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.