Two authentication planes
The MCP transport accepts bearer credentials only, not browser session cookies. Organization management APIs use an authenticated application session, tenant middleware, owner/admin authorization and CSRF protection; MCP bearer tokens cannot administer those APIs.
Connections act as their real issuing owner/admin within the original organization. Current role, active status, revocation, expiry and policy are rechecked. Changing the issuer's browser organization never changes the connection's tenant.
OAuth discovery
Use the WWW-Authenticate resource metadata URL returned by an unauthenticated MCP request. Do not fabricate discovery paths or issuer URLs. The authorization server publishes protected-resource and authorization-server metadata, including its registration, authorization and token endpoints.
The flow is:
- Discover the resource and issuer; validate origins and supported capabilities.
- Register a public or supported confidential client with approved HTTPS callback URLs. Loopback exceptions, where accepted by validation, are for local clients only.
- Use authorization-code flow with PKCE S256, a fresh verifier and
state, the registered redirect URI, and the MCP resource binding. - An authenticated human owner/admin reviews client name, callback origin, modules and read/guarded-write access. Names are self-declared; they are not provider identity proof.
- Exchange the one-use code using the same client, redirect, resource and PKCE verifier. Confidential clients also authenticate using their registered method.
- Send access tokens to the MCP endpoint in the Authorization header.
- Rotate refresh tokens atomically. Retain only the newly returned refresh token. Refresh can narrow, not expand, permission.
Access tokens last one hour. Refresh tokens have a maximum 30-day lifetime and are bounded by a grant lasting at most 90 days. Expired grants must be linked again. Reuse of an old refresh token revokes the token family; do not use concurrent independent refresh loops for one grant.
Authorization denial, invalid PKCE, redirect/resource mismatch, code reuse and token replay must be surfaced to the user, not worked around with bearer-token sharing.
Organization client restrictions
When restrictClients is enabled, an actual OAuth registration ID must appear in approvedClientIds. Manual bearer connections are not approved OAuth registrations and are blocked by this setting. New registrations are not automatically approved. Administrator review of registration IDs, redirects and authentication methods is required.
This pins approved registrations; it does not cryptographically attest that a client belongs to OpenAI, Anthropic, Google or Microsoft. Provider account eligibility and consumer-host support still require real-provider testing.
Legacy bearer credentials
Admin-issued connection credentials remain supported for compatible clients. Only hashes are stored; the original token cannot be recovered. Use a short expiry, narrow permissions and immediate revocation when no longer needed. Do not store tokens in source-controlled client configurations.
Client-specific configuration examples remain in the operational guide. OAuth consent is not approval of any later business mutation.
Download this guide as Markdown.