<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Vladimir Terekhov</title>
    <description>The latest articles on DEV Community by Vladimir Terekhov (@vladimir_terekhov_4c7c300).</description>
    <link>https://dev.to/vladimir_terekhov_4c7c300</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4254601%2F6e1b51a5-f1d4-44c6-a5e0-b0db497ff1e6.jpg</url>
      <title>DEV Community: Vladimir Terekhov</title>
      <link>https://dev.to/vladimir_terekhov_4c7c300</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/vladimir_terekhov_4c7c300"/>
    <language>en</language>
    <item>
      <title>One Cloudflare Worker, two kinds of auth: a stateless MCP server with OAuth 2.1 and API keys</title>
      <dc:creator>Vladimir Terekhov</dc:creator>
      <pubDate>Fri, 20 Nov 2026 12:31:14 +0000</pubDate>
      <link>https://dev.to/vladimir_terekhov_4c7c300/one-cloudflare-worker-two-kinds-of-auth-a-stateless-mcp-server-with-oauth-21-and-api-keys-3id9</link>
      <guid>https://dev.to/vladimir_terekhov_4c7c300/one-cloudflare-worker-two-kinds-of-auth-a-stateless-mcp-server-with-oauth-21-and-api-keys-3id9</guid>
      <description>&lt;p&gt;I wanted two kinds of clients to use the same MCP URL. Claude and ChatGPT add a remote server as a connector and expect to sign in with OAuth. Developer tools such as Claude Code, Codex and Cursor are happy with a bearer API key in a header. I did not want two endpoints, two sets of tools or a second Worker.&lt;/p&gt;

&lt;p&gt;This is how it fits together in one Cloudflare Worker that also serves an Astro site. All code is copied from the repository, which is MIT licensed. The versions are Astro 7, &lt;code&gt;@astrojs/cloudflare&lt;/code&gt; 14, &lt;code&gt;@modelcontextprotocol/server&lt;/code&gt; 2.4.0 and &lt;code&gt;@cloudflare/workers-oauth-provider&lt;/code&gt; 1.2.4.&lt;/p&gt;

&lt;h2&gt;
  
  
  One Worker, three jobs
&lt;/h2&gt;

&lt;p&gt;The Worker entry is short. Astro's fetch handler goes in as the default handler, and the OAuth provider sits in front of it.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// src/worker.ts&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;astro&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;ExportedHandler&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;Env&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nb"&gt;fetch&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;handle&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nb"&gt;fetch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;handleOAuthRequest&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;astro&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nf"&gt;scheduled&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;_controller&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// ... OAuth cleanup retries, then the daily 30-day data cleanup&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;satisfies&lt;/span&gt; &lt;span class="nc"&gt;ExportedHandler&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;Env&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;handleOAuthRequest&lt;/code&gt; builds an &lt;code&gt;OAuthProvider&lt;/code&gt; from the library. That class is the one-Worker shape: requests under &lt;code&gt;apiRoute&lt;/code&gt; go to &lt;code&gt;apiHandler&lt;/code&gt; with the verified token, the provider answers its own endpoints (&lt;code&gt;/oauth/token&lt;/code&gt;, &lt;code&gt;/oauth/register&lt;/code&gt;, the &lt;code&gt;/.well-known/&lt;/code&gt; documents), and everything else goes to &lt;code&gt;defaultHandler&lt;/code&gt;, which is the Astro site. The consent page at &lt;code&gt;/oauth/authorize&lt;/code&gt; is an ordinary server-rendered Astro page.&lt;/p&gt;

&lt;p&gt;The library's README now recommends splitting the authorization server and the resource server into two Workers joined by a Service Binding. It still fully supports &lt;code&gt;OAuthProvider&lt;/code&gt; for a Worker that is both. I have one resource and one app, so I kept one Worker.&lt;/p&gt;

&lt;p&gt;Passing the Astro handler in as a parameter also helps testing. Worker-level tests run in workerd with &lt;code&gt;@cloudflare/vitest-plugin&lt;/code&gt;, but they cannot load &lt;code&gt;src/worker.ts&lt;/code&gt; because it pulls in Astro's virtual modules. The tests call &lt;code&gt;handleOAuthRequest&lt;/code&gt; directly with a stub default handler:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// test/worker/oauth.test.ts&lt;/span&gt;
&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;dispatch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;handleOAuthRequest&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nf"&gt;createExecutionContext&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;defaultHandler&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Storage is split by job: D1 for app data, R2 for uploaded files, and a KV namespace bound as &lt;code&gt;OAUTH_KV&lt;/code&gt;, which the provider requires.&lt;/p&gt;

