Remote MCP Instructions | OAuth Error
- Dominant language
- TypeScript
- Stars
- 1.2k
- Forks
- 345
- Avg merge
- 13h 31m
- Merged PRs (30d)
- 1
Description
### 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_
Contributor guide
Research direction
Compare demos/remote-mcp-server/static/README.md with demos/remote-mcp-server/README.md#deploy-to-cloudflare, then inspect wrangler.jsonc and worker-configuration.d.ts. Update the static instructions to explain the expected binding and namespace setup, and verify the documented deployment and MCP Inspector OAuth flow using the listed commands.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100