DEV Community

Manoj Kumar
Manoj Kumar

Posted on

Your remote MCP server needs OAuth. Here are the 7 things that break when you add it

A local MCP server is easy. You run it over stdio, point Claude Desktop or Cursor at it, done.

The moment you want a remote server, one you paste into Claude or ChatGPT as a URL, things change. A shared API key in a header won't cut it: Claude's custom connectors expect the MCP authorization flow, which is OAuth 2.1 with a specific set of extras. And the official MCP SDKs only give you the resource server half. They verify tokens. They don't issue them. You're told to bring your own authorization server.

I built one (TypeScript on Cloudflare Workers, plus a Python version) and hit every sharp edge on the way. Here are the seven that cost me the most time, with the fix for each.

1. The client never starts the sign-in

Symptom: you add the URL, and the client just says "couldn't connect". No sign-in page ever opens.

Cause: the client discovers auth by calling /mcp without a token and reading the response. The MCP authorization spec (revision 2026-07-28) requires your server, as a resource server, to implement Protected Resource Metadata (RFC 9728). The reliable way to point the client at that document is a 401 with a WWW-Authenticate header:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://your-server.example/.well-known/oauth-protected-resource", scope="mcp:tools"
Enter fullscreen mode Exit fullscreen mode

The scope parameter is recommended, not required; include it so the client knows what to request. The metadata document then names your authorization server, and the client fetches its metadata (RFC 8414, or OpenID Connect Discovery) at /.well-known/oauth-authorization-server.

Return a 403, or a 200 with an error body, and discovery stops. A 401 without the header is not quite as fatal as it looks: clients are required to fall back to the well-known URIs (first under the MCP path, then at the root). Still, include the header. Many implementations start from it, and it's the path the spec prefers.

First thing to check:

curl -i -X POST https://your-server.example/mcp
Enter fullscreen mode Exit fullscreen mode

One more trap: if you serve browser clients, expose the header in CORS (Access-Control-Expose-Headers: WWW-Authenticate, Mcp-Protocol-Version, Mcp-Session-Id), or the browser hides it from the client's JavaScript.

2. PKCE is not optional, and only S256 counts

OAuth 2.1 makes PKCE mandatory, and the MCP spec requires S256 when the client can use it. Clients must also refuse to proceed if your authorization server metadata doesn't advertise code_challenge_methods_supported. Accepting plain, or skipping PKCE when the challenge is missing, is the kind of shortcut a security reviewer flags straight away. Reject both at /authorize:

const challenge = q.get('code_challenge');
if (!challenge || q.get('code_challenge_method') !== 'S256')
  return fail('invalid_request', 'PKCE with code_challenge_method=S256 is required');
if (!/^[A-Za-z0-9\-_]{43}$/.test(challenge))
  return fail('invalid_request', 'Malformed code_challenge');
Enter fullscreen mode Exit fullscreen mode

Advertise it too: code_challenge_methods_supported: ["S256"] in your AS metadata. Some clients check this before they start.

3. Clients register themselves, in two different ways

Claude, ChatGPT, Cursor and Claude Code don't arrive with a pre-shared client ID. The 2026-07-28 MCP spec supports three registration mechanisms, in this order of preference: pre-registered credentials, then Client ID Metadata Documents (CIMD), then Dynamic Client Registration (RFC 7591) as a fallback.

CIMD is now the preferred path: newer clients use an HTTPS URL as the client_id, and you fetch that URL to read their redirect URIs. Advertise it with client_id_metadata_document_supported: true in your authorization server metadata.

DCR is still worth supporting, but it is deprecated in this revision and kept only for older clients. The client POSTs its name and redirect URIs to /register and gets a client_id back. Supporting only DCR, or only CIMD, means some clients work and others fail at the first step.

