Cloudflare Remote MCP Server

Cloudflare Remote MCP Server

A Model Context Protocol (MCP) server implementation running on Cloudflare Workers with Durable Objects.

Features

• Remote MCP Server: HTTP Streamable transport-based MCP server accessible over the internet
• Durable Objects: Stateful request processing using Cloudflare Durable Objects
• Sample Tools: Demonstration tools for MCP protocol
• Sample Resources: Static data resources accessible via MCP
• Sample Prompts: Pre-built prompts for AI interactions
• CORS Support: Web-friendly with Cross-Origin Resource Sharing

Architecture

┌─────────────────┐  HTTP POST + SSE  ┌──────────────────┐
│   MCP Client    │ ◄──────────────► │ Cloudflare       │
│   (AI/Claude)   │                  │ Worker           │
└─────────────────┘                  └─────────┬────────┘
                                               │
                                               ▼
                                     ┌──────────────────┐
                                     │ MCPServerObject  │
                                     │ (Durable Object) │
                                     │                  │
                                     │ • MCP Protocol   │
                                     │ • HTTP Processing│
                                     │ • Request State  │
                                     └──────────────────┘

Available Capabilities

Tools

• echo: Echo back input text
• get_time: Get current timestamp
• random_number: Generate random number between min and max

Resources

• cloudflare://worker-info: Information about the Cloudflare Worker
• cloudflare://sample-data: Sample JSON data for testing

Prompts

• explain_code: Generate prompts to explain code
• debug_help: Generate prompts for debugging assistance

Deployment

1. Install dependencies:

   npm install
   

2. Deploy to Cloudflare:

   npm run deploy
   

3. Access your MCP server at the deployed URL

Development

1. Start local development:

   npm run dev
   

2. Test the server:

   # Get server info
   curl http://localhost:8787/
   
   # Test MCP endpoint with a simple request
   curl -X POST http://localhost:8787/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   

Usage

HTTP API

• GET / - Server information and capabilities
• POST /mcp - MCP HTTP Streamable endpoint

MCP Connection

Connect MCP clients to the HTTP endpoint:

• Local: http://localhost:8787/mcp
• Production: https://your-worker.your-subdomain.workers.dev/mcp

Protocol Details

The server uses HTTP Streamable transport:

• Request: HTTP POST with JSON-RPC message in body
• Response: Server-Sent Events (SSE) stream with text/event-stream content type
• Format: Each response is sent as data: {JSON}\n\n

Example MCP Messages

List Tools

curl -X POST http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Call Tool

curl -X POST http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "echo",
      "arguments": {
        "text": "Hello, MCP!"
      }
    }
  }'

List Resources

curl -X POST http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "resources/list"
  }'

Configuration

The server is configured in wrangler.jsonc:

• Durable Objects: MCPServerObject handles stateful MCP request processing
• Compatibility Date: Set to current date for latest Cloudflare Workers features

Development Notes

• Uses @modelcontextprotocol/sdk for MCP protocol implementation
• HTTP requests are processed by Durable Objects for state management
• Responses are streamed using Server-Sent Events (SSE)
• CORS is enabled for web client compatibility
• Error handling includes JSON-RPC error responses
• TypeScript with strict mode enabled

Transport Protocol

This implementation uses HTTP Streamable transport instead of WebSocket:

• More compatible with proxies and firewalls
• Uses standard HTTP semantics
• Supports Server-Sent Events for real-time responses
• Better suited for stateless cloud environments

License

This is a sample implementation for educational purposes.