Deploying an MCP Service Backend on Cloudflare Workers

This guide details how to instantiate a robust, remote MCP service gateway hosted on Cloudflare Workers, complete with necessary OAuth security layers.

Local Development Environment Setup

To begin working on the service locally:

bash

Obtain the source repository

git clone git@github.com:cloudflare/ai.git

Navigate to the directory and install dependencies

cd ai npm install

Initiate the local development server instance

npx nx dev remote-mcp-server

The running service should become accessible via your local browser at http://localhost:8787/.

Linking with the MCP Inspector Utility

You can use the MCP Inspector client to interact with and validate your newly established MCP API surface.

1. Launch the inspector utility from your terminal: npx @modelcontextprotocol/inspector
2. Within the inspector interface (typically at http://localhost:5173), adjust the Transport Mechanism to SSE.
3. Input the local server stream endpoint, http://localhost:8787/sse, as the target MCP server address, and click "Establish Connection".
4. A placeholder authentication prompt will appear; entering any dummy credentials will simulate successful login.
5. Upon successful redirection, the Inspector will list all available tools, enabling direct invocation.

Configuring Claude Desktop for Local Interaction

While the Inspector is useful, true integration involves connecting the Claude AI application. Refer to Anthropic's Quickstart documentation for general setup. Locate and open the configuration file under Claude Desktop's Settings > Developer > Edit Config. Replace its contents with the following structure to route requests through a local intermediary:

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

This configuration activates a local proxy, enabling Claude to communicate with your locally hosted MCP backend via HTTP. When Claude launches, a browser window should prompt for login, and subsequently, the available tools will appear in the application's interface, ready for invocation based on user prompts.

Production Deployment to Cloudflare Infrastructure

To move the service to a live environment:

1. Provision the required persistent storage: npx wrangler kv namespace create OAUTH_KV
2. Incorporate the generated KV namespace ID into your wrangler.jsonc configuration file as instructed.
3. Execute the deployment command: npm run deploy

Accessing the Deployed Remote MCP Host from a Client

Similar to the local testing phase, initialize the MCP Inspector utility:

npx @modelcontextprotocol/inspector@latest

Then, input the public endpoint URL of your deployed Worker (e.g., worker-name.account-name.workers.dev/sse) into the inspector interface and connect.

You have now successfully linked a remote MCP client to your Cloudflare Worker-hosted service.

Connecting Claude Desktop to the Live Worker Endpoint

Update the Claude configuration file, replacing the local address with your production workers.dev URL (e.g., worker-name.account-name.workers.dev/sse), and then restart the Claude application:

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

Troubleshooting Guide

If connection issues arise, try restarting Claude first. A direct command-line test against the server can isolate the problem:

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

In infrequent scenarios involving authentication state persistence issues, manually deleting stored credentials might resolve the matter:

bash rm -rf ~/.mcp-auth