One read of Claude Documentationclaude-docs-20261104T160705Z
3 pages moved out of 281 read.
Pages moved
3
significant first
Pages read
281
in this capture
Captured
16:07 UTC
Corpus hash
0f51b7b203c0
corpus-hash
What this read moved
1-3 of 3connectors/building/authentication Changed · +5 / -4 lines
from line 14
1414
1515* A `401` is required to start sign-in, and Claude ignores a `WWW-Authenticate` header on a `200` response, as [Serve discovery metadata](#serve-discovery-metadata) describes
1616* Claude uses only the first entry in your metadata's `authorization_servers` list, as [Serve discovery metadata](#serve-discovery-metadata) describes
17* Claude uses a Client ID Metadata Document only when your authorization server metadata advertises both values in [DCR and CIMD details](#dcr-and-cimd-details), and otherwise falls back to DCR
17* Claude normally uses a Client ID Metadata Document only when your authorization server metadata advertises both values in [DCR and CIMD details](#dcr-and-cimd-details), and otherwise falls back to DCR
1818* Claude Code's loopback redirect needs a port-agnostic match for `localhost` as well as `127.0.0.1`, as [Callback URLs](#callback-urls) describes
1919* Claude gives your discovery, registration, and token endpoints 10 seconds to respond and refresh requests 30 seconds, as [Endpoint latency](#endpoint-latency) describes
2020* A machine-to-machine `client_credentials` grant isn't supported, and [Anthropic-held client credentials](#anthropic-held-client-credentials) are the consent-gated alternative
from line 85
8585If your authorization server doesn't support DCR, meaning it exposes no `registration_endpoint`, you have these options:
8686
8787* Expose a `registration_endpoint`
88* Support CIMD instead. Claude selects CIMD only when your authorization server metadata advertises both `"client_id_metadata_document_supported": true` and `"none"` in `token_endpoint_auth_methods_supported`. The second is required because Claude's CIMD client authenticates as a public client at your token endpoint. If either is missing, Claude falls back to DCR. See [lazy authentication](https://claude.com/docs/connectors/building/lazy-authentication.md#identify-claude-with-a-client-id-metadata-document) for a worked CIMD example
88* Support CIMD instead. Claude normally selects CIMD only when your authorization server metadata advertises both `"client_id_metadata_document_supported": true` and `"none"` in `token_endpoint_auth_methods_supported`, and otherwise falls back to DCR. The second value is required because Claude's CIMD client authenticates as a public client at your token endpoint in that case. If your metadata lists `private_key_jwt`, Claude can instead present a second metadata document, whose URL ends in `/confidential_client`, and authenticate with a signed client assertion. On [Enterprise Managed Auth](https://claude.com/docs/connectors/building/enterprise-managed-auth.md) exchanges it can do this even when `"none"` isn't listed, and on other sign-ins only for some servers. See [lazy authentication](https://claude.com/docs/connectors/building/lazy-authentication.md#identify-claude-with-a-client-id-metadata-document) for a worked CIMD example
8989* Switch to `oauth_anthropic_creds`, if your listing doesn't use a URL pattern
9090
91If your server URL varies per customer and DCR isn't available, CIMD is the recommended path. Every customer's authorization server must advertise both CIMD values. Otherwise Claude falls back to DCR for that customer, which needs a `registration_endpoint`.
91If your server URL varies per customer and DCR isn't available, CIMD is the recommended path. Every customer's authorization server must advertise both CIMD values. Otherwise Claude normally falls back to DCR for that customer, which needs a `registration_endpoint`.
9292
9393For servers expecting high traffic from the directory, prefer CIMD or `oauth_anthropic_creds` over DCR. DCR causes Claude to register a new client on every fresh connection, which can result in very large numbers of registered clients on your authorization server. CIMD and Anthropic-held credentials avoid the registration call entirely.
9494
from line 134
134134* **Some connections, such as older ones**: these don't use the client you entered. They use the organization's or Anthropic's client if either exists, and otherwise your server's own [DCR or CIMD](#dcr-and-cimd-details) registration. If there's no such client and your server supports neither, sign-in fails for those connections
135135* **A client Anthropic already holds**: if Anthropic holds a client for any of your listing's URLs, you can't save your client secret or request header values on a published listing. You can save them once Anthropic removes its client or checks your listing again. On a listing that isn't published yet, you can save them, but the listing can't go live until Anthropic checks it. In either case, email `[email protected]` with your listing's name and its exact server URLs, and don't put the secret in the email
136136* **Custom connectors**: a custom connector that someone adds with your server's URL never uses the client secret you entered in the portal
137* **Enterprise Managed Auth sign-ins**: these don't use the client you entered in the developer portal. For how to register Claude for those sign-ins, see [Enterprise Managed Auth prerequisites](https://claude.com/docs/connectors/building/enterprise-managed-auth.md#prerequisites)
137138
138139For each request header on your listing, select the **Anthropic holds one shared value** checkbox in the developer portal to enter one value yourself that every organization uses. Leave it unchecked so each person who adds your connector enters their own value. You can't select the checkbox on a listing with a [URL pattern](#servers-with-per-customer-urls). Header values come only from you or from the people who add your connector, never from Anthropic.
139140
from line 226
225226Claude refreshes tokens reactively on a `401` response, and proactively up to five minutes before the stored expiry. To avoid refresh failures:
226227
227228* Return RFC 6749-compliant error codes when a refresh token is no longer valid: `invalid_grant`, not `invalid_request` or a custom code
228* Rotate refresh tokens for public-client connections. DCR and CIMD register Claude as a public client, and the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#token-theft) adopts OAuth 2.1's requirement to rotate or sender-constrain refresh tokens for public clients. If you rotate, return the new refresh token in the same response that invalidates the old one
229* Rotate refresh tokens for public-client connections. DCR registers Claude as a public client, and CIMD normally does too. The [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#token-theft) adopts OAuth 2.1's requirement to rotate or sender-constrain refresh tokens for public clients. If you rotate, return the new refresh token in the same response that invalidates the old one
229230
230231Your `/token` endpoint must accept `Content-Type: application/x-www-form-urlencoded` per [RFC 6749 section 4.1.3](https://www.rfc-editor.org/rfc/rfc6749#section-4.1.3). Claude sends both the initial token exchange and refresh requests with this content type. Some web frameworks default to JSON-only body parsing, so if your endpoint returns `415 Unsupported Media Type`, register a form-urlencoded body parser. Dynamic client registration at `/register` uses `application/json` per [RFC 7591 section 3.1](https://www.rfc-editor.org/rfc/rfc7591#section-3.1), so don't assume the same parser works for both.
231232
connectors/building/enterprise-managed-auth Changed · +12 / -2 lines
from line 32
3232Before adding Enterprise Managed Auth, make sure the following are already in place:
3333
3434* Your MCP server implements [MCP authorization](https://modelcontextprotocol.io/specification/draft/basic/authorization), including Protected Resource Metadata (PRM) discovery. See the [authentication guide](https://claude.com/docs/connectors/building/authentication.md) for Claude-specific requirements
35* Your authorization server registers Claude using either [Anthropic-held client credentials](https://claude.com/docs/connectors/building/authentication.md#anthropic-held-client-credentials) or a [Client ID Metadata Document](https://claude.com/docs/connectors/building/authentication.md#dcr-and-cimd-details)
35* Your authorization server registers Claude using either a client that Anthropic set up for your server's URL, as [Which credentials Claude uses when several are set](https://claude.com/docs/connectors/building/authentication.md#which-credentials-claude-uses-when-several-are-set) describes, or a [Client ID Metadata Document](https://claude.com/docs/connectors/building/authentication.md#dcr-and-cimd-details). Enterprise Managed Auth sign-ins don't use a client ID and secret that you entered in the developer portal. If that is how Claude is registered with you, email `[email protected]` with your listing's name and its exact server URLs before you ask to have your listing marked as supporting Enterprise Managed Auth, and don't put the secret in the email
3636
3737Enterprise Managed Auth works with [lazy authentication](https://claude.com/docs/connectors/building/lazy-authentication.md). When your MCP server answers a tool call with `401 Unauthorized` and the user's organization has Enterprise Managed Auth configured for your connector, Claude runs the exchange and retries the call instead of showing the **Connect** card.
3838
from line 95
9595&resource=https://mcp.example.com
9696```
9797
98Client authentication is left out of this example. The `client_id` is the value Claude is registered under at your authorization server, which for a Client ID Metadata Document is the document's URL. If that client has a secret or key, require it on this request. Answer at the `token_endpoint` URL itself, because Claude doesn't follow redirects on this request.
98Client authentication is left out of this example. Answer at the `token_endpoint` URL itself, because Claude doesn't follow redirects on this request. The `client_id` is the value Claude is registered under at your authorization server, which for a Client ID Metadata Document is the document's URL. If that client has a secret or key, require it on this request:
99
100* **Client secret**: Claude sends the secret in the request body, so accept `client_secret_post` for this client
101* **Signed client assertion**: if Claude is registered with you through its Client ID Metadata Document and your authorization server metadata lists `private_key_jwt` in `token_endpoint_auth_methods_supported`, Claude can send this request as a second client, `https://claude.ai/oauth/mcp-oauth-client-metadata/confidential_client`, with a signed client assertion. Accept that `client_id` as well as the public document's URL, and verify the client assertion with the keys at the `jwks_uri` in the `confidential_client` document
102
103The **Client** check in [Validate the identity assertion](#validate-the-identity-assertion) compares the assertion's `client_id` claim with this request's `client_id`:
104
105* **Claude-issued**: the claim names the client that sends this request
106* **Identity provider-issued**: the claim is the client ID that the customer's administrator registered for your connector in their identity provider. Claude's managed authorization setup gives the identity provider's setup the client ID that Claude presents on this request, so the two values should match when the administrator registers your connector through it. An administrator who registers your connector another way must enter the client ID that Claude presents on this request, so name it in your setup documentation
107
108Adding or removing `private_key_jwt` in `token_endpoint_auth_methods_supported` changes which client Claude presents through its metadata document. After customers are set up, that change can make their identity provider-issued sign-ins fail the **Client** check until each administrator runs Claude's managed authorization setup again or enters the new client ID in their identity provider. Tell administrators before you make it.
99109
100110A Claude-issued request always carries the `resource` parameter ([Resource Indicators, RFC 8707](https://www.rfc-editor.org/rfc/rfc8707)), set to the `resource` in your Protected Resource Metadata when that is your MCP server's URL or a parent of it, and otherwise to your MCP server's URL. An identity provider-issued request carries it whenever the customer's identity provider supports forwarding it. Accept the request whether or not `resource` is present, and use it for audience binding when it is.
101111
connectors/building/lazy-authentication Changed · +1 / -1 lines
from line 205
205205
206206> [!NOTE]
207207>
208> Claude selects CIMD only when the authorization-server metadata advertises both `client_id_metadata_document_supported: true` and `"none"` in `token_endpoint_auth_methods_supported`. The second is required because Claude's CIMD client authenticates as a public client with `token_endpoint_auth_method: "none"`, so the token endpoint must accept [PKCE](https://datatracker.ietf.org/doc/html/rfc7636)-only requests without a client secret. If either property is missing, Claude falls back to looking for a `registration_endpoint`.
208> Claude normally selects CIMD only when the authorization-server metadata advertises both `client_id_metadata_document_supported: true` and `"none"` in `token_endpoint_auth_methods_supported`, and otherwise looks for a `registration_endpoint`. The second property is required because Claude's CIMD client authenticates as a public client with `token_endpoint_auth_method: "none"` in that case, so the token endpoint must accept [PKCE](https://datatracker.ietf.org/doc/html/rfc7636)-only requests without a client secret. If the metadata lists `private_key_jwt`, Claude can present a second, confidential metadata document instead, as [DCR and CIMD details](https://claude.com/docs/connectors/building/authentication.md#dcr-and-cimd-details) describes.
209209
210210If you move to a real issuer, keep `client_id_metadata_document_supported: true` in that issuer's metadata if you want registration-free onboarding for Claude clients.
211211