~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
330 lines · 16.5 KB Raw History

OAuth for MCP clients

OAUTH.md makes the server the authorization server for its accounts as atproto's OAuth profile has it: pushed requests, DPoP-bound tokens, and client metadata that declares atproto and DPoP. MCP clients (COMMANDS.md, "The MCP endpoint") sign in by MCP's authorization spec instead (mcp/basic/authorization/, mcp/legacy/2025-11-25/basic/authorization.md): they find the authorization server from the MCP endpoint's protected resource metadata, name themselves by a client ID metadata document that declares neither, send the browser straight to the authorization endpoint with PKCE and an RFC 8707 resource, and call the endpoint with a bearer token. This page is a second issuer on the same server for them, the MCP issuer, beside the atproto one, which it leaves as it is. An account signs in on the same pages, and grants the same scopes; what it is given is a token for the MCP endpoint alone.

Sources

This section is informative.

FileIsLicence
mcp/basic/authorization/MCP's authorization, 2026-07-28Apache-2.0 or MIT, mcp/LICENSE
mcp/legacy/2025-11-25/basic/authorization.mdthe same, 2025-11-25Apache-2.0 or MIT, mcp/LICENSE
rfc/rfc8414.txtauthorization server metadataIETF Trust
rfc/rfc6750.txtbearer tokens and WWW-AuthenticateIETF Trust
rfc/draft-client-id-metadata-document.txtclient ID metadata documentsIETF Trust

Names

With <origin> the origin of PDS_PUBLIC_URL, the atproto issuer (OAUTH.md, "The issuer"):

NameIs
the resource<origin>/mcp, the MCP endpoint
the MCP issuer<origin>/oauth/mcp
/.well-known/oauth-protected-resource/mcpthe resource's metadata
/.well-known/oauth-authorization-server/oauth/mcpthe MCP issuer's metadata
/oauth/mcp/authorizeits authorization endpoint
/oauth/mcp/tokenits token endpoint
/oauth/mcp/revokeits revocation endpoint

Metadata

GET /.well-known/oauth-protected-resource/mcp answers 200 application/json, with Access-Control-Allow-Origin: *:

{"resource": "<origin>/mcp", "authorization_servers": ["<origin>/oauth/mcp"],
 "scopes_supported": ["atproto", "transition:generic"],
 "bearer_methods_supported": ["header"], "resource_documentation": "https://atproto.com"}

The root document, /.well-known/oauth-protected-resource, stays the atproto one (OAUTH.md).

GET /.well-known/oauth-authorization-server/oauth/mcp answers 200 application/json, with the CORS headers of OAUTH.md's metadata:

FieldValue
issuer<origin>/oauth/mcp
authorization_endpoint<origin>/oauth/mcp/authorize
token_endpoint<origin>/oauth/mcp/token
revocation_endpoint<origin>/oauth/mcp/revoke
scopes_supportedas the atproto issuer's
response_types_supported["code"]
response_modes_supported["query"]
grant_types_supported["authorization_code", "refresh_token"]
code_challenge_methods_supported["S256"]
token_endpoint_auth_methods_supported["none"]
client_id_metadata_document_supportedtrue
authorization_response_iss_parameter_supportedtrue
protected_resources["<origin>/mcp"]

and no other field: no PAR, no DPoP, no registration_endpoint, no offline_access. The atproto issuer's metadata is unchanged.

Clients

An MCP client is named by an https:// client_id whose document the server fetches as OAUTH-CLIENTS.md says ("Client IDs", and "The document": fetching it, its size, time and cache, the development fetch). The document is then held to MCP's rules, not atproto's:

  1. A JSON object whose client_id is the client_id, character for character.
  2. redirect_uris a non-empty array of URIs, each an https: URL; an http: URL whose host is 127.0.0.1, [::1] or localhost; or a private-use scheme URI, as OAUTH-CLIENTS.md forms them; none with a user, password or fragment.
  3. token_endpoint_auth_method none: the client is public. Left out, it is RFC 7591's client_secret_basic, which the MCP issuer does not take.
  4. grant_types, if given, including authorization_code; response_types, if given, including code.

