cloudflare / cloudflare/ai

Remote MCP Instructions | OAuth Error

Open
#96 0 comments 0 reactions 0 assignees View on GitHub
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`

![Image](https://github.com/user-attachments/assets/ea04053a-a1be-403c-8296-76da8dedb6c4)

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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.