Client ID Metadata Documents in MCP

A Client ID Metadata Document (CIMD) lets an AI app identify itself to an OAuth authorization server using an HTTPS URL as its client ID. The URL points to a JSON file the app's maker hosts, listing the app's name and allowed redirect addresses. The authorization server fetches that file when it needs it, so no registration step is required.

Status in the 2026-07-28 spec: core (the recommended client registration method; support is "SHOULD")

CIMD solves a problem that is common in MCP: an AI app and an MCP server that have never met. It is step 3 of the sign-in flow in our MCP authentication and OAuth 2.1 guide. This page follows the client registration page of the 2026-07-28 spec, checked on 28 October 2026.

Why it exists

OAuth normally needs a client ID issued in advance. That works when an app talks to a handful of known services. MCP is different: one AI app may connect to thousands of servers, and each server may use its own authorization server.

The spec lists three ways to get a client ID. It describes CIMD as the choice "When client and server have no prior relationship (most common)." The underlying IETF draft, OAuth Client ID Metadata Document, says it lets a client "identify itself to authorization servers, without prior dynamic client registration or other existing registration." As of October 2026 that draft is at revision -02 and is not yet an RFC. The MCP spec cites revision -00.

How it works

The document

This is the example from the MCP spec:

{
  "client_id": "https://app.example.com/oauth/client-metadata.json",
  "client_name": "Example MCP Client",
  "client_uri": "https://app.example.com",
  "logo_uri": "https://app.example.com/logo.png",
  "redirect_uris": [
    "http://127.0.0.1:3000/callback",
    "http://localhost:3000/callback"
  ],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Rules for clients:

• The document must be hosted at an HTTPS URL, and the client_id URL "MUST use the 'https' scheme and contain a path component."
• It "MUST include at least" client_id, client_name and redirect_uris.
• The client_id value "matches the document URL exactly."
• Clients "MAY use private_key_jwt" to authenticate at the token endpoint.

The flow

1. The client sends an authorization request with client_id set to its document URL.
2. The authorization server sees a URL-formatted client ID and fetches the document.
3. It checks that client_id matches the URL, that the requested redirect_uri is listed, and that the JSON is valid.
4. It may also apply a domain trust policy.
5. It shows the user a consent page using client_name, then continues the normal OAuth flow.

Authorization servers "SHOULD cache metadata respecting HTTP cache headers."

Advertising support

Authorization servers say they support CIMD by adding this to their OAuth metadata:

{ "client_id_metadata_document_supported": true }

Clients "SHOULD check for this capability" and "MAY fall back" to Dynamic Client Registration or pre-registration if it is missing.

Where CIMD sits in the priority order

For clients that support every option, the spec's order is:

1. Pre-registered client details, if available.
2. CIMD, if the authorization server advertises support.
3. Dynamic Client Registration, as a fallback.
4. Asking the user to enter client details.

Security considerations

The authorization security considerations list three CIMD-specific risks.

• SSRF. The authorization server fetches a URL supplied by an unknown client. The MCP security best practices warn that a malicious client could make it request "private administration endpoints." Blocking private IP ranges and using egress proxies help. See server-side request forgery in MCP.
• Localhost impersonation. "Client ID Metadata Documents cannot prevent localhost URL impersonation by themselves." Authorization servers "SHOULD display additional warnings for localhost-only redirect URIs" and "MUST clearly display the redirect URI hostname."
• Trust policies. Authorization servers "MAY implement domain-based trust policies," for example accepting only known client domains.

What changed across spec versions

The 2026-07-28 changelog also clarified credential binding. Pre-registered or DCR credentials are tied to one authorization server. CIMD client IDs "are portable across authorization servers," so "No re-registration is needed when the authorization server changes."

The 2025-11-25 release post introduced the feature as "URL-based client registration using OAuth Client ID Metadata Documents."

Common mistakes

• A client_id that differs from the URL, even by a trailing slash. The server must reject it.
• Hosting the document without a path, such as https://example.com. The spec requires a path component.
• Forgetting a redirect URI. The server validates the exact redirect against the list.
• Authorization servers fetching any URL with no SSRF controls.
• Assuming every authorization server supports CIMD. Check the metadata flag and keep a fallback.

Next step

Some authorization servers still only support the older registration method. Read Dynamic Client Registration in MCP next, or return to MCP authorization: what the spec requires and the full MCP specification reference.

Frequently asked questions