&lt;h2&gt;
  
  
  A stateless MCP endpoint
&lt;/h2&gt;

&lt;p&gt;The MCP side keeps no session. Every request builds a fresh server for the authenticated account and hands the request to the SDK:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// src/server/mcp/handler.ts&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;handler&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;createMcpHandler&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;createPairpollMcpServer&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;accountId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;handler&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nb"&gt;fetch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;createMcpHandler&lt;/code&gt; in SDK 2.4.0 serves the 2026-07-28 protocol revision from that per-request factory and, by default, falls back to stateless serving for 2025-era clients. Stateless means no Durable Object and no session table. Each tool call is one HTTP exchange that reads and writes D1. The tools call the same server functions as the REST API, so the MCP server has no logic of its own.&lt;/p&gt;

&lt;p&gt;One thing the SDK leaves to you: its handler does no Origin or Host validation. Its docs say to put that in front. Mine is three lines before the handler is built:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// src/server/mcp/handler.ts&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;origin&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Origin"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;origin&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;origin&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="no"&gt;URL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;origin&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;jsonError&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;403&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"invalid_origin"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Send this request from the same origin."&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  The OAuth provider
&lt;/h2&gt;

&lt;p&gt;Here is the core of the configuration, trimmed to the parts that matter:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// src/server/oauth.ts&lt;/span&gt;
&lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;apiRoute&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"/mcp"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;apiHandler&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="cm"&gt;/* checks scope, then calls the MCP handler */&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;defaultHandler&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;authorizeEndpoint&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"/oauth/authorize"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;tokenEndpoint&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"/oauth/token"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;clientRegistrationEndpoint&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"/oauth/register"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;scopesSupported&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="no"&gt;MCP_SCOPE&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;requiredScopes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="no"&gt;MCP_SCOPE&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;resourceMetadata&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;resource&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;mcpResource&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;authorization_servers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;origin&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;resource_name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Pairpoll MCP"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;clientIdMetadataDocumentEnabled&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="c1"&gt;// resolveExternalToken and tokenExchangeCallback below&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;What each line buys:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Client registration.&lt;/strong&gt; &lt;code&gt;clientRegistrationEndpoint&lt;/code&gt; turns on RFC 7591 dynamic client registration. &lt;code&gt;clientIdMetadataDocumentEnabled&lt;/code&gt; turns on Client ID Metadata Documents, where the &lt;code&gt;client_id&lt;/code&gt; is an HTTPS URL the client controls. The MCP 2026-07-28 revision prefers CIMD and deprecates DCR for new work, but clients still use DCR, so I enabled both. CIMD needs the &lt;code&gt;global_fetch_strictly_public&lt;/code&gt; compatibility flag in &lt;code&gt;wrangler.jsonc&lt;/code&gt;, because the server fetches the client's document.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;PKCE.&lt;/strong&gt; The library accepts only S256 for public clients, as MCP requires. Confidential clients may skip PKCE in the library, so the consent page calls a small &lt;code&gt;requireS256&lt;/code&gt; check on every request and refuses anything else.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Resource indicators.&lt;/strong&gt; Every grant and access token is bound to one registered resource, here &lt;code&gt;https://pairpoll.com/mcp&lt;/code&gt;. The token response includes that resource, and a token is accepted only on the route its audience covers.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Hashed tokens.&lt;/strong&gt; The provider stores tokens, codes and client secrets in KV only as hashes. The &lt;code&gt;props&lt;/code&gt; I attach to a grant are encrypted with a key that only the token holder can unwrap.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;I added two things around the provider. Registration and token requests are rate limited per IP in D1, and the token endpoint refuses bodies over 8 KB before the library parses them.&lt;/p&gt;

&lt;h2&gt;
  
  
  The 401 challenge
&lt;/h2&gt;

