<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[Glidely]]></title><description><![CDATA[Glidely]]></description><link>https://glidely.hashnode.dev</link><image><url>https://cdn.hashnode.com/uploads/logos/6af88f33eac6df2a260d2c06/3ca456cb-6c22-4628-ad3a-95926cac8c25.png</url><title>Glidely</title><link>https://glidely.hashnode.dev</link></image><generator>RSS for Node</generator><lastBuildDate>Wed, 18 Nov 2026 15:07:17 GMT</lastBuildDate><atom:link href="https://glidely.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[How I added Client ID Metadata Documents to my MCP server's OAuth]]></title><description><![CDATA[How to add Client ID Metadata Document support to a remote MCP server’s OAuth on Cloudflare Workers, so Claude can sign in with its published identity.]]></description><link>https://glidely.hashnode.dev/how-i-added-client-id-metadata-documents-to-my-mcp-server-s-oauth</link><guid isPermaLink="true">https://glidely.hashnode.dev/how-i-added-client-id-metadata-documents-to-my-mcp-server-s-oauth</guid><category><![CDATA[mcp]]></category><category><![CDATA[mcp server]]></category><category><![CDATA[oauth]]></category><category><![CDATA[cloudflare]]></category><category><![CDATA[webdev]]></category><dc:creator><![CDATA[glidely]]></dc:creator><pubDate>Sat, 14 Nov 2026 17:39:29 GMT</pubDate><content:encoded><![CDATA[<blockquote>
<p>Note: this article was written with an AI assistant, about work on Glidely's own MCP server. It was first published on <a href="https://dev.to/glidely/how-i-added-client-id-metadata-documents-to-my-mcp-servers-oauth-4no0">DEV</a>.</p>
</blockquote>
<p>I run a hosted MCP server for <a href="https://glidely.site">Glidely</a>, 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.</p>
<p>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: <strong>"Use Claude's published identity"</strong>. Behind that option is a fairly new OAuth spec called <strong>Client ID Metadata Documents</strong> (CIMD), and the MCP authorization spec now prefers it over DCR.</p>
<p>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.</p>
<h2>What's annoying about DCR</h2>
<p>With DCR, the app POSTs its name and redirect URIs to <code>/oauth/register</code> and gets back a <code>client_id</code>. Two problems in practice:</p>
<ol>
<li><strong>The client table only grows.</strong> 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.</li>
<li><strong>The name is whatever the app says it is.</strong> 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.</li>
</ol>
<h2>What a Client ID Metadata Document is</h2>
<p>Instead of registering, the app uses an <strong>https URL as its</strong> <code>client_id</code>. That URL serves a small JSON file describing the app. This is Claude's, live at <code>https://claude.ai/oauth/mcp-oauth-client-metadata</code>:</p>
<pre><code class="language-json">{
  "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"
}
</code></pre>
<p>When the authorization server sees a URL as the <code>client_id</code>, 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 <a href="http://claude.ai">claude.ai</a>.</p>
<h2>Step 1: say you support it</h2>
<p>Claude only switches to CIMD when the authorization server metadata has <strong>both</strong> of these. Otherwise it quietly falls back to DCR:</p>
<pre><code class="language-js">token_endpoint_auth_methods_supported: ['none', 'client_secret_post', 'client_secret_basic'],
client_id_metadata_document_supported: true,
</code></pre>
<p>The <code>none</code> 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.</p>
<h2>Step 2: recognise a URL client_id, safely</h2>
<p>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 <code>localhost</code> or <code>.internal</code> names, no unusual ports), so I reused it and added the CIMD rules on top:</p>
<pre><code class="language-js">export function isMetadataClientId(value) {
  if (typeof value !== 'string' || value.length &gt; 500 || !value.startsWith('https://')) return false;
  try {
    const url = publicWebUrl(value); // throws for IPs, local names and odd ports
    return url.href === value &amp;&amp; !url.port &amp;&amp; !url.search &amp;&amp; !url.hash &amp;&amp; url.pathname.length &gt; 1;
  } catch {
    return false;
  }
}
</code></pre>
<p><code>url.href === value</code> is a cheap way to reject anything that isn't already in canonical form, like <code>..</code> segments or an upper-case host.</p>
<h2>Step 3: fetch it like you don't trust it</h2>
<pre><code class="language-js">async function publishedClient(clientId) {
  const hit = published.get(clientId);
  if (hit &amp;&amp; hit.until &gt; 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 &gt; 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;
}
</code></pre>
<p>The rules, in plain words:</p>
<ul>
<li><strong>Only a 200 counts.</strong> A 302 is not followed, so <code>evil.example/x</code> can't bounce you to a file on <a href="http://claude.ai">claude.ai</a>.</li>
<li><strong>The document must name its own URL as</strong> <code>client_id</code><strong>.</strong> Otherwise anyone could serve a copy of Claude's file from their own domain.</li>
<li><strong>Read at most 5 KB, wait at most 5 seconds.</strong> <code>readBytes</code> streams and stops as soon as it passes the limit, instead of buffering a huge body first.</li>
<li><strong>Cache good answers, never errors.</strong> If the file is down for a minute, the next try fetches it again.</li>
</ul>
<p>I left <code>private_key_jwt</code> out on purpose. It needs JWKS fetching and JWT checks, and nobody I support needs it yet.</p>
<h2>Step 4: one function, everywhere a client is looked up</h2>
<p>My code looked up clients in two places: <code>/oauth/authorize</code> and <code>/oauth/token</code>. Both now go through one function:</p>
<pre><code class="language-js">const findClient = async (env, id) =&gt;
  isMetadataClientId(id) ? publishedClient(id)
  : validId(id) ? getDocument(env, `aiClients/${id}`)
  : null;
</code></pre>
<p>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.</p>
<h2>Claude Code and loopback redirects</h2>
<p>Claude Code has its own document at <code>https://claude.ai/oauth/claude-code-client-metadata</code>. Its redirect URIs are <code>http://localhost/callback</code> and <code>http://127.0.0.1/callback</code>, 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):</p>
<pre><code class="language-js">function sameRedirect(registered, given) {
  if (registered === given) return true;
  const a = new URL(registered);
  const b = new URL(given);
  return a.protocol === 'http:' &amp;&amp; b.protocol === 'http:' &amp;&amp; LOOPBACK.has(a.hostname)
    &amp;&amp; a.hostname === b.hostname &amp;&amp; a.pathname === b.pathname &amp;&amp; a.search === b.search;
}
</code></pre>
<p>I already had this for DCR clients, so Claude Code worked on the first try.</p>
<h2>The thing I got wrong</h2>
<p>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.</p>
<h2>How I tested it</h2>
<ul>
<li>The full flow with Claude's real document: authorize, approve, swap the code with PKCE, refresh as a public client.</li>
<li>Claude Code's loopback redirect on two random ports.</li>
<li>Refusals: a file that names a different <code>client_id</code>, a file asking for <code>client_secret_basic</code>, 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 (<code>http://</code>, IP addresses, <code>localhost</code>, <code>.local</code>, a port, a query string).</li>
<li>A connection made the old DCR way gets replaced, not doubled, when the same person reconnects through CIMD.</li>
<li>Finally, against production: Claude's and Claude Code's real documents both reach the approval page.</li>
</ul>
<h2>Links</h2>
<ul>
<li>Anthropic: <a href="https://claude.com/docs/connectors/building/authentication">Authentication for connectors</a></li>
<li>IETF: <a href="https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/">OAuth Client ID Metadata Document</a></li>
<li>If you want to try it with a real board: <a href="https://glidely.site/guides/kanban-mcp-server">Glidely's MCP server</a> is free, nothing to install, and works with Claude Code, Cursor and VS Code</li>
</ul>
<p>Happy to answer questions about running MCP OAuth on Workers in the comments.</p>
]]></content:encoded></item></channel></rss>