I run a hosted MCP server for Glidely, a kanban board with team chat built in. People connect it to Claude, ChatGPT, Cursor and VS Code, and the AI can read their boards, add cards and move work along.
Until this week, every AI app signed in through Dynamic Client Registration (DCR). Then I noticed Claude's custom connector dialog has a new recommended option: "Use Claude's published identity". Behind that option is a fairly new OAuth spec called Client ID Metadata Documents (CIMD), and the MCP authorization spec now prefers it over DCR.
Adding it to my server took about 60 lines on Cloudflare Workers. Here is what it is, the code, and the one thing I got wrong on the way.
What's annoying about DCR
With DCR, the app POSTs its name and redirect URIs to /oauth/register and gets back a client_id. Two problems in practice:
- The client table only grows. Claude registers a new client on every fresh connection. Remove the connector, add it back, and there is another row. Anthropic's own docs say high-traffic servers should prefer CIMD for exactly this reason.
- The name is whatever the app says it is. Anyone can register a client called "Claude". I already had to make my approval page ignore the self-declared name unless the redirect URI is an https address on the app's real domain.
What a Client ID Metadata Document is
Instead of registering, the app uses an https URL as its client_id. That URL serves a small JSON file describing the app. This is Claude's, live at https://claude.ai/oauth/mcp-oauth-client-metadata:
{
"client_id": "https://claude.ai/oauth/mcp-oauth-client-metadata",
"client_name": "Claude",
"client_uri": "https://claude.ai",
"redirect_uris": ["https://claude.ai/api/mcp/auth_callback"],
"grant_types": ["authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:jwt-bearer"],
"response_types": ["code"],
"token_endpoint_auth_method": "none"
}
When the authorization server sees a URL as the client_id, it fetches that file and uses it as the registration. Nothing is stored, and the identity is backed by the domain: only Anthropic can put a file on claude.ai.
Step 1: say you support it
Claude only switches to CIMD when the authorization server metadata has both of these. Otherwise it quietly falls back to DCR:
token_endpoint_auth_methods_supported: ['none', 'client_secret_post', 'client_secret_basic'],
client_id_metadata_document_supported: true,
The none matters because Claude's CIMD client is a public client: it proves itself with PKCE, not a secret. A file anyone can read can't hold a secret anyway.
Step 2: recognise a URL client_id, safely
Your server is about to fetch a URL that a stranger typed into a query string, so this is an SSRF door. I already had a strict check for link previews (no IP addresses, no localhost or .internal names, no unusual ports), so I reused it and added the CIMD rules on top:
export function isMetadataClientId(value) {
if (typeof value !== 'string' || value.length > 500 || !value.startsWith('https://')) return false;
try {
const url = publicWebUrl(value); // throws for IPs, local names and odd ports
return url.href === value && !url.port && !url.search && !url.hash && url.pathname.length > 1;
} catch {
return false;
}
}
url.href === value is a cheap way to reject anything that isn't already in canonical form, like .. segments or an upper-case host.
Step 3: fetch it like you don't trust it
async function publishedClient(clientId) {
const hit = published.get(clientId);
if (hit && hit.until > Date.now()) return hit.client;
let doc;
try {
const response = await fetch(clientId, {
headers: { Accept: 'application/json' },
redirect: 'manual', // the spec says don't follow redirects
signal: AbortSignal.timeout(5000),
});
if (response.status !== 200) return null;
doc = JSON.parse(new TextDecoder().decode(await readBytes(response, 5 * 1024))); // stop at 5 KB
} catch {
return null;
}
if (!doc || doc.client_id !== clientId) return null; // the file must name its own address
const uris = Array.isArray(doc.redirect_uris) ? doc.redirect_uris.map(String) : [];
if (uris.length === 0 || uris.length > 10 || !uris.every(redirectAllowed)) return null;
if (String(doc.token_endpoint_auth_method || 'none') !== 'none') return null; // public clients only
const client = { id: clientId, data: { name: doc.client_name, redirectUris: uris, authMethod: 'none' } };
published.set(clientId, { client, until: Date.now() + 10 * 60 * 1000 }); // cache successes only
return client;
}
The rules, in plain words:
-
Only a 200 counts. A 302 is not followed, so
evil.example/xcan't bounce you to a file on claude.ai. -
The document must name its own URL as
client_id. Otherwise anyone could serve a copy of Claude's file from their own domain. -
Read at most 5 KB, wait at most 5 seconds.
readBytesstreams and stops as soon as it passes the limit, instead of buffering a huge body first. - Cache good answers, never errors. If the file is down for a minute, the next try fetches it again.
I left private_key_jwt out on purpose. It needs JWKS fetching and JWT checks, and nobody I support needs it yet.
Step 4: one function, everywhere a client is looked up
My code looked up clients in two places: /oauth/authorize and /oauth/token. Both now go through one function:
const findClient = async (env, id) =>
isMetadataClientId(id) ? publishedClient(id)
: validId(id) ? getDocument(env, `aiClients/${id}`)
: null;
Everything after that stayed the same: redirect URI matching, PKCE, one-time codes, refresh-token rotation. A published client is just a client that happens not to live in the database.
Claude Code and loopback redirects
Claude Code has its own document at https://claude.ai/oauth/claude-code-client-metadata. Its redirect URIs are http://localhost/callback and http://127.0.0.1/callback, with no port, because the CLI opens a random port each time. Your redirect check has to ignore the port for loopback addresses (RFC 8252, section 7.3):
function sameRedirect(registered, given) {
if (registered === given) return true;
const a = new URL(registered);
const b = new URL(given);
return a.protocol === 'http:' && b.protocol === 'http:' && LOOPBACK.has(a.hostname)
&& a.hostname === b.hostname && a.pathname === b.pathname && a.search === b.search;
}
I already had this for DCR clients, so Claude Code worked on the first try.
The thing I got wrong
When I first saw the new option, I assumed picking "Use Claude's published identity" on my server was broken. It wasn't. Anthropic's docs say Claude only uses CIMD when the server advertises it, and falls back to DCR otherwise. So nothing was failing. CIMD is an upgrade, not a fix: no more orphaned client rows, and the identity is checked by domain instead of by what the app calls itself.
How I tested it
- The full flow with Claude's real document: authorize, approve, swap the code with PKCE, refresh as a public client.
- Claude Code's loopback redirect on two random ports.
- Refusals: a file that names a different
client_id, a file asking forclient_secret_basic, a redirect URI the file doesn't list, a 302, a 6 KB file, a 503 that later recovers (it must not stay cached), and URLs that must never be fetched at all (http://, IP addresses,localhost,.local, a port, a query string). - A connection made the old DCR way gets replaced, not doubled, when the same person reconnects through CIMD.
- Finally, against production: Claude's and Claude Code's real documents both reach the approval page.
Links
- Anthropic: Authentication for connectors
- IETF: OAuth Client ID Metadata Document
- If you want to try it with a real board: Glidely's MCP server is free, nothing to install, and works with Claude Code, Cursor and VS Code
Happy to answer questions about running MCP OAuth on Workers in the comments.
Top comments (2)
Nice write-up — the "cache good answers, never errors" rule is the one I'd underline. The failure mode it saves you from is subtle: if the fetch fails once and you cache the error, a single blip at the client's end locks every new sign-in out until the cache expires.
One trade-off worth naming is the TTL on the good answers. Caching the document is what makes the redirect URIs self-updating — if Claude adds a redirect URI to its metadata, your server picks it up without a code change — but the same cache means a changed or revoked document keeps being trusted until it expires. Short TTLs (minutes, not hours) keep that window small without giving up the availability win.
Also worth checking on your side: VS Code uses a loopback redirect with a random port too, so the same port-ignoring redirect comparison you built for Claude Code covers it.
Thanks, and yes, that failure mode is exactly why the rule is there. One slow or broken response from the client's side shouldn't lock every new sign-in out until the cache expires.
On the TTL we ended up in the same place you describe. Published metadata is cached for 10 minutes, and the cache is in memory per Worker instance, so in practice it's often shorter than that. A changed or removed document is picked up within that window, and because failures are never cached, sign-ins recover as soon as the document is reachable again. Respecting the document's own Cache-Control is on the list if clients start changing theirs often.
Good call on VS Code. The redirect check isn't Claude-specific: it follows RFC 8252 section 7.3, so any http loopback redirect (localhost, 127.0.0.1 or [::1]) matches the registered one on any port, as long as the host, path and query are the same. So VS Code's random port should go through the same path. I haven't run VS Code end to end against it yet though, so that's going on the test list. Thanks for the nudge.