Every other field is optional and of no effect but as the page shows it (client_name, client_uri, logo_uri, tos_uri, policy_uri, as OAUTH-PAGES.md shows an https:// client's): no scope, dpop_bound_access_tokens or application_type is asked for. A document that fails these is invalid_client_metadata; a client_id that is not an https:// one as OAUTH-CLIENTS.md has it is invalid_client. A redirect_uri matches one of the document's if equal, or if both are on the same loopback host (127.0.0.1, [::1] or localhost), the document's has no port, and they are equal but for the port.

The client gets a refresh token when its grant_types includes refresh_token.

The authorization request

GET /oauth/mcp/authorize takes its parameters in the query (RFC 6749 §4.1.1, without PAR):

ParameterIs
response_typecode
client_idthe client
redirect_urione of the client's; may be left out when it has exactly one
code_challenge, code_challenge_methodPKCE, S256
resourcethe resource, <origin>/mcp; its scheme and host in any case
scopeoptional: a scope string as OAUTH.md's PAR takes it, with atproto; left out, atproto transition:generic
stateoptional
login_hint, prompt, ui_localesoptional, as OAUTH.md's PAR takes them

A parameter given twice is refused. It is checked in this order:

  1. client_id given, an https:// client whose document passes the rules above: else a 400 error page, as the atproto page answers a request it cannot take.
  2. redirect_uri one of the client's: else a 400 error page.

Past those, a refusal is a redirect to the redirect_uri with error, error_description, iss (the MCP issuer) and state if given, as RFC 6749 §4.1.2.1 has it:

  1. response_type code: else unsupported_response_type.
  2. code_challenge given and code_challenge_method S256: else invalid_request.
  3. resource the resource: else invalid_target (RFC 8707).
  4. scope a scope string with atproto: else invalid_scope.

The request is then kept as OAUTH.md's PAR keeps one, for 300 seconds, marked as the MCP issuer's, with its resource and no DPoP key, and the answer is 303 to /oauth/authorize?client_id=<client_id>&request_uri=<request_uri>: the authorization page, its API and its redirect (OAUTH.md, OAUTH-PAGES.md), as for any request. Its redirect back carries iss the MCP issuer, and the code it gives is the MCP issuer's.

The token endpoint

POST /oauth/mcp/token takes a form or JSON as /oauth/token does, and its answers carry Cache-Control: no-store and Pragma: no-cache. It takes no DPoP proof: a DPoP header is not read. It checks, in this order, each failure 400:

  1. The body, as /oauth/token's.
  2. client_id present: else invalid_request; an MCP client as above: else invalid_client.
  3. grant_type authorization_code with code, redirect_uri and code_verifier, or refresh_token with refresh_token: else invalid_request, or unsupported_grant_type for another grant.
  4. resource, if given, the resource: else invalid_target.

The code grant then checks, all invalid_grant, as OAUTH.md's does but for the DPoP key: the code one the MCP issuer gave, not spent and less than 300 seconds old (a code used twice ends the session the first made); its request's client this one; redirect_uri the request's; code_verifier's SHA-256, base64url, the request's code_challenge; and the account neither taken down nor deactivated. A code the atproto issuer gave is not one the MCP issuer gave, nor the other way about. It answers 200:

{"access_token": "<token>", "token_type": "Bearer", "refresh_token": "<token>",
 "scope": "<the scope, as kept and narrowed at consent, its include: scopes expanded>",
 "expires_in": 900, "sub": "<the account's DID>"}

with no refresh_token for a client without that grant, and starts an MCP session: an OAuth session as OAUTH.md keeps one, with no DPoP key, marked as the MCP issuer's.

The refresh grant is first refused 400 unauthorized_client for a client whose grant_types does not include refresh_token, before its refresh_token is looked at: such a client is given no refresh token ("Clients"), and takes no refresh grant. Past that, it is OAUTH.md's, but for the DPoP key: a refresh token of an MCP session, its current one; a replaced one, or another client's, refused and the session ended; the session not past two weeks from its start. It answers as the code grant, replacing both tokens.

Revocation

POST /oauth/mcp/revoke takes a form or JSON with client_id and token, as /oauth/revoke does but with no DPoP proof, and answers 200 {} whatever the token. If the token is an MCP session's current access token, its current or a replaced refresh token, and the session is this client's, the session ends.

Tokens at the MCP endpoint

POST /mcp takes an MCP session's access token as Authorization: Bearer <token>, the scheme in any case, in either era (COMMANDS.md). A token that is its session's current one, unexpired, the session not ended, makes the call the account's, as an OAuth access token makes an XRPC call: with the session's scope, as OAUTH-SCOPES.md says of each method, and a method that takes no OAuth token refusing it as it refuses one there.

The endpoint answers HTTP 401 with a WWW-Authenticate: Bearer challenge, not a JSON-RPC answer, in two cases, so that a client signs in:

  • No token. A tools/call with no Authorization header whose method, called so over XRPC, answers 401 AuthMissing: the challenge is Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp", scope="atproto transition:generic". (A method that answers 401 AuthenticationRequired there wants the admin, whom no sign-in makes: it is a tool error, as before.)
  • A token the MCP issuer gave that no longer works: expired, replaced, revoked, its session ended: Bearer error="invalid_token", resource_metadata="…", so that the client refreshes or signs in again.

The body is {"error": "invalid_token", "error_description": "…"}.

With a token that works, a call its scope does not allow is HTTP 403, so that the client asks the account for more (MCP's step-up, "Scope Challenge Handling"): where the method, called as an XRPC call with an OAuth token of that scope, answers 403 ScopeMissingError naming the scope that would allow it (OAUTH-SCOPES.md, "The refusal"), the challenge is Bearer error="insufficient_scope", scope="<the token's scope, then what it lacks>", resource_metadata="…", error_description="<the error's message>": the token's scope as its token answer gave it, its tokens in order; then each scope the call needs that it does not allow and that is not already there: the one the error names, and, for a repository write, the others its input needs, in the order OAUTH-SCOPES.md asks them (putRecord both create and update); separated by single spaces, so that one sign-in grants all the call needs. The body is {"error": "insufficient_scope", "error_description": "…"}. A method that takes no OAuth token at all, as the app password methods, is not refused for its scope: no sign-in grants it, and its refusal is a tool error, as XRPC answers it.

Any other call is answered as COMMANDS.md says: a tool that needs no account works with no token, and a token the server did not give out, or a password session's, is taken as XRPC takes it.

An MCP session's access token is for the MCP endpoint alone. On XRPC it is not a token the server gave out as Bearer: 400 InvalidToken, as OAUTH.md says of an OAuth access token sent so; and with the DPoP scheme, 401 invalid_token. Its refresh token is refused at /oauth/token, and an atproto session's at /oauth/mcp/token.

Lifecycle and durability

An MCP session is an OAuth session: a change of its account's state ends it as LIFECYCLE.md says ("OAuth sessions"), deleteAccount with it; the pages' sign-out signs the account out of that device alone (OAUTH.md, "The API") and ends no session; and it survives the server being killed as OAUTH.md says ("Durability").

How it is checked

node compare.mjs --commands ... signs an account in as Claude does, after the tool checks, on the server alone, as the reference has no MCP endpoint. The client web (OAUTH-CLIENTS.md, "How it is checked") publishes a document of Claude's shape, a public client with no scope, dpop_bound_access_tokens or application_type, whose redirect URIs are an https: one and http://localhost/callback. Then:

  • tools/call repo_create_record with no token: 401, the challenge as above; and server_describe_server with no token answers as before.
  • The two metadata documents, exactly as above; the root resource metadata and the atproto issuer's, unchanged.
  • /oauth/mcp/authorize with the https: redirect URI: 303 to the page; the page signs in and consents as OAUTH.md's checks do; its redirect carries code, state and iss the MCP issuer. Again with http://localhost:<port>/callback, a port the document does not name.
  • The code at /oauth/mcp/token, form-encoded, no DPoP: Bearer, 900 seconds, the scope, a refresh token. Then /mcp with it: server_get_session is the account, and repo_create_record writes a record XRPC then reads.
  • The token on XRPC: 400 InvalidToken as Bearer, 401 invalid_token as DPoP. The refresh token at /oauth/token, and the code exchanged there, refused.
  • The refresh grant: new tokens; the old access token at /mcp the invalid_token challenge; the old refresh token refused, and the session ended, so the new access token is challenged too.
  • Revocation ends a session.
  • A client whose grant_types is authorization_code alone: its code grant answers no refresh_token, and a refresh grant from it, with any refresh_token, 400 unauthorized_client.
  • Step-up: an account signed in with atproto repo:com.example.other alone; repo_put_record to com.example.note with that token: 403, Bearer error="insufficient_scope", scope="atproto repo:com.example.other repo:com.example.note?action=create repo:com.example.note?action=update", resource_metadata="…"; signed in again with that scope, the same call writes. server_create_app_password with the narrow token is a tool error, not a challenge.
  • Refusals: no resource, or another, invalid_target; no PKCE, or plain, invalid_request; a scope without atproto, invalid_scope, each a redirect with iss; a document whose client_id is another URL, or with token_endpoint_auth_method left out, an error page; a redirect_uri the document does not name, an error page; a wrong code_verifier, invalid_grant.
  • Lifecycle, on accounts of their own made on both sides: an MCP session, and a code approved and not exchanged, before an admin takedown; the session ended after it (/mcp the invalid_token challenge, refresh 400 invalid_grant), still ended once it is lifted, and the code refused; a new session ended by lifting it again from an account not down. The pages' sign-out on the device the session was made on: the session still calls a tool. A deactivation by the password session: the MCP session answers server_check_account_status and repo_create_record as the password token does at /mcp, refreshes, and works after activateAccount, the code refused; one by an MCP session of scope account:status?action=manage: that session and the other ended, before and after activation. deleteAccount with its mailed token: the session ended. The deletion is left out of runs with --firehose, whose replay checks would have to drop its events.
  • With --crash-every, before each kill, on an account with a password: a session refreshed, a code approved, a session ended by revocation or by its replaced refresh token sent again; after the restart the replaced access token refused, the refreshed session calling a tool and refreshing, the code exchanged, the ended session ended, and the device consenting without signing in again.

node conformance.mjs runs MCP's conformance suite's authorization-server-metadata-endpoint against the MCP issuer.

Not checked: Claude itself, which reaches only a server on the internet (docs/guide/deploying.md).