🚀 MCP Streamable HTTP Server Template

✨ A reusable template for building streamable HTTP transport MCP servers that can be quickly deployed to Cloudflare Workers free tier. This template provides a complete foundation for creating Model Context Protocol (MCP) servers with real-time streaming capabilities and dual deployment support.

---

🎯 What This Template Provides

• 🔧 Complete MCP Implementation: Full Model Context Protocol server implementation using the official @modelcontextprotocol/sdk
• ⚡ Streamable HTTP Transport: Server-Sent Events (SSE) support for real-time client notifications
• ☁️ Cloudflare Workers Integration: Optimized for deployment to Cloudflare Workers free tier
• 🔄 Dual Runtime Support: Works in both Node.js development environment and Cloudflare Workers production
• 👥 Multi-session Handling: Supports multiple simultaneous client connections
• 💻 TypeScript Foundation: Fully typed codebase with proper configuration
• 📝 Example Implementation: Working example to demonstrate usage patterns

---

🚀 Quick Start

1. 📦 Clone and Setup

# Clone this template (replace with your repo URL)
git clone <your-template-repo-url>
cd your-mcp-server

# Install dependencies
npm install

2. 🔧 Environment Setup

# Copy the example environment file
cp .env.example .env

# Edit .env with your configuration
# Update API keys, database URLs, and other settings as needed

3. 💻 Local Development

# Build the project
npm run build

# Run locally with Node.js
node build/index.js

# Or specify a custom port
node build/index.js --port=9000

🌐 The server will start at http://localhost:8123 by default (or the port specified in your .env file).

4. ☁️ Cloudflare Workers Development

# Start local Workers development server
npm run dev:worker

# Build for Workers deployment
npm run build:worker

5. 🚀 Deploy to Cloudflare Workers

# Deploy to Cloudflare Workers (free tier)
npm run deploy

✅ Success! Your MCP server is now live on the edge! 🎉

---

🏗️ Core Architecture

🔄 Dual Runtime Support

This template is designed to work in both environments:

• 💻 Node.js: Full Express.js server for local development and traditional hosting
• ☁️ Cloudflare Workers: Optimized worker implementation for edge deployment

🧩 Key Components

├── src/
│   ├── index.ts           # 💻 Node.js Express server entry point
│   ├── worker.ts          # ☁️ Cloudflare Workers entry point  
│   ├── worker-transport.ts # ⚡ Workers-optimized HTTP transport
│   ├── server.ts          # 🔧 Core MCP server implementation
├── example-client.js      # 🧪 Example client for testing
├── wrangler.toml         # ☁️ Cloudflare Workers configuration
├── tsconfig.json         # 💻 Node.js TypeScript config
└── tsconfig.worker.json  # ☁️ Workers TypeScript config

---

✨ Customizing the Template

1. 🔧 Define Your Tools

Edit src/server.ts to implement your specific MCP tools:

// Add your custom tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "your-custom-tool",
        description: "Description of what your tool does",
        inputSchema: {
          type: "object",
          properties: {
            // Define your tool's parameters
          },
        },
      },
    ],
  };
});

// Implement your tool logic
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  
  switch (name) {
    case "your-custom-tool":
      // Implement your tool logic here
      return {
        content: [
          {
            type: "text",
            text: "Your tool response"
          }
        ]
      };
    default:
      throw new McpError(ErrorCode.MethodNotFound, `Tool not found: ${name}`);
  }
});

2. ☁️ Configure Workers Deployment

Update wrangler.toml:

name = "your-mcp-server-name"
main = "src/worker.ts"
compatibility_date = "2024-12-06"

[vars]
# Add your environment variables
API_KEY = "your-api-key"

3. 📦 Update Package Metadata

Modify package.json:

{
  "name": "your-mcp-server",
  "description": "Your MCP server description",
  "version": "1.0.0"
}

---

🌐 API Endpoints

The server exposes a single MCP endpoint at /mcp:

• 📤 POST /mcp: Handle MCP JSON-RPC requests
• 📡 GET /mcp: Establish Server-Sent Events (SSE) stream for real-time notifications

📋 Example MCP Request

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "your-tool-name",
    "arguments": {
      "param1": "value1"
    }
  }
}

---

✨ Features

🔐 Security & Authentication

• 🔑 Optional API Key Authentication: Secure your MCP server with configurable API key authentication
• 🎛️ Flexible Authentication Formats: Support for both Bearer <token> and direct API key formats
• 🌍 Environment-Controlled: Enable/disable authentication via environment variables
• 🌐 CORS-Compatible: Proper CORS headers for cross-origin authentication

📡 Streaming HTTP Transport

• ⚡ Real-time Notifications: Server-Sent Events for live updates
• 👥 Multi-session Support: Handle multiple concurrent client connections
• 🔄 Dynamic Updates: Real-time tool and resource updates with client notifications

☁️ Cloudflare Workers Optimization

• 💰 Free Tier Compatible: Designed to work within Cloudflare Workers free tier limits
• 🌍 Edge Performance: Global edge deployment for low latency
• 🏗️ Serverless Architecture: Pay-per-request pricing model
• ⚡ Zero Cold Start: Optimized for fast startup times

🛠️ Development Experience

• 💻 TypeScript Support: Full type safety and IntelliSense
• 🔥 Hot Reload: Fast development iteration with wrangler dev
• 🚨 Error Handling: Comprehensive error handling and logging
• 🧪 Example Client: Ready-to-use client for testing with authentication examples

---

🧪 Testing Your Server

Use the included example client to test your implementation:

# Start your server
npm run build && node build/index.js

# In another terminal, test with the example client
node example-client.js

The example client demonstrates:

