{"title":"How Remote MCP Servers Trigger OAuth Sign-In","html_url":"https://deallocatedobjects.com/posts/how-remote-mcp-servers-trigger-oauth-sign-in","source_url":"","markdown_content":"When someone pastes your MCP server's URL into Claude or ChatGPT, a sign-in window should open. What makes that happen is one HTTP response from your server. I run a few remote MCP servers with OAuth, and the response those clients need is the same one that gets a server marked as down in directories.\n\n### The Response That Starts It\n\nThe flow in the [MCP authorization spec](https://modelcontextprotocol.io/specification/draft/basic/authorization) begins when the client's request gets a 401 with a `WWW-Authenticate` header pointing at your protected resource metadata:\n\n```\nHTTP/1.1 401 Unauthorized\nWWW-Authenticate: Bearer resource_metadata=\"https://example.com/.well-known/oauth-protected-resource/mcp\"\nAccess-Control-Expose-Headers: WWW-Authenticate\n```\n\nThe expose header is there for clients running in a browser. Without it, their JavaScript can't read the challenge.\n\nThat URL returns a small JSON document ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)) naming your authorization server:\n\n```json\n{\n \"resource\": \"https://example.com/mcp\",\n \"authorization_servers\": [\"https://example.com\"],\n \"bearer_methods_supported\": [\"header\"],\n \"scopes_supported\": [\"mcp\"]\n}\n```\n\nFrom there the client reads your authorization server's metadata, registers itself and opens the browser. I serve the metadata at both `/.well-known/oauth-protected-resource/mcp` and the bare `/.well-known/oauth-protected-resource`, because some clients try the root first.\n\n### Two Callers Want Opposite Things\n\nIf an anonymous `initialize` returns 200, an OAuth-capable client can decide your server needs no auth. It connects, lists the tools and only fails later on `tools/call`, with no sign-in window. So those clients need the 401 on their very first request.\n\nDirectories and health checkers want the opposite. They call `initialize` and `tools/list` with no credentials, and many of them read a 401 as an outage. [CallForMe](https://callforme.tel/?ref=deallocated-post) logged about 700 of those 401s from checkers in two days, and one directory listed it as \"Unhealthy, 0.0% uptime over 32 days\" while it was running fine.\n\n### Answer By Who's Asking\n\nSo the endpoint looks at the caller. This is the version in [Taskhold](https://taskhold.com/?ref=deallocated-post), trimmed down. Clients that sign in get challenged, and everything else can read the public parts:\n\n```ts title=\"app/api/mcp/route.ts\"\nconst ANONYMOUS_METHODS = new Set([\n \"initialize\", \"server/discover\", \"notifications/initialized\",\n \"tools/list\", \"ping\", \"prompts/list\", \"resources/list\",\n]);\n\nconst OAUTH_CLIENT_UA = /\\b(Claude-User|claude-ai|openai-mcp|ChatGPT|claude-code|Cursor|codex-mcp-client|Visual Studio Code|goose)\\b/i;\nconst OAUTH_CLIENT_NAME = /\\b(gemini|visual studio code|vscode|windsurf|zed)\\b/i;\n\nasync function isDiscoveryOnly(request: Request): Promise {\n if (request.headers.get(\"Authorization\")) return false;\n if (OAUTH_CLIENT_UA.test(request.headers.get(\"User-Agent\") ?? \"\")) return false;\n try {\n const body = await request.clone().json();\n const msgs = Array.isArray(body) ? body : [body];\n if (msgs.some((m) => m?.method === \"initialize\" && OAUTH_CLIENT_NAME.test(String(m?.params?.clientInfo?.name ?? \"\")))) return false;\n return msgs.length > 0 && msgs.every((m) => typeof m?.method === \"string\" && ANONYMOUS_METHODS.has(m.method));\n } catch {\n return false;\n }\n}\n```\n\nThe User-Agent catches most clients. Some send something generic like `node`, and those name themselves in `clientInfo` inside the `initialize` body, which is why there's a second regex.\n\nA spoofed User-Agent gets a caller nothing here, since the list only decides who sees a challenge. Every tool that touches data still needs a token, and anonymous requests run against a backend that throws on any call.\n\n### Which Default To Pick\n\nTaskhold defaults to anonymous and challenges a list of known OAuth clients. CallForMe does the inverse: it defaults to the 401 and opens up for a list of known checkers. Your choice decides who gets the wrong answer when a caller you've never seen shows up:\n\n- With a list of OAuth clients, a new client gets a 200 and may not offer sign-in until someone adds it.\n- With a list of checkers, a new checker gets a 401 and may list you as down.\n\nI'd pick by which mistake costs you more. CallForMe also matches checkers by how they describe themselves (`mcp-?index`, `health-?check`, `crawler`), so new ones don't sit on a 401 until I notice them.\n\nThere are exceptions on both sides. The CI for [awesome-remote-mcp-servers](https://github.com/punkpeye/awesome-remote-mcp-servers) labels a server by its `initialize` reply: 200 means no auth, and a 401 with `resource_metadata` means OAuth. An OAuth server that wants the right label has to challenge that checker too, so it's in Taskhold's full list.\n\n### Log The 401s\n\nSome clients see the challenge and never finish. `codex mcp add --url` without `codex mcp login` hit a 401 on every session: in early November my logs showed 7 IPs stuck in one day and no completed Codex sign-ins in 3 days. CallForMe now lets unauthenticated Codex sessions into a public mode that needs no sign-in, and signed-in ones keep their token. Another runtime registered with the OAuth server, never called `/authorize` and kept retrying hourly.\n\nI only found these by logging each 401 with its User-Agent, limited to once per IP and client every 6 hours. Comparing that against completed sign-ins shows which clients get stuck.\n\nYou can check your own server's answer with curl by changing the User-Agent:\n\n```bash\ncurl -si -X POST https://example.com/mcp \\\n -H 'Content-Type: application/json' \\\n -H 'Accept: application/json, text/event-stream' \\\n -H 'User-Agent: claude-code/2.0' \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1\"}}}' \\\n | head -5\n```\n\nRun it once with that header and once with `User-Agent: directory-check`. The first should return the 401 and the second a 200, unless your server is one that challenges everyone by default.","html_content":"

When someone pastes your MCP server’s URL into Claude or ChatGPT, a sign-in window should open. What makes that happen is one HTTP response from your server. I run a few remote MCP servers with OAuth, and the response those clients need is the same one that gets a server marked as down in directories.

\n

The Response That Starts It

\n

The flow in the MCP authorization spec begins when the client’s request gets a 401 with a WWW-Authenticate header pointing at your protected resource metadata:

\n
HTTP/1.1 401 Unauthorized\nWWW-Authenticate: Bearer resource_metadata=\"https://example.com/.well-known/oauth-protected-resource/mcp\"\nAccess-Control-Expose-Headers: WWW-Authenticate

The expose header is there for clients running in a browser. Without it, their JavaScript can’t read the challenge.

\n

That URL returns a small JSON document (RFC 9728) naming your authorization server:

\n
JSON
{\n  \"resource\": \"https://example.com/mcp\",\n  \"authorization_servers\": [\"https://example.com\"],\n  \"bearer_methods_supported\": [\"header\"],\n  \"scopes_supported\": [\"mcp\"]\n}

From there the client reads your authorization server’s metadata, registers itself and opens the browser. I serve the metadata at both /.well-known/oauth-protected-resource/mcp and the bare /.well-known/oauth-protected-resource, because some clients try the root first.

\n

Two Callers Want Opposite Things

\n

If an anonymous initialize returns 200, an OAuth-capable client can decide your server needs no auth. It connects, lists the tools and only fails later on tools/call, with no sign-in window. So those clients need the 401 on their very first request.

\n

Directories and health checkers want the opposite. They call initialize and tools/list with no credentials, and many of them read a 401 as an outage. CallForMe logged about 700 of those 401s from checkers in two days, and one directory listed it as “Unhealthy, 0.0% uptime over 32 days” while it was running fine.

\n

Answer By Who’s Asking

\n

So the endpoint looks at the caller. This is the version in Taskhold, trimmed down. Clients that sign in get challenged, and everything else can read the public parts:

\n
app/api/mcp/route.tsTypeScript
const ANONYMOUS_METHODS = new Set([\n  \"initialize\", \"server/discover\", \"notifications/initialized\",\n  \"tools/list\", \"ping\", \"prompts/list\", \"resources/list\",\n]);\n\nconst OAUTH_CLIENT_UA = /\\b(Claude-User|claude-ai|openai-mcp|ChatGPT|claude-code|Cursor|codex-mcp-client|Visual Studio Code|goose)\\b/i;\nconst OAUTH_CLIENT_NAME = /\\b(gemini|visual studio code|vscode|windsurf|zed)\\b/i;\n\nasync function isDiscoveryOnly(request: Request): Promise<boolean> {\n  if (request.headers.get(\"Authorization\")) return false;\n  if (OAUTH_CLIENT_UA.test(request.headers.get(\"User-Agent\") ?? \"\")) return false;\n  try {\n    const body = await request.clone().json();\n    const msgs = Array.isArray(body) ? body : [body];\n    if (msgs.some((m) => m?.method === \"initialize\" && OAUTH_CLIENT_NAME.test(String(m?.params?.clientInfo?.name ?? \"\")))) return false;\n    return msgs.length > 0 && msgs.every((m) => typeof m?.method === \"string\" && ANONYMOUS_METHODS.has(m.method));\n  } catch {\n    return false;\n  }\n}

The User-Agent catches most clients. Some send something generic like node, and those name themselves in clientInfo inside the initialize body, which is why there’s a second regex.

\n

A spoofed User-Agent gets a caller nothing here, since the list only decides who sees a challenge. Every tool that touches data still needs a token, and anonymous requests run against a backend that throws on any call.

\n

Which Default To Pick

\n

Taskhold defaults to anonymous and challenges a list of known OAuth clients. CallForMe does the inverse: it defaults to the 401 and opens up for a list of known checkers. Your choice decides who gets the wrong answer when a caller you’ve never seen shows up:

\n\n

I’d pick by which mistake costs you more. CallForMe also matches checkers by how they describe themselves (mcp-?index, health-?check, crawler), so new ones don’t sit on a 401 until I notice them.

\n

There are exceptions on both sides. The CI for awesome-remote-mcp-servers labels a server by its initialize reply: 200 means no auth, and a 401 with resource_metadata means OAuth. An OAuth server that wants the right label has to challenge that checker too, so it’s in Taskhold’s full list.

\n

Log The 401s

\n

Some clients see the challenge and never finish. codex mcp add --url without codex mcp login hit a 401 on every session: in early November my logs showed 7 IPs stuck in one day and no completed Codex sign-ins in 3 days. CallForMe now lets unauthenticated Codex sessions into a public mode that needs no sign-in, and signed-in ones keep their token. Another runtime registered with the OAuth server, never called /authorize and kept retrying hourly.

\n

I only found these by logging each 401 with its User-Agent, limited to once per IP and client every 6 hours. Comparing that against completed sign-ins shows which clients get stuck.

\n

You can check your own server’s answer with curl by changing the User-Agent:

\n
Shell
curl -si -X POST https://example.com/mcp \\\n  -H 'Content-Type: application/json' \\\n  -H 'Accept: application/json, text/event-stream' \\\n  -H 'User-Agent: claude-code/2.0' \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1\"}}}' \\\n  | head -5

Run it once with that header and once with User-Agent: directory-check. The first should return the 401 and the second a 200, unless your server is one that challenges everyone by default.

","created_at":"2026-11-09T14:00:00.000Z","updated_at":"2026-11-09T14:00:00.000Z"}