&lt;p&gt;A client that knows nothing about the server starts with an unauthenticated request. This is the live response:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;$ curl -si -X POST https://pairpoll.com/mcp -H "Content-Type: application/json" -d '{}'
HTTP/2 401
www-authenticate: Bearer realm="OAuth", resource_metadata="https://pairpoll.com/.well-known/oauth-protected-resource/mcp", scope="mcp:tools"
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The provider writes that header. The client follows &lt;code&gt;resource_metadata&lt;/code&gt; to the RFC 9728 document:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nl"&gt;"resource"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="s2"&gt;"https://pairpoll.com/mcp"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="nl"&gt;"authorization_servers"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"https://pairpoll.com"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="nl"&gt;"scopes_supported"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"mcp:tools"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="nl"&gt;"bearer_methods_supported"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"header"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="nl"&gt;"resource_name"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="s2"&gt;"Pairpoll MCP"&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;From there it reads &lt;code&gt;/.well-known/oauth-authorization-server&lt;/code&gt;, which lists the endpoints, &lt;code&gt;code_challenge_methods_supported: ["S256"]&lt;/code&gt; and &lt;code&gt;client_id_metadata_document_supported: true&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;One detail caught my eye in the docs: &lt;code&gt;requiredScopes&lt;/code&gt; is advertised, not enforced. The handler has to check the scope itself, so &lt;code&gt;apiHandler&lt;/code&gt; does:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// src/server/oauth.ts&lt;/span&gt;
&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;oauthContext&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;props&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;access&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s2"&gt;"oauth"&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;oauthContext&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;scope&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;includes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="no"&gt;MCP_SCOPE&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;insufficientScope&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;oauthContext&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="no"&gt;MCP_SCOPE&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  API keys on the same endpoint
&lt;/h2&gt;

&lt;p&gt;Existing users have API keys that start with &lt;code&gt;ppk_&lt;/code&gt;. The provider has a hook for credentials it did not issue:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// src/server/oauth.ts&lt;/span&gt;
&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nf"&gt;resolveExternalToken&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;env&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;authenticate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;DB&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;auth&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;kind&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="s2"&gt;"api_key"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;props&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;accountId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;accountId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;access&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"api_key"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;satisfies&lt;/span&gt; &lt;span class="nc"&gt;OAuthGrantProps&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;audience&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;mcpResource&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The library runs this only after its own token lookup fails, and never for a token in its own &lt;code&gt;userId:grantId:secret&lt;/code&gt; format. So an expired OAuth token is answered as invalid and never falls through to the API key check. The callback must return an &lt;code&gt;audience&lt;/code&gt;, which is the local resource where the key is accepted.&lt;/p&gt;

&lt;p&gt;The library docs are frank that accepting API keys like this sits outside the MCP authorization profile. That is a trade I made on purpose: an API key in a header is what Claude Code, Codex and Cursor configs expect, and the key is minted by this same app, not passed through to another API.&lt;/p&gt;

&lt;p&gt;Both paths end in the same function with an account ID. The &lt;code&gt;access&lt;/code&gt; prop tells it whether to apply OAuth-only checks, such as the scope check above.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why there is a D1 table next to KV
&lt;/h2&gt;

&lt;p&gt;KV is eventually consistent and has no atomic insert. Two things needed stronger guarantees than that.&lt;/p&gt;

&lt;p&gt;First, an authorization code must work once, even under concurrent exchanges. A test fires two exchanges of the same code at once and expects exactly one 200 and one 400. The provider's &lt;code&gt;tokenExchangeCallback&lt;/code&gt; claims the grant in D1, where the insert is atomic:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// src/server/oauth-grants.ts&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;meta&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;prepare&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sb"&gt;`
  INSERT INTO oauth_grant_states (account_id, grant_id, code_exchanged_at)
  VALUES (?, ?, ?)
  ON CONFLICT (account_id, grant_id) DO NOTHING
