Remote

You can run a remote MCP server on Cloudflare Workers or locally for testing, then connect your MCP clients (like the MCP Inspector or Claude Desktop) to interact with tools securely through an OAuth login flow. This guide walks you through developing locally, connecting to the inspector and Claude Desktop, deploying to Cloudflare, and debugging.

How to use

To use your MCP server, connect your MCP client to the server endpoint and authenticate so you can discover and call defined tools. Start the local server, then point your MCP clients to the SSE endpoint to begin exploring the available tools and workflows.

How to install

Prerequisites: you need Node.js and a package manager. You will also use pnpm for dependency management in development.

Step-by-step commands to develop locally:

git clone https://github.com/cloudflare/ai.git
# Or if using ssh:
# git clone git@github.com:cloudflare/ai.git

cd ai
# Note: using pnpm instead of just "npm"
pnpm install

# run locally
npx nx dev remote-mcp-server

Deploy to Cloudflare

Prepare a Cloudflare Workers deployment by creating an OAuth KV namespace and configuring your Wrangler project, then deploy the MCP server so it can be accessed remotely.

1. npx wrangler kv namespace create OAUTH_KV
2. Follow the guidance to add the kv namespace ID to wrangler.jsonc
3. npm run deploy

Call your newly deployed remote MCP server from a remote MCP client

After deployment, connect a remote MCP client to your Worker by using the remote URL that ends with /sse. Use the MCP Inspector or Claude Desktop configured to reach your workers.dev URL.

npx @modelcontextprotocol/inspector@latest

Then enter the Worker URL (for example, workers.dev/sse) in the inspector to connect.

## Connect Claude Desktop to your local MCP server

You can route Claude Desktop through a local proxy so Claude can call your MCP server over HTTP. Create or edit your Claude configuration file to include the local proxy target.

{ "mcpServers": { "math": { "command": "npx", "args": [ "mcp-remote", "http://localhost:8787/sse" ] } } }

## Connect Claude Desktop to your remote MCP server

Update the Claude configuration to point to your Cloudflare Worker SSE endpoint and restart Claude to connect to the remote MCP server.

{ "mcpServers": { "math": { "command": "npx", "args": [ "mcp-remote", "https://worker-name.account-name.workers.dev/sse" ] } } }

## Debugging

If something goes wrong, restart Claude or try connecting directly to your MCP server from the command line to verify the endpoint works.

npx mcp-remote http://localhost:8787/sse

## Notes and troubleshooting

If you need to clear stored authentication data, you can remove the MCP auth cache from your home directory as a last resort.

rm -rf ~/.mcp-auth