Also, desktop tools such as Claude Code and Cursor use loopback redirects on random ports (http://127.0.0.1:53817/callback). Exact-string redirect matching breaks them. Per RFC 8252 you should ignore the port for loopback IP URIs. Prefer 127.0.0.1 over localhost (RFC 8252 recommends this, because localhost can surprise you with IPv6). They are not the same host; don't treat a registered 127.0.0.1 URI as interchangeable with localhost unless you have explicitly allowed both.

4. Sign-in works, then every call is 401

This one hurt the most. Everything looks fine, the consent page completes, and then every tool call is rejected.

Cause: audience binding. With Resource Indicators (RFC 8707) the client must send resource=https://your-server.example/mcp on both the authorization request and the token request, and the token you issue should carry that as its aud. Your resource server then checks it. That's correct and important, because it stops a token minted for one server from being replayed against another. But it means the URL the user pasted has to match your configured public URL exactly: no www vs bare domain, no custom domain vs *.workers.dev, no stray trailing slash (the spec prefers the form without one unless the slash is meaningful).

The 2026-07-28 revision also asks authorization servers to return the iss parameter (RFC 9207) on the authorization response, and clients to check it before exchanging the code. If you advertise authorization_response_iss_parameter_supported: true and then omit iss, compliant clients will reject the response.

Fix: one PUBLIC_URL config value, used for metadata, token audience and the Host check, and tell users to paste exactly that.

5. Refresh tokens need rotation and reuse detection

Connectors stay connected for weeks, so you'll issue refresh tokens. For public clients, OAuth 2.1 and the OAuth security BCP (RFC 9700) want them rotated: every refresh returns a new refresh token and kills the old one.

The part most tutorials skip is what happens when an old refresh token shows up again. That means it leaked, or two copies are racing. The safe response is to revoke the whole token family, so both the attacker and the legitimate client have to sign in again:

// Reuse of a rotated token means it leaked: revoke the whole family.
Enter fullscreen mode Exit fullscreen mode

Store refresh tokens and auth codes hashed, not raw, so a storage dump doesn't hand out live sessions. And support revocation (RFC 7009) so "disconnect" in the client really disconnects.

6. Your storage isn't as persistent as you think

Symptom: users get signed out after every deploy.

Registered clients, codes and refresh tokens need durable storage. An in-memory map works in tests and on npm run dev, then vanishes on the next cold start. On Cloudflare Workers, use KV. On Vercel, use a free Upstash Redis. On a VPS, use a file or SQLite on a real volume. Write a tiny KV interface with TTLs once, and swap the backend per runtime.

7. A public URL is a public attack surface

Once the server is on the internet:

  • Check the Host header against your public hostname. This blocks DNS-rebinding attacks on local and dev instances. Side effect: Vercel preview URLs fail by design, so test on the production domain.
  • Check Origin for browser requests. Server-to-server clients like Claude and ChatGPT don't send one, but browsers always do.
  • Lock down the consent page: Cache-Control: no-store, anti-framing (frame-ancestors 'none'), a strict CSP, constant-time password comparison, and a lockout after a few wrong tries.
  • Fail closed: if the auth config is missing or broken, refuse to serve /mcp rather than falling back to "no auth". Never allow auth=none on a non-localhost URL.

Bonus: test the whole dance, not just the pieces

Unit tests for each endpoint didn't catch half of these bugs. What did was a smoke script that plays the client: it hits /mcp, follows the 401 to the metadata, registers, does PKCE, submits the consent form, exchanges the code, calls a tool, and refreshes to confirm the refresh token actually rotated. (Replay of an old refresh token lives in the regular test suite.) Run it against your live URL after every deploy. It tells you which step broke, which beats a client's "couldn't connect".

Wrap-up

Remote MCP is where agents get genuinely useful: your tools, from Claude on your phone, ChatGPT, Cursor and Claude Code, all behind one sign-in. The auth layer is the toll you pay for that. None of it is exotic, but the requirements are spread across OAuth 2.1 and several RFCs (9728, 8414, 8707, 9207, 8252, 7009, plus the CIMD draft), and the failure modes are silent.

If you're building one, start with the 401 + WWW-Authenticate check, get audience binding right, prefer CIMD and keep DCR only as a fallback, and write the smoke test early.

If you want this wired up already, I packaged the TypeScript and Python template as the Remote MCP Connector Kit.

I'm Manoj, an AI engineer in Ireland building MCP servers and agents. Questions or war stories about MCP auth? Drop them in the comments.

Top comments (1)

Collapse
 
x1y1co profile image
X1Y1 •

Points 3 and 4 match what we saw from the outside. On November 4 we checked 61 login-protected vendor MCP servers. All 61 returned the 401 and got PKCE right, so steps 1 and 2 are mostly solved in production. The gaps were the newer parts: 36 did not advertise Client ID Metadata Documents, and 40 did not advertise the RFC 9207 iss parameter. So the majority are not yet on the registration path the spec now prefers. Your smoke script is the right fix, and I'd add one assertion: fetch the AS metadata and fail the deploy if client_id_metadata_document_supported or authorization_response_iss_parameter_supported is missing.