Skip to content

OAuth for MCP clients

OAuth: the authorization server 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: every method as an MCP tool and a CLI command, “The MCP endpoint”) sign in by MCP’s authorization spec instead (MCP's Authorization spec, MCP's Authorization spec (2025-11-25)): 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.

This section is informative.

FileDescriptionLicence
MCP's Authorization specMCP’s authorization, 2026-07-28Apache-2.0 or MIT, mcp/LICENSE
MCP's Authorization spec (2025-11-25)the same, 2025-11-25Apache-2.0 or MIT, mcp/LICENSE
RFC 8414authorization server metadataIETF Trust
RFC 6750bearer tokens and WWW-AuthenticateIETF Trust
the client ID metadata document draftclient ID metadata documentsIETF Trust

With <origin> the origin of PDS_PUBLIC_URL, the atproto issuer (OAuth: the authorization server, “The issuer”):

NameDescription
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

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: the authorization server).

GET /.well-known/oauth-authorization-server/oauth/mcp answers 200 application/json, with the CORS headers of OAuth: the authorization server’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.

An MCP client is named by an https:// client_id whose document the server fetches as OAuth: web, native and confidential clients 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: web, native and confidential clients 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: what the authorization pages show 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: web, native and confidential clients 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.

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

ParameterDescription
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: the authorization server’s PAR takes it, with atproto; left out, atproto transition:generic
stateoptional
login_hint, prompt, ui_localesoptional, as OAuth: the authorization server’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: the authorization server’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: the authorization server, OAuth: what the authorization pages show), as for any request. Its redirect back carries iss the MCP issuer, and the code it gives is the MCP issuer’s.

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: the authorization server’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: the authorization server 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: the authorization server’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.

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.

POST /mcp takes an MCP session’s access token as Authorization: Bearer <token>, the scheme in any case, in either era (Commands: every method as an MCP tool and a CLI command). 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: access tokens on every method, and what scopes allow 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: access tokens on every method, and what scopes allow, “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: access tokens on every method, and what scopes allow 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: every method as an MCP tool and a CLI command 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: the authorization server 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.

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

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: web, native and confidential clients, “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: the authorization server’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).