Remote MCP Instructions | OAuth Error

[eliu-dev]

Existing documentation URL(s)

1. https://github.com/cloudflare/ai/blob/main/demos/remote-mcp-server/README.md#deploy-to-cloudflare
2. (UPDATE NEEDED) https://github.com/cloudflare/ai/blob/main/demos/remote-mcp-server/static/README.md

Issue

The readme under /static diverges from the main README on a crucial point that will lead users to an OAuth error when they attempt to connect to their remote MCP.

The /static README first instructs users to create a new namespace named remote-mcp-server-oauth-kv.

npx wrangler@latest kv namespace create remote-mcp-server-oauth-kv

Finally, it instructs users to follow the installation prompt and update the wrangler.jsonc configuration file with kv_namespaces value from the prompt. That installation prompt implies that the binding property must be updated (example below).

This is incorrect and will cause OAuth errors when attempting to connect to the worker from your local MCP inspector.

> npx wrangler@latest kv namespace create remote-mcp-server-oauth-kv
...
🌀 Creating namespace with title "remote-mcp-server-oauth-kv"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
{
  "kv_namespaces": [
    {
      "binding": "remote-mcp-server-oauth-kv",
      "id": "[SOME_ID]"
    }
  ]
}
...

Analysis and Root Cause

The expected binding should be kept as OAUTH_KV. The top-level README.md seems to work by chance because it uses OAUTH_KV as its example namespace (i.e., the binding will not change during the installation prompt).

npx wrangler@latest kv namespace create OAUTH_KV

I'm not sure what the ultimate root cause is, but a worker configuration file references OAUTH_KV as an enum.

https://github.com/cloudflare/ai/blob/1a3a6deb6e63a42efca139569a9f2ac5cbc0eb26/demos/remote-mcp-server/worker-configuration.d.ts#L5

Repro

1. Run npx wrangler@latest kv namespace create [SOME_NAMESPACE] replacing [SOME_NAMESPACE] with a namespace of your choice.
2. Following the installation prompt (i.e., also updating the binding in wrangler.jsonc)
3. Deploy to cloudflare using npm run deploy
4. Run npx @modelcontextprotocol/inspector@latest to launch the MCP inspector. Note that attempting to connect results in an OAuth error.
5. Update the binding property's value back to OAUTH_KV in wrangler.jsonc
6. Deploy to cloudflare again and attempt to connect via the MCP inspector. Note that the OAuth flow will trigger correctly.

What changes are you suggesting?

• Update the static readme to match the main readme
• Explain the connection between binding and the OAUTH_KV value

Additional information

Redirected from https://github.com/cloudflare/cloudflare-docs/issues/21578#issuecomment-2791105583

No response