1. 🔌 MCP connection initialization
2. 🔍 Tool discovery and listing
3. ⚙️ Tool execution with parameters
4. 🚨 Error handling
5. 🔐 Authentication examples (configure USE_AUTH and API_KEY in the client)

💡 Note: If you enable authentication on your server (MCP_AUTH_REQUIRED=true), make sure to update the authentication configuration in example-client.js by setting USE_AUTH=true and providing your API_KEY.

---

🚀 Deployment Options

☁️ Cloudflare Workers (Recommended)

• 💰 Free tier: 100,000 requests/day
• 🌍 Global edge: Low latency worldwide
• 🔧 Zero maintenance: Serverless infrastructure

🖥️ Traditional Hosting

• 💻 Node.js: Deploy to any Node.js hosting platform
• 🌐 Express.js: Full HTTP server capabilities
• 🎯 Custom domains: Complete control over deployment

---

🔧 Environment Variables

💻 Node.js Development (.env file)

For local Node.js development, copy .env.example to .env and configure:

# Copy the example file
cp .env.example .env

📋 Required Variables

• PORT: Server port (default: 8123)
• ENVIRONMENT: Current environment (development/production)

⚙️ Optional Variables

• MCP_SERVER_NAME: Name of your MCP server (default: "mcp-server")
• MCP_SERVER_VERSION: Version of your MCP server (default: "1.0.0")
• MCP_SESSION_HEADER_NAME: Header name for session ID (default: "mcp-session-id")

🔐 Authentication Variables

• MCP_AUTH_REQUIRED: Enable/disable API key authentication (true/false, default: false)
• MCP_API_KEY: API key for client authentication (required if MCP_AUTH_REQUIRED=true)
• MCP_AUTH_HEADER_NAME: Header name for API key (default: "Authorization")

🌤️ Weather API Configuration (for example weather tools)

• WEATHER_API_BASE_URL: Weather API base URL (default: "https://api.weather.gov")
• USER_AGENT: User agent string for API requests (default: "weather-app/1.0")

🔑 API Keys (configure as needed for your tools)

• WEATHER_API_KEY: Weather service API key
• OPENAI_API_KEY: OpenAI API key
• GOOGLE_API_KEY: Google services API key
• ANTHROPIC_API_KEY: Anthropic API key

🔗 External Services

• DATABASE_URL: Database connection string
• REDIS_URL: Redis connection string
• EXTERNAL_API_URL: External API base URL

🌐 CORS Configuration

• CORS_ORIGIN: Allowed origins (default: "*")
• CORS_METHODS: Allowed HTTP methods (default: "GET, POST, OPTIONS")
• CORS_HEADERS: Allowed headers (default: "Content-Type, mcp-session-id")

🎛️ Feature Flags

• ENABLE_LOGGING: Enable detailed logging (true/false)
• ENABLE_DEBUG_MODE: Enable debug mode (true/false)

☁️ Cloudflare Workers (.dev.vars file)

For Cloudflare Workers development, copy .dev.vars.example to .dev.vars and configure similarly.

💡 Note: The .env file is for Node.js development, while .dev.vars is for Cloudflare Workers. Both files are ignored by git for security.

---

🔐 Authentication

This MCP server supports optional API key authentication to secure access to your server endpoints.

🔑 Enabling Authentication

Authentication is controlled by environment variables and is disabled by default. To enable authentication:

1. Set authentication environment variables in your .env file (Node.js) or .dev.vars file (Cloudflare Workers):

# Enable authentication
MCP_AUTH_REQUIRED=true

# Set your API key (keep this secure!)
MCP_API_KEY=your-secure-api-key-here

# Optional: customize the header name (default: Authorization)
MCP_AUTH_HEADER_NAME=Authorization

2. Restart your server after updating the environment variables.

🎯 Supported Authentication Formats

The server supports two authentication formats:

🏷️ Bearer Token Format (Recommended)

Authorization: Bearer your-api-key-here

🔑 Direct API Key Format

Authorization: your-api-key-here

💻 Client Implementation

When authentication is enabled, clients must include the API key in their requests:

// Example client code with authentication
const headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer your-api-key-here'  // or just 'your-api-key-here'
};

const response = await fetch('http://localhost:8123/mcp', {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(mcpRequest)
});

📋 Authentication Responses

• ✅ 200 OK: Request successful (valid API key or authentication disabled)
• ❌ 401 Unauthorized: Invalid or missing API key when authentication is required

Example error response:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Unauthorized: Invalid or missing API key"
  },
  "id": null
}

🔒 Security Best Practices

1. 🔐 Keep API keys secure: Never commit API keys to version control
2. 🌍 Use environment variables: Store API keys in .env files that are gitignored
3. 🔒 Use HTTPS in production: Always use HTTPS when deploying to production
4. 🔄 Rotate keys regularly: Change API keys periodically for better security
5. 🏷️ Use Bearer format: The Bearer <token> format is the recommended standard

❌ Disabling Authentication

To disable authentication (default behavior):

# In .env or .dev.vars
MCP_AUTH_REQUIRED=false
# or simply omit the MCP_AUTH_REQUIRED variable

When authentication is disabled, the server will accept all requests without checking for API keys.

---

📄 License

ISC

---

🎯 Next Steps

1. 🔧 Customize Tools: Replace the example tools with your specific functionality
2. ☁️ Configure Deployment: Update wrangler.toml with your project details
3. 🧪 Test Locally: Use the example client to verify your implementation
4. 🚀 Deploy: Push to Cloudflare Workers free tier
5. 🔌 Connect: Integrate with MCP-compatible clients

🎉 This template provides everything you need to build, test, and deploy production-ready MCP servers with minimal setup time! ✨

---