Skip to content

MCP OAuth authorization

OAuth fits when you offer the Gateway’s MCP services to outside users and do not want them to paste an API key. A user clicks connect in ChatGPT, Claude, Codex or another client, signs in to your business system and approves, and the client receives a token that can only access MCP. Existing API-key access keeps working.

Open the Client access & authorization section on the MCP Servers page and find the OAuth 2.0 sign-in (optional) card. Choose one mode:

ModeWhen to use it
Built-in authorization serverRecommended. The Gateway registers clients and issues and refreshes tokens itself. Your business system only handles sign-in and consent and stores no OAuth state.
External authorization serverYou already run an authorization server that issues gateway tokens through the Admin API. The Gateway only serves resource metadata.
OffNo OAuth discovery. Clients connect with an API key.

OAuth applies only to the MCP entry points. It does not authorize general model APIs or relay an upstream server’s OAuth flow. Business accounts must map to gateway users so usage is charged to the right user.

  1. Prepare the application directory: under Applications in the OAuth access tokens area, use Import preset to add ChatGPT, Claude, Codex, Doubao or WorkBuddy, or add an application manually. Clients are matched to an application by redirect URI at registration; clients with no matching application cannot register.
  2. Prepare a sign-in and consent page: provide a page in your business system that receives the request_id appended by the Gateway, confirms the user is signed in, reports the user’s approval or denial to the Gateway with an integration key that has the oauth.consent permission, and redirects back to the client using the returned address. To skip your own site, leave it empty and use the built-in page, where users approve with their own API key.
  3. Forward authorization paths: have the reverse proxy forward /oauth/* and /.well-known/oauth-authorization-server to Proxy on the same public domain as /mcp.
  4. Save: select Built-in authorization server, fill in Public URL of this Gateway (issuer) and, optionally, Sign-in and consent page, then save.
  5. Verify with real clients: complete authorization, a tool call, refresh and revocation for each client, and check that request logs show the right application and user.

When switching from an external server, existing grants stop working once their access tokens expire, and users must authorize again. See the 0036 migration notes for the full steps.

  • oat_ access tokens are stored separately from user API keys, only permit /mcp and its subpaths, and last one hour by default.
  • Built-in mode also issues refresh tokens (30 days, single use). Clients refresh automatically, so users do not sign in every hour. Reusing a refresh token is treated as a leak and revokes the whole grant.
  • The OAuth access tokens area summarizes users, instances and grants per application. You can disable an application, revoke all of its grants, or filter details by application, user or status (active, renewable, expired, revoked). User details also list that user’s grants below the API Keys tab.
  • Older grants issued by an external server appear as Unattributed and can be revoked individually.
  • Switching to Off only stops OAuth discovery; it does not revoke issued tokens. Revoke grants to stop their use immediately.
  • A client cannot register: check that an enabled application exists and its redirect URIs match what the client uses.
  • The flow stops at the consent page: confirm the page reads request_id and the integration key has oauth.consent. Authorization requests last 10 minutes; start again from the client after they expire.
  • A 401 means the client needs a new or refreshed token. An MCP token is rejected (403) on chat and other endpoints because its scope is limited.

See the OAuth technical reference for endpoints, the object model and the consent API.