robertefreeman/Streamflare
If you are the rightful owner of Streamflare and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
This template provides a comprehensive foundation for building streamable HTTP transport MCP servers, optimized for deployment on Cloudflare Workers.
๐ 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 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 :
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 :
{
"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:
- ๐ MCP connection initialization
- ๐ Tool discovery and listing
- โ๏ธ Tool execution with parameters
- ๐จ Error handling
- ๐ Authentication examples (configure
USE_AUTH
andAPI_KEY
in the client)
๐ก Note: If you enable authentication on your server (MCP_AUTH_REQUIRED=true
), make sure to update the authentication configuration in 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 keyOPENAI_API_KEY
: OpenAI API keyGOOGLE_API_KEY
: Google services API keyANTHROPIC_API_KEY
: Anthropic API key
๐ External Services
DATABASE_URL
: Database connection stringREDIS_URL
: Redis connection stringEXTERNAL_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:
- 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
- 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
- ๐ Keep API keys secure: Never commit API keys to version control
- ๐ Use environment variables: Store API keys in
.env
files that are gitignored - ๐ Use HTTPS in production: Always use HTTPS when deploying to production
- ๐ Rotate keys regularly: Change API keys periodically for better security
- ๐ท๏ธ 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
- ๐ง Customize Tools: Replace the example tools with your specific functionality
- โ๏ธ Configure Deployment: Update
wrangler.toml
with your project details - ๐งช Test Locally: Use the example client to verify your implementation
- ๐ Deploy: Push to Cloudflare Workers free tier
- ๐ 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! โจ
Built with โค๏ธ for the MCP community
๐ Get Started โข ๐ Documentation โข ๐ ๏ธ Features โข ๐ง Customization