chadtmiller.com/monolith
An atproto PDS
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.
| 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 <origin> the origin of PDS_PUBLIC_URL, the atproto issuer
(OAUTH.md, "The issuer"):
| Name | Is |
|---|---|
| the resource | <origin>/mcp, the MCP endpoint |
| the MCP issuer | <origin>/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: *:
{"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:
| Field | Value |
|---|---|
issuer | <origin>/oauth/mcp |
authorization_endpoint | <origin>/oauth/mcp/authorize |
token_endpoint | <origin>/oauth/mcp/token |
revocation_endpoint | <origin>/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 | ["<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:
- A JSON object whose
client_idis theclient_id, character for character. redirect_urisa non-empty array of URIs, each anhttps:URL; anhttp:URL whose host is127.0.0.1,[::1]orlocalhost; or a private-use scheme URI, asOAUTH-CLIENTS.mdforms them; none with a user, password or fragment.token_endpoint_auth_methodnone: the client is public. Left out, it is RFC 7591'sclient_secret_basic, which the MCP issuer does not take.grant_types, if given, includingauthorization_code;response_types, if given, includingcode.
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, <origin>/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:
client_idgiven, anhttps://client whose document passes the rules above: else a400error page, as the atproto page answers a request it cannot take.redirect_urione of the client's: else a400error 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:
response_typecode: elseunsupported_response_type.code_challengegiven andcode_challenge_methodS256: elseinvalid_request.resourcethe resource: elseinvalid_target(RFC 8707).scopea scope string withatproto: elseinvalid_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:
- The body, as
/oauth/token's. client_idpresent: elseinvalid_request; an MCP client as above: elseinvalid_client.grant_typeauthorization_codewithcode,redirect_uriandcode_verifier, orrefresh_tokenwithrefresh_token: elseinvalid_request, orunsupported_grant_typefor another grant.resource, if given, the resource: elseinvalid_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/callwith noAuthorizationheader whose method, called so over XRPC, answers401 AuthMissing: the challenge isBearer resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp", scope="atproto transition:generic". (A method that answers401 AuthenticationRequiredthere 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_recordwith no token:401, the challenge as above; andserver_describe_serverwith no token answers as before.- The two metadata documents, exactly as above; the root resource metadata and the atproto issuer's, unchanged.
/oauth/mcp/authorizewith thehttps:redirect URI:303to the page; the page signs in and consents asOAUTH.md's checks do; its redirect carriescode,stateandissthe MCP issuer. Again withhttp://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/mcpwith it:server_get_sessionis the account, andrepo_create_recordwrites a record XRPC then reads. - The token on XRPC:
400 InvalidTokenasBearer,401 invalid_tokenasDPoP. The refresh token at/oauth/token, and the code exchanged there, refused. - The refresh grant: new tokens; the old access token at
/mcptheinvalid_tokenchallenge; 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_typesisauthorization_codealone: its code grant answers norefresh_token, and a refresh grant from it, with anyrefresh_token,400 unauthorized_client. - Step-up: an account signed in with
atproto repo:com.example.otheralone;repo_put_recordtocom.example.notewith 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_passwordwith the narrow token is a tool error, not a challenge. - Refusals: no
resource, or another,invalid_target; no PKCE, orplain,invalid_request; a scope withoutatproto,invalid_scope, each a redirect withiss; a document whoseclient_idis another URL, or withtoken_endpoint_auth_methodleft out, an error page; aredirect_urithe document does not name, an error page; a wrongcode_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 (
/mcptheinvalid_tokenchallenge, refresh400 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-outon the device the session was made on: the session still calls a tool. A deactivation by the password session: the MCP session answersserver_check_account_statusandrepo_create_recordas the password token does at/mcp, refreshes, and works afteractivateAccount, the code refused; one by an MCP session of scopeaccount:status?action=manage: that session and the other ended, before and after activation.deleteAccountwith 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).