# OAuth for MCP clients [`OAUTH.md`](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.* | File | Is | Licence | | --- | --- | --- | | `mcp/basic/authorization/` | MCP's authorization, `2026-07-28` | Apache-2.0 or MIT, `mcp/LICENSE` | | `mcp/legacy/2025-11-25/basic/authorization.md` | the same, `2025-11-25` | Apache-2.0 or MIT, `mcp/LICENSE` | | `rfc/rfc8414.txt` | authorization server metadata | IETF Trust | | `rfc/rfc6750.txt` | bearer tokens and `WWW-Authenticate` | IETF Trust | | `rfc/draft-client-id-metadata-document.txt` | client ID metadata documents | IETF Trust | ## Names With `` the origin of `PDS_PUBLIC_URL`, the atproto issuer (`OAUTH.md`, "The issuer"): | Name | Is | | --- | --- | | the **resource** | `/mcp`, the MCP endpoint | | the **MCP issuer** | `/oauth/mcp` | | `/.well-known/oauth-protected-resource/mcp` | the resource's metadata | | `/.well-known/oauth-authorization-server/oauth/mcp` | the MCP issuer's metadata | | `/oauth/mcp/authorize` | its authorization endpoint | | `/oauth/mcp/token` | its token endpoint | | `/oauth/mcp/revoke` | its revocation endpoint | ## Metadata `GET /.well-known/oauth-protected-resource/mcp` answers `200 application/json`, with `Access-Control-Allow-Origin: *`: ```json {"resource": "/mcp", "authorization_servers": ["/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: | Field | Value | | --- | --- | | `issuer` | `/oauth/mcp` | | `authorization_endpoint` | `/oauth/mcp/authorize` | | `token_endpoint` | `/oauth/mcp/token` | | `revocation_endpoint` | `/oauth/mcp/revoke` | | `scopes_supported` | as 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_supported` | `true` | | `authorization_response_iss_parameter_supported` | `true` | | `protected_resources` | `["/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): | Parameter | Is | | --- | --- | | `response_type` | `code` | | `client_id` | the client | | `redirect_uri` | one of the client's; may be left out when it has exactly one | | `code_challenge`, `code_challenge_method` | PKCE, `S256` | | `resource` | the resource, `/mcp`; its scheme and host in any case | | `scope` | optional: a scope string as `OAUTH.md`'s PAR takes it, with `atproto`; left out, `atproto transition:generic` | | `state` | optional | | `login_hint`, `prompt`, `ui_locales` | optional, 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: 3. `response_type` `code`: else `unsupported_response_type`. 4. `code_challenge` given and `code_challenge_method` `S256`: else `invalid_request`. 5. `resource` the resource: else `invalid_target` (RFC 8707). 6. `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=&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`: ```json {"access_token": "", "token_type": "Bearer", "refresh_token": "", "scope": "", "expires_in": 900, "sub": ""} ``` 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 `, 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="/.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="", resource_metadata="…", error_description=""`: 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:/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`).