Establishing a Remote MCP Endpoint via Cloudflare Workers

This guide details deploying an MCP server instance on Cloudflare Workers, secured with OAuth-based bearer token authentication.

Local Development Setup

To commence development locally, follow these steps:

bash

Obtain the source code repository

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

Navigate into the project directory and install dependencies

cd ai npm install

Launch the local development server for this specific component

npx nx dev remote-mcp-server-bearer-auth

You should now be able to access the service endpoint, typically located at http://localhost:8787/.

Integrating the MCP Inspector

To visually inspect and interact with your newly established MCP API, utilize the MCP Inspector tool:

• Initiate the inspector from your terminal: npx @modelcontextprotocol/inspector
• Within the inspector interface (usually running at http://localhost:5173), adjust the connection protocol to SSE.
• Input the local server's streaming URL: http://localhost:8787/sse.
• Input your requisite bearer authorization credential and press "Connect".
• Execute the "List Tools" command.
• Run the "getToken" utility; the expected outcome is the return of the Authorization header you initially provided.

Configuring Claude Desktop for Local Connection

To direct Claude Desktop to use your local, self-hosted MCP gateway, configure your connection settings as follows:

"remote-example": {
  "command": "npx",
  "args": [
    "mcp-remote",
    "http://localhost:8787/sse",
    "--header",
    "Authorization: Bearer {token}"
  ]
}

Deployment to Cloudflare Infrastructure

To push your configuration live onto the Cloudflare network, execute the deployment script:

npm run deploy

Remote Client Communication Test

To verify connectivity from a remote MCP client to your deployed Worker endpoint, follow the initial inspection procedure again:

npx @modelcontextprotocol/inspector@latest

In the inspector, substitute the local URL with the public endpoint provided by Cloudflare (e.g., worker-name.account-name.workers.dev/sse). Ensure you supply the correct bearer token upon connection.

You have successfully linked a remote client to your hosted MCP gateway.

Connecting Claude Desktop Remotely

Note: Support for injecting arbitrary HTTP headers into the mcp-remote proxy mechanism is pending implementation.

Troubleshooting Guide

If connectivity issues arise, consider these diagnostic steps. Restarting the Claude application is often beneficial. Furthermore, direct CLI testing against the gateway can isolate the issue:

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

In rare scenarios where authentication persistence seems problematic, purging cached authentication artifacts might resolve the issue:

bash rm -rf ~/.mcp-auth