MCP Nexus - Cloudflare Workers

One-click deployment of MCP Nexus to Cloudflare's free tier. This provides a unified MCP server for Tavily and Brave Search APIs with automatic API key rotation.

Features

• Zero-cost hosting on Cloudflare Workers free tier
• D1 Database for persistent storage (automatic provisioning)
• Encrypted API keys with Web Crypto API
• Admin UI included - Full web interface for managing keys and tokens
• 7 MCP tools: tavily_search, tavily_extract, tavily_crawl, tavily_map, tavily_research, brave_web_search, brave_local_search

Deploy

Option 1: One-Click Deploy

Click the button above and follow the prompts. You'll be asked to:

1. Authorize Cloudflare to access your GitHub (fork will be created)
2. Configure secrets:
   • ADMIN_API_TOKEN: Token for admin API access (generate with openssl rand -hex 32)
   • KEY_ENCRYPTION_SECRET: Key for encrypting API keys (generate with openssl rand -base64 32)

Option 2: Manual Deploy

# Clone the repo
git clone https://github.com/ykq007/mcp-nexus.git
cd mcp-nexus/packages/worker

# Install dependencies
npm install

# Create D1 database
npx wrangler d1 create mcp-nexus-db
# Copy the database_id from output to wrangler.jsonc

# Set secrets
npx wrangler secret put ADMIN_API_TOKEN
npx wrangler secret put KEY_ENCRYPTION_SECRET

# Run migrations and deploy
npm run deploy

Post-Deployment Setup

After deployment, you need to add API keys and create client tokens.

1. Add Tavily API Keys

curl -X POST https://your-worker.workers.dev/admin/api/tavily-keys \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "Primary Key", "key": "tvly-xxxxx"}'

2. Add Brave API Keys (Optional)

curl -X POST https://your-worker.workers.dev/admin/api/brave-keys \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "Primary Key", "key": "BSAxxxxx"}'

3. Create Client Token

curl -X POST https://your-worker.workers.dev/admin/api/tokens \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Claude Desktop"}'

Save the returned token - it's only shown once.

MCP Client Configuration

Claude Desktop / Cline

{
  "mcpServers": {
    "mcp-nexus": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-proxy", "https://your-worker.workers.dev/mcp"],
      "env": {
        "MCP_HEADERS": "Authorization: Bearer YOUR_CLIENT_TOKEN"
      }
    }
  }
}

Direct HTTP

curl -X POST https://your-worker.workers.dev/mcp \
  -H "Authorization: Bearer YOUR_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

API Endpoints

Endpoint	Auth	Description
POST /mcp	Client Token	MCP JSON-RPC endpoint
GET /health	None	Health check
GET /admin/api/tavily-keys	Admin Token	List Tavily keys
POST /admin/api/tavily-keys	Admin Token	Add Tavily key
DELETE /admin/api/tavily-keys/:id	Admin Token	Delete Tavily key
GET /admin/api/brave-keys	Admin Token	List Brave keys
POST /admin/api/brave-keys	Admin Token	Add Brave key
DELETE /admin/api/brave-keys/:id	Admin Token	Delete Brave key
GET /admin/api/tokens	Admin Token	List client tokens
POST /admin/api/tokens	Admin Token	Create client token
DELETE /admin/api/tokens/:id	Admin Token	Revoke client token
GET /admin/api/settings	Admin Token	Get settings
PUT /admin/api/settings	Admin Token	Update settings
GET /admin/api/usage	Admin Token	View usage logs

Local Development

# Install dependencies
npm install

# Create local D1 database
npm run db:migrate:local

# Start dev server
npm run dev

Architecture

┌─────────────────────────────────────────────────────────┐
│                  Cloudflare Workers                      │
├─────────────────────────────────────────────────────────┤
│  Hono Router                                            │
│  ├── /mcp (MCP JSON-RPC)                               │
│  ├── /admin/api/* (Admin API)                          │
│  └── /health                                           │
├─────────────────────────────────────────────────────────┤
│  Services                                               │
│  ├── Key Pool (rotation, cooldown)                     │
│  ├── Tavily Client                                     │
│  └── Brave Client                                      │
├─────────────────────────────────────────────────────────┤
│  D1 Database                                           │
│  ├── tavily_keys (encrypted)                           │
│  ├── brave_keys (encrypted)                            │
│  ├── client_tokens (hashed)                            │
│  ├── server_settings                                   │
│  └── usage_logs                                        │
└─────────────────────────────────────────────────────────┘

License

MIT