Client ID Metadata Documents: How MCP Clients Register

ProductionProtocols and integrationPublished Updated By Simon Budziak

Client ID Metadata Documents (CIMD) let an OAuth client use an HTTPS URL as its client ID. The URL serves a JSON document describing the client, which the authorization server fetches on first contact. The MCP authorization spec recommends it for the common case of a client meeting a server it has never seen, with no registration step.

How does a Client ID Metadata Document work?

The client hosts a JSON file at an HTTPS URL with a path and uses that URL as its client_id. Under the MCP authorization spec, the document must include at least client_id, client_name and redirect_uris, and its client_id must match the URL exactly (MCP client registration, 2026-07-28, read 16 November 2026). Trimmed from the spec’s example:

{
  "client_id": "https://app.example.com/oauth/client-metadata.json",
  "client_name": "Example MCP Client",
  "redirect_uris": ["http://127.0.0.1:3000/callback"],
  "token_endpoint_auth_method": "none"
}

The authorization server advertises client_id_metadata_document_supported: true in its OAuth metadata. When an authorization request arrives with a URL-shaped client_id, it fetches the document, checks that the client_id matches, that the redirect URI is listed and that the JSON is valid, then shows the user a consent screen naming the client. It should cache the document per its HTTP cache headers. The client’s identity is whatever its own domain serves, so no server keeps a registration record for it. That tells a server which software is asking, the agent identity question, not what it may do.

How is CIMD different from Dynamic Client Registration?

CIMD replaces a registration call with a document fetch, one of three mechanisms the MCP spec names:

Client ID Metadata Documents Dynamic Client Registration Pre-registration
Where the client_id comes from An HTTPS URL the client hosts Issued by the server’s registration endpoint Issued in advance, out of band
Changing authorization server Portable, no re-registration Must re-register Bound to the issuing server
Status in MCP 2026-07-28 SHOULD support Deprecated, MAY support SHOULD offer an option for it

A client supporting all three should try pre-registered credentials first, then CIMD if the server advertises it, then Dynamic Client Registration if the server has a registration_endpoint, then ask the user. CIMD entered MCP in the 2025-11-25 revision as a recommended mechanism (changelog, read 16 November 2026). The 2026-07-28 revision, the same one that made MCP stateless, deprecated Dynamic Client Registration in its favor, with removal possible from the first revision released on or after 28 July 2027 (deprecated features, read 16 November 2026). New clients and authorization servers should build CIMD first and keep Dynamic Client Registration only for older servers.

What security risks does CIMD leave open?

The authorization server fetches a URL that a stranger supplied. Every CIMD fetch is an outbound request made on someone else’s behalf, so the spec points servers to the IETF draft’s server-side request forgery (SSRF) guidance (MCP security considerations, read 16 November 2026). CIMD also cannot by itself stop a local app impersonating a client whose redirect URIs point at localhost, so servers should warn on localhost-only redirect URIs and must show the redirect URI hostname during authorization. The MCP spec cites draft -00, while the IETF draft has since reached -03, last updated 2 November 2026 and still an Internet-Draft (IETF datatracker, read 16 November 2026), so check which revision your auth library follows. The wider attack surface is in MCP security in production.

How do we handle client registration when connecting our agents to MCP servers?

Our agents reach remote MCP servers over HTTP, each authenticated per account, usually with OAuth. We try the client’s built-in authorization flow before creating an OAuth client by hand. In one case the vendor documented only flows that needed our own pre-registered client, and the plain built-in flow worked without one: vendor docs lag the servers. In general, a client that registers itself through CIMD or Dynamic Client Registration needs nothing created in advance. We record a server as usable only after a real tool call succeeds, because once the client reported “connected” while tool calls from a running session failed with an “Incompatible auth server” error.

Written with AI assistance and reviewed by Simon Budziak. The production notes come from systems Soba Labs builds and runs.

Frequently asked questions

Do stdio MCP servers need Client ID Metadata Documents?

No. MCP authorization is optional and written for HTTP transports; the 2026-07-28 spec says stdio implementations should not follow it and should take credentials from the environment instead.

Is a CIMD client_id a secret?

No. It is a public HTTPS URL that anyone can fetch. A client that must authenticate at the token endpoint may use private_key_jwt with published keys, as the MCP client registration page allows.

Summarize this page with

Train your team to build this