How I added Client ID Metadata Documents to my MCP server's OAuth

Hamza Ishtiaq — Sat, 14 Nov 2026 15:57:25 +0000

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/x can'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. readBytes streams 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 for client_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.

Why We Built Glidely: A Calm All-in-One Alternative to Trello and Slack

Hamza Ishtiaq — Fri, 09 Oct 2026 13:54:12 +0000

Every development and startup team faces the same invisible tax: app-switching fatigue.

On any given workday, you're constantly toggling between three different tools:

Trello or Jira to update task status cards.
Slack or Discord to ask quick questions or share updates.
Google Calendar to confirm approaching deadlines and milestones.

Individually, these tools work fine. But together, they create a fragmented mess. Discussions happen in Slack channels completely detached from the actual task tickets, while deadlines slip quietly because they're hidden in a separate calendar tab.

We got tired of juggling multiple subscriptions and losing our focus to tab clutter. That's why we built Glidely (https://glidely.site).

What is Glidely?

Glidely (https://glidely.site) is a calm, unified workspace that puts your team's visual task boards, real-time messaging, and deadline calendars into a single, distraction-free interface.

Instead of over-engineering the workflow with enterprise bloat, Glidely focuses on speed and simplicity:

Visual Kanban Boards: Lightweight drag-and-drop boards to track tasks across custom stages with clear priorities and assignments.
In-Context Team Chat: Discuss projects directly inside your workspace, keeping every conversation attached to real work rather than lost in endless Slack channels.
Integrated Calendar and Timelines: See your deadlines clearly without syncing external calendar extensions.
Automated Analytics: Monitor task velocity and completion rates automatically without manual reporting.

Built for Speed on the Modern Edge

We wanted Glidely to feel instant. We built the platform using React, TypeScript, and Tailwind CSS on the frontend, powered by serverless Cloudflare Workers and Cloudflare R2 on the backend. This gives teams sub-100ms response times worldwide with zero lag.

Try it Free

Glidely has a 100% free plan for individuals, freelancers, and small teams getting started.

You can try the live demo or set up your first board in under 60 seconds at:
https://glidely.site

We would love to hear your thoughts, feedback, and feature suggestions from the community!

DEV Community: Hamza Ishtiaq