`&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;bind&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;accountId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;grantId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;now&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;run&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;meta&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;changes&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Second, disconnecting an app must take effect at once. Every MCP call with an OAuth token reads the grant ID out of the token and checks the D1 row for &lt;code&gt;revoked_at&lt;/code&gt;. Revoking writes D1 first and marks the row &lt;code&gt;cleanup_pending&lt;/code&gt;, then revokes the grant in KV. If the KV call fails, the daily cron retries it. Deleting an account goes through the same path for every connected app.&lt;/p&gt;

&lt;p&gt;The consent page uses D1 too. When it shows the Approve button, it stores a hash of the consent handle with the signed-in account and a ten-minute expiry. Approving deletes that row with &lt;code&gt;DELETE ... RETURNING&lt;/code&gt;, so a consent can be used once, by the account that saw it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Tool annotations
&lt;/h2&gt;

&lt;p&gt;Each tool has a title and explicit hints. Claude's connector directory asks for them, and clients can use them to decide when to ask the user before calling a tool.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// src/server/mcp/tools.ts&lt;/span&gt;
&lt;span class="n"&gt;server&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;registerTool&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"open_poll"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;oauthTool&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;title&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Open a poll"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;annotations&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;readOnlyHint&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;destructiveHint&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;description&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Open a draft after 2 to 16 files are ready. Opening freezes its settings and files and returns the voter share link."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;inputSchema&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kt"&gt;object&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;pollId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Opening a poll deletes nothing, but it freezes the poll for good, so I marked it destructive. &lt;code&gt;oauthTool&lt;/code&gt; adds &lt;code&gt;_meta.securitySchemes&lt;/code&gt; with the &lt;code&gt;mcp:tools&lt;/code&gt; scope to every tool.&lt;/p&gt;

&lt;h2&gt;
  
  
  Chat apps cannot attach files
&lt;/h2&gt;

&lt;p&gt;This shaped the tool list more than anything else. A poll needs 2 to 16 images or videos, and chat apps cannot pass an attached file to a connector. I also did not want the server to fetch files from arbitrary URLs, because that opens it to abuse.&lt;/p&gt;

&lt;p&gt;So &lt;code&gt;create_poll&lt;/code&gt; makes an empty draft, and a separate tool returns a browser link to that draft's upload page:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// src/server/mcp/tools.ts&lt;/span&gt;
&lt;span class="n"&gt;description&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Return the browser page for adding local files to a draft poll. Use this because MCP chat clients cannot pass attached images or videos to Pairpoll, and Pairpoll does not fetch remote URLs."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The server's &lt;code&gt;instructions&lt;/code&gt; say the same in one line: create a draft, send the user to the upload link, then open the poll. The link goes through the normal sign-in if the browser is signed out. The model reads the tool description, so putting the reason there means it explains the extra step instead of trying to work around it.&lt;/p&gt;

&lt;h2&gt;
  
  
  What surprised me
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Token rate limits and shared IPs.&lt;/strong&gt; I first limited token requests to 120 an hour per IP. That was too low: hosted connectors such as Claude and ChatGPT refresh tokens for many users from a few shared addresses. The limit is now 3,000 an hour, with a comment saying why.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The Astro adapter adds bindings.&lt;/strong&gt; By default &lt;code&gt;@astrojs/cloudflare&lt;/code&gt; adds a KV binding for Astro sessions and an Images binding. &lt;code&gt;session: false&lt;/code&gt; and &lt;code&gt;imageService: "compile"&lt;/code&gt; in &lt;code&gt;astro.config.mjs&lt;/code&gt; keep them out, so the only KV namespace is the one OAuth needs.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Astro 7 notices coding agents.&lt;/strong&gt; When it detects one, &lt;code&gt;astro dev&lt;/code&gt; runs in the background. &lt;code&gt;npx astro dev --ignore-lock&lt;/code&gt; keeps it in the foreground.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;OAuth needs a public URL to test properly.&lt;/strong&gt; I postponed OAuth until after the first deploy. Locally I test API keys against &lt;code&gt;astro dev&lt;/code&gt; and the OAuth flow against the built Worker in workerd, then once more in production with a test client.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What I left out
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Two Workers.&lt;/strong&gt; The split shape is the library's recommendation, but one resource did not justify it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;More than one scope.&lt;/strong&gt; There is one scope, &lt;code&gt;mcp:tools&lt;/code&gt;. Every tool needs the same access, so per-tool scopes would add consent screens and nothing else.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Sessions.&lt;/strong&gt; No Durable Objects and no session IDs. Each request stands alone.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Fetching files from URLs.&lt;/strong&gt; Covered above.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;An interactive UI inside the chat.&lt;/strong&gt; The tools return JSON text and structured content only.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;ChatGPT's app directory.&lt;/strong&gt; Its review needs a test login without email or magic links, and Pairpoll signs in with an email link only. Anyone can still add the server as a custom connector.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  The project
&lt;/h2&gt;

&lt;p&gt;The app is Pairpoll, a free poll where voters pick the better of two images or videos until their top 1, 3 or 5 is settled, and the creator gets each voter's list plus an overall ranking. The code is at &lt;a href="https://github.com/BuildShipGrowRepeat/pairpoll" rel="noopener noreferrer"&gt;https://github.com/BuildShipGrowRepeat/pairpoll&lt;/a&gt; and the site is &lt;a href="https://pairpoll.com" rel="noopener noreferrer"&gt;https://pairpoll.com&lt;/a&gt;.&lt;/p&gt;

</description>
      <category>mcp</category>
      <category>cloudflare</category>
      <category>oauth</category>
      <category>astro</category>
    </item>
  </channel>
</rss>
