Just this past Friday we put the current Model Context Protocol specification in “frozen” state. In practice, that just means that all the big items have been merged and the community and maintainers are now heads-down implementing the changes and working through the last papercuts to make sure the new functionality is well-documented and works the way it’s expected.

One change that made it into the protocol was driven by Aaron Parecki into the authorization specification - support for Client ID Metadata Documents (CIMD). This work comes on the heels of the pain that developers have experienced for the past six months trying to get Dynamic Client Registration (DCR) working properly for their MCP servers. Spoiler alert - it’s neither fun nor easy to implement it from scratch if you’re using an Identity Provider that doesn’t support it. Let alone the complexity of now having to maintain a separate pseudo-Authorization Server (AS) for this purpose.

How CIMD works

First, let’s maybe take a short detour into the world of CIMD and how it actually works. I won’t rehash the specification because you can read it on your own time. The gist of the approach is that instead of relying on some kind of client registration mechanism like DCR (or pre-registration, as is common in the OAuth world), a client can identify itself to an AS. To do that, the client effectively exposes a JSON document on a well-known URL that is treated as a client ID by the AS. The document itself contains the required metadata that allows the AS to reliably make a determination about the validity of the client.

The JSON the client hosts may look something like this (the URLs are entirely fictional - I am not yet hosting my own MCP server):

{
  "client_id": "https://mcp.den.dev/oauth/metadata.json",
  "client_name": "den.dev",
  "client_uri": "https://mcp.den.dev",
  "redirect_uris": ["https://mcp.den.dev/oauth/callback"]
}

With the client ready, we now also need to make sure that the AS supports CIMD - the approach here is not magical and requires work on both sides of the aisle. Prior to actually being able to get any tokens, a client would send a GET request to the AS authorization endpoint with the metadata URL as the client ID, and then jump through the same authorization hoops as one normally would to get the user credentials and ultimately - a credential (usually in the shape of an opaque token). This requires AS developers to implement support for the capability.

Indeed. However, the awesome folks at Stytch actually added support for CIMD already - you can use their AS for testing. They even put together an excellent education resource for those that want to learn more about the approach on the dedicated Client ID Metadata Documents site.

I really like this approach for its simplicity - if I am a developer of “Den’s MCP Server” hosted at https://mcp.den.dev, I am the only one that can actually host a CIMD on this domain. We’re back to using DNS as the source of truth. An AS can then verify the document from my server against a number of parameters (e.g., source matching the client ID, whether the expected redirect URIs are used) and then make a determination on whether to trust this client or not.

Now, some of you might jump up eagerly yelling at the screen “Den, but what about client secrets?” With CIMD, client secrets are not applicable. For all intents and purposes, we’re talking about a similar approach to other public clients in OAuth.

Integration in Visual Studio Code

Starting last week, Visual Studio Code supports CIMD for MCP in its stable build. It hosts its CIMD here:

https://vscode.dev/oauth/client-metadata.json

To get everything up and running, we need to find an AS that we can tinker with. Luckily, we can use one that Max Gerber from Stytch put together in the open (you can view the hosted version too). We will also use a MCP server that Max provided that we can use out-of-the-box (we’ll need this URL to connect inside Visual Studio Code):

https://stytch-as-demo.val.run/mcp

When the MCP server is added, it will follow all of the steps that we’ve talked before. It even hosts its Protected Resource Metadata (PRM) where you expect it:

https://stytch-as-demo.val.run/.well-known/oauth-protected-resource

It looks like this:

{
  "resource": "https://stytch-as-demo.val.run/mcp",
  "authorization_servers": [
    "https://industrious-dress-4239.customers.stytch.dev"
  ],
  "scopes_supported": [
    "openid",
    "email"
  ]
}

So far so good, and nothing too different from other PRM documents we’ve seen before. After getting the PRM, the client (Visual Studio Code, in this case) will go ahead and get the AS metadata document. The URI for it is constructed based on standard OAuth conventions, and ends up being this:

https://industrious-dress-4239.customers.stytch.dev/.well-known/oauth-authorization-server

Which, inside, looks like this:

{
  "authorization_endpoint": "https://stytch-as-demo.val.run/oauth/authorize",
  "client_id_metadata_document_supported": true,
  "code_challenge_methods_supported": [
    "S256"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "issuer": "https://industrious-dress-4239.customers.stytch.dev",
  "jwks_uri": "https://industrious-dress-4239.customers.stytch.dev/.well-known/jwks.json",
  "registration_endpoint": "https://industrious-dress-4239.customers.stytch.dev/v1/oauth2/register",
  "request_id": "request-id-test-b9d728aa-77f1-4fce-aa12-b9360ba521a2",
  "response_types_supported": [
    "code",
    "code token"
  ],
  "scopes_supported": [
    "openid",
    "profile",
    "email",
    "phone",
    "offline_access"
  ],
  "status_code": 200,
  "token_endpoint": "https://industrious-dress-4239.customers.stytch.dev/v1/oauth2/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ],
  "userinfo_endpoint": "https://industrious-dress-4239.customers.stytch.dev/v1/oauth2/userinfo"
}

Notice the presence of client_id_metadata_document_supported. This is what hints to the client that they can bypass the entire registration dance and jump right in by sending a GET request like this:

https://stytch-as-demo.val.run
  /oauth
  /authorize
    ?client_id=https%3A%2F%2Fvscode.dev%2Foauth%2Fclient-metadata.json
    &response_type=code
    &code_challenge=luDEIWQzDnkpDAlm563kBp9CugNlwgWPb4BQBBq8JNg
    &code_challenge_method=S256
    &scope=openid+email
    &resource=https%3A%2F%2Fstytch-as-demo.val.run%2Fmcp
    &redirect_uri=http%3A%2F%2F127.0.0.1%3A33418%2F
    &state=Yk%2FLbnhh1Ht869Ua11VXKw%3D%3D

If you’re an OAuth aficionado, this will look super familiar - because it is. The only thing that really changed is that the client ID is now the metadata document URL and not some other identifier (e.g., a GUID in Entra ID).

And just like that, CIMD just works for protected MCP servers that rely on AS with this feature implemented inside Visual Studio Code:

CIMD integration in Visual Studio Code.
CIMD integration in Visual Studio Code.

What’s next

As Paul Carleton (one of the MCP Core Maintainers) mentioned in his blog post from August of this year, CIMD is coming to the MCP specification and is already available in the draft that we’re aiming to make stable at the end of November. I am excited about this change mainly because it significantly simplifies how developers can protect their MCP servers without jumping through many (many) unpleasantries of DCR.

With Visual Studio Code already supporting this, and with a test AS being available from the folks at Stytch, if you’re a MCP client or server developer I highly recommend you start tinkering with it and seeing what the rough edges are and how those can be improved. And as always, MCP feedback is welcome!