What this read moved
1–3 of 3connectors/building/authentication Changed · +61 / -4 lines
## Servers with per-customer URLs ## Credentials entered at connection time
from line 12
1212| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
1313| `oauth_dcr` | OAuth 2.0 with Dynamic Client Registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)) | Supported out of the box |
1414| `oauth_cimd` | OAuth 2.0 with [Client ID Metadata Document](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#client-id-metadata-documents) | Supported out of the box |
15| `oauth_anthropic_creds` | OAuth 2.0 with Anthropic-held client credentials | Contact `[email protected]` |
16| `custom_connection` | Custom URL or credentials supplied at connection time (for example, Snowflake-style) | Contact `[email protected]` |
15| `oauth_anthropic_creds` | OAuth 2.0 with [Anthropic-held client credentials](#anthropic-held-client-credentials) | Contact `[email protected]` |
16| `custom_connection` | Custom URL or OAuth client credentials [entered at connection time](#credentials-entered-at-connection-time) | Contact `[email protected]` |
1717| `static_headers` | Fixed credential (API key or bearer token) entered by an organization administrator as a request header when adding the connector | Beta |
1818| `none` | No authentication (authless server) | Supported. An optional partial-auth mode is experimental. |
1919
20If your server URL varies per customer, read [Servers with per-customer URLs](#servers-with-per-customer-urls) before you pick a type.
21
2022Static bearer tokens and API keys are supported in beta through request headers (`static_headers`). An organization administrator enters the credential once when adding the connector, and Claude sends it on every request. The credential is shared by the organization rather than pasted per user. Standard header names such as `authorization` and `x-api-key` work for every connector; Anthropic reviews and approves any other header name before administrators can save the connector. See [Authenticating with request headers](/docs/connectors/custom/remote-mcp#authenticating-with-request-headers) for what administrators see and how to document the expected header for them.
2123
2224Tokens or API keys passed in the connector URL (for example, `?token=`, `?apiKey=`, or `?userToken=` query parameters) are **not recommended**. A credential in a URL is a security vulnerability: URLs are routinely recorded in server logs, proxies, and browsing history, so a query-string credential is easy to leak. The MCP authorization specification explicitly [prohibits access tokens in the URI query string](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#token-requirements). Use OAuth or [request headers](/docs/connectors/custom/remote-mcp#authenticating-with-request-headers) instead.
2325
26## Servers with per-customer URLs
27
28The submission portal's **Connection** step asks how users reach your server. There are three choices:
29
30* **Universal URL**: every user connects to the same URL.
31* **Multiple URLs**: you list a fixed set of labeled URLs, such as one per region. Users pick one when they connect.
32* **URL pattern**: you give an anchored regular expression that every customer's URL must match, such as `^https://[a-z0-9-]+\.mcp\.example\.com/mcp$`. Each user enters their own URL when they connect, and Claude accepts it only if it matches.
33
34Keep the host part of a URL pattern lowercase, because Claude lowercases the host of the URL the user enters before checking it.
35
36Listings with **Multiple URLs** or a **URL pattern** take longer to review.
37
38You choose the URL option and the authentication type separately, but the URL option limits which authentication types work. Request headers (`static_headers`) are set up by the organization administrator who adds the connector and aren't covered by this table.
39
40| Type | Universal URL | Multiple URLs | URL pattern |
41| ----------------------- | ------------- | ------------- | ----------- |
42| `oauth_dcr` | Yes | Yes | Yes |
43| `oauth_cimd` | Yes | Yes | Yes |
44| `oauth_anthropic_creds` | Yes | Yes | No |
45| `custom_connection` | Yes | No | Yes |
46| `none` | Yes | Yes | Yes |
47
48Anthropic-held client credentials are tied to exact server URLs, and a URL pattern matches URLs Anthropic doesn't know in advance. Credentials entered at connection time can't be combined with **Multiple URLs**.
49
50For a URL pattern, use these in order of preference:
51
521. Client ID Metadata Document (CIMD). Every customer's authorization server must advertise both CIMD values listed in [DCR and CIMD details](#dcr-and-cimd-details).
532. [Dynamic Client Registration](#dcr-and-cimd-details) (DCR). Every customer's authorization server must expose a `registration_endpoint`.
543. [Credentials entered at connection time](#credentials-entered-at-connection-time), if your customers' authorization servers support neither. Each customer then has to create an OAuth client for Claude themselves.
55
2456## Anthropic-held client credentials
2557
2658A pure machine-to-machine `client_credentials` grant—where a server-to-server token is issued with no user in the loop—is **not supported**. Every connection requires user consent.
from line 68
3668
3769Anthropic-held credentials are bound to the authorization server that issued them. If you migrate to a new authorization server, email `[email protected]` with the new `client_id` and `client_secret` before cutting over. CIMD-based connectors don't have this constraint — a CIMD `client_id` is a self-hosted URL, so it works against any authorization server that fetches it.
3870
71<Note>
72 Anthropic-held credentials are also tied to exact server URLs. They can't be used with a URL pattern, where each customer enters their own server URL. See [Servers with per-customer URLs](#servers-with-per-customer-urls) for the alternatives.
73</Note>
74
4076
77## Credentials entered at connection time
78
79`custom_connection` (**Custom URL or credentials at connection time** in the submission portal) asks each customer for the OAuth client that Claude should use, instead of Claude registering one or Anthropic holding one.
80
81Each customer must be able to create an OAuth client in your product, which usually means an administrator sets up the connector for their organization. If your customers can't create OAuth clients, use CIMD or DCR instead.
82
83When a user adds your connector, Claude shows a form with these fields:
84
85* **Server URL**, if your listing uses a URL pattern. Claude accepts the URL only if it matches the pattern.
86* **OAuth client ID** and **OAuth client secret**. You choose which of the two to ask for, and whether each is required or optional.
87
88The form links to pages you supply: one for where the customer finds their server URL, and one for how they get the credentials. The credentials page must explain how a customer creates an OAuth client for Claude in your product and registers the redirect URI `https://claude.ai/api/mcp/auth_callback`.
89
90If a user leaves an optional client secret blank, Claude uses the client ID as a public client. If a user leaves an optional client ID blank, Claude falls back to the same order as any other listing: Anthropic-held credentials for that URL if Anthropic holds any, then CIMD, then DCR. See [DCR and CIMD details](#dcr-and-cimd-details).
91
92If you later stop asking for credentials, connections already made with user-entered credentials keep using them. An organization gets the new behavior only once no one in it still has the connector. The next person to add it starts fresh.
93
94To use this flow, email `[email protected]` with which fields you need, whether each is required, and the page each one should link to.
95
4196## DCR and CIMD details
4297
4398If your authorization server does **not** expose a `registration_endpoint` (i.e., does not support DCR), you have several options:
from line 99
4499
45100* Expose a `registration_endpoint`
46101* 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](/docs/connectors/building/lazy-authentication#identify-the-client-with-cimd) for a worked CIMD example.
47* Switch to `oauth_anthropic_creds`
102* Switch to `oauth_anthropic_creds`, if your listing doesn't use a URL pattern
48103
104If your server URL varies per customer and DCR isn't available, CIMD is the recommended path. Every customer's authorization server must advertise both values above. Otherwise Claude falls back to DCR for that customer, which needs a `registration_endpoint`.
105
49106For 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.
50107
51108Claude includes a [PKCE](https://datatracker.ietf.org/doc/html/rfc7636) `code_challenge` with `code_challenge_method=S256` on every authorization request, regardless of which registration mechanism it uses. Your authorization server must support S256 PKCE, and the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#authorization-code-protection) requires it to advertise `"code_challenge_methods_supported": ["S256"]` in its metadata so spec-compliant clients can verify support before starting the flow.
from line 173
116173 Organizations using SSO can also connect their users to your server without an interactive OAuth consent step, using an identity assertion signed by their identity provider. See [Enterprise Managed Auth](./enterprise-managed-auth) for what your authorization server needs to support.
117174</Note>
118175
119Directory connectors use a **single shared OAuth application per connector**. There is no per-org OAuth client for directory connectors — enterprise customers connect to the same OAuth app as everyone else, and access is scoped by the user's own permissions on your service. Custom connectors are different: an admin can supply their own OAuth client credentials when adding the connector, which scopes the OAuth client to that organization. See [custom connectors](#custom-connectors).
176Most directory connectors use a **single shared OAuth application per connector**. Enterprise customers connect to the same OAuth app as everyone else, and access is scoped by the user's own permissions on your service. For a listing that asks for [credentials entered at connection time](#credentials-entered-at-connection-time), each customer supplies its own OAuth client instead. Custom connectors are different: an admin can supply their own OAuth client credentials when adding the connector, which scopes the OAuth client to that organization. See [custom connectors](#custom-connectors).
120177
121178## Custom connectors
122179
connectors/building/submission Changed · +4 / -2 lines
from line 129
129129 </Step>
130130
131131 <Step title="Connection">
132 Connect the server you're submitting. You confirm the server URL (must be `https://`), the transport (streamable HTTP or SSE), and whether every user connects to the same URL or different users connect to different URLs.
132 Connect the server you're submitting. You confirm the server URL (must be `https://`), the transport (streamable HTTP or SSE), and how users reach your server: one **Universal URL** for everyone, a fixed list of **Multiple URLs**, or a **URL pattern** that each user's own URL must match. See [Servers with per-customer URLs](/docs/connectors/building/authentication#servers-with-per-customer-urls) for how this choice limits your authentication options.
133133 </Step>
134134
135135 <Step title="Tools">
from line 149
149149 </Step>
150150
151151 <Step title="Authentication">
152 How users authenticate: OAuth (with dynamic client registration, client ID metadata documents, or a static client ID held by Anthropic), a custom connection where users supply their own URL or credentials at connection time, or no authentication. See [authentication](/docs/connectors/building/authentication) for which modes are supported out of the box and which need coordination with the review team. If your server starts without authentication and individual tools prompt for it on demand, you can flag that here.
152 How users authenticate: OAuth (with dynamic client registration, client ID metadata documents, or Anthropic-held client credentials), a custom connection where users supply their own URL or credentials at connection time, or no authentication. See [authentication](/docs/connectors/building/authentication) for which modes are supported out of the box and which need coordination with the review team. If your server starts without authentication and individual tools prompt for it on demand, you can flag that here.
153
154 If you chose **URL pattern** in the Connection step, Anthropic-held client credentials can't be used. If you chose **Multiple URLs**, a custom connection can't be used.
153155 </Step>
154156
155157 <Step title="Data handling">
connectors/building/directory-vs-custom Changed · +1 / -1 lines
from line 72
7272
7373## Per-tenant URLs
7474
75If your server URL varies per tenant (for example, `{tenant}.mcp.example.com`), this is typically handled either as separate per-tenant directory entries or via the [`custom_connection`](/docs/connectors/building/authentication#supported-authentication-types) authentication type, where users supply their tenant-specific URL at connection time. `custom_connection` is enabled per partner—email `[email protected]` to request it. The directory does not currently template a single entry across tenant subdomains.
75If your server URL varies per tenant (for example, `{tenant}.mcp.example.com`), submit one directory listing with a URL pattern. Each user enters their own URL when they connect. See [Servers with per-customer URLs](/docs/connectors/building/authentication#servers-with-per-customer-urls) for how this choice limits your authentication options.
7676
7777## What the directory is not
7878