mcp-gateway-worker

MCP Gateway Worker

Cloudflare Worker gateway that exposes MCP-compatible JSON-RPC (/mcp) and REST test endpoints (/tools, /tools/:name/call) over a single unified tool registry.

Live deployment

• Worker URL: https://mcp-gateway-worker.to-jamz.workers.dev
• MCP endpoint: https://mcp-gateway-worker.to-jamz.workers.dev/mcp

Setup

pnpm install
pnpm wrangler secret put DOMAIN_SHARED_SECRET
pnpm dev

Build and verify

pnpm install
pnpm build
pnpm test

Targeted suites:

pnpm test:contract
pnpm test:validation
pnpm test:e2e

Deploy to Cloudflare

pnpm wrangler login
pnpm wrangler secret put DOMAIN_SHARED_SECRET
pnpm wrangler deploy

Production checklist before deploy:

• Replace local values in wrangler.toml (DOMAIN_A_URL, DOMAIN_B_URL, ALLOWED_ORIGINS).
• Replace CLIENT_AUTH_TOKEN and set least-privilege CLIENT_ALLOWED_SCOPES.
• Confirm upstream domain workers are reachable from Cloudflare.

Environment and secrets

wrangler.toml local vars:

• ENVIRONMENT
• DOMAIN_A_URL
• DOMAIN_B_URL
• ALLOWED_ORIGINS
• AUTH_MODE
• CLIENT_AUTH_TOKEN
• CLIENT_ALLOWED_SCOPES
• UPSTREAM_TIMEOUT_MS
• REQUEST_BODY_MAX_BYTES
• TOOL_ARGUMENT_MAX_BYTES

Required secret:

• DOMAIN_SHARED_SECRET

Authentication model

• Client -> Gateway: Authorization: Bearer <CLIENT_AUTH_TOKEN> (static-token mode).
• Gateway -> Domain workers: Authorization: Bearer <DOMAIN_SHARED_SECRET>.
• Trusted scopes source: CLIENT_ALLOWED_SCOPES (gateway does not trust raw scope headers directly for authorization).

Trust boundary

• Gateway is the policy enforcement boundary for auth, scope checks, origin checks, and canonical error mapping.
• Domain workers are upstream execution targets and are treated as untrusted for response shape (gateway validates upstream payloads).

Guardrails

• Origin checks apply only when an Origin header is present.
• Request and argument size limits are centralized via env-backed limits.
• Upstream calls use timeout/retry handling and normalize exceptions to canonical UPSTREAM_ERROR.

Endpoints

• GET /health -> { "status": "ok", "environment": "..." }
• GET /tools -> unified tool catalog
• POST /tools/:name/call -> REST tool invocation
• POST /mcp -> MCP JSON-RPC (tools/list, tools/call)

Use this MCP from any IDE

Any IDE/editor MCP client that supports HTTP/JSON-RPC can connect to this endpoint:

• URL: https://mcp-gateway-worker.to-jamz.workers.dev/mcp
• Method: POST
• Header: Authorization: Bearer <CLIENT_AUTH_TOKEN>
• Header: Content-Type: application/json

Generic MCP client config shape:

{
	"mcpServers": {
		"mcp-gateway-worker": {
			"transport": "http",
			"url": "https://mcp-gateway-worker.to-jamz.workers.dev/mcp",
			"headers": {
				"Authorization": "Bearer <CLIENT_AUTH_TOKEN>"
			}
		}
	}
}

Quick connectivity test:

curl -s -X POST https://mcp-gateway-worker.to-jamz.workers.dev/mcp \
	-H "Authorization: Bearer <CLIENT_AUTH_TOKEN>" \
	-H "content-type: application/json" \
	-d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

If your IDE uses a different MCP schema (for example command-based wrappers), map it to the same HTTP endpoint and headers above.

IDE-specific examples

The exact file path/key name can vary by IDE version, but these templates are the common setup patterns.

VS Code (MCP extension/client)

settings.json example:

{
	"mcp.servers": {
		"mcp-gateway-worker": {
			"transport": "http",
			"url": "https://mcp-gateway-worker.to-jamz.workers.dev/mcp",
			"headers": {
				"Authorization": "Bearer <CLIENT_AUTH_TOKEN>"
			}
		}
	}
}

Cursor

.cursor/mcp.json example:

{
	"mcpServers": {
		"mcp-gateway-worker": {
			"transport": "http",
			"url": "https://mcp-gateway-worker.to-jamz.workers.dev/mcp",
			"headers": {
				"Authorization": "Bearer <CLIENT_AUTH_TOKEN>"
			}
		}
	}
}

Windsurf

MCP config example:

{
	"mcpServers": {
		"mcp-gateway-worker": {
			"transport": "http",
			"url": "https://mcp-gateway-worker.to-jamz.workers.dev/mcp",
			"headers": {
				"Authorization": "Bearer <CLIENT_AUTH_TOKEN>"
			}
		}
	}
}

JetBrains AI Assistant / IDE MCP client

MCP server entry example:

{
	"name": "mcp-gateway-worker",
	"transport": "http",
	"url": "https://mcp-gateway-worker.to-jamz.workers.dev/mcp",
	"headers": {
		"Authorization": "Bearer <CLIENT_AUTH_TOKEN>"
	}
}

If your IDE only supports command-based MCP launchers, create a tiny local proxy/wrapper that forwards to this HTTP endpoint with the same Authorization header.

Examples

curl -s http://127.0.0.1:8787/health

curl -s http://127.0.0.1:8787/tools \
	-H "Authorization: Bearer replace-me"

curl -s -X POST http://127.0.0.1:8787/tools/sum/call \
	-H "Authorization: Bearer replace-me" \
	-H "content-type: application/json" \
	-d '{"arguments":{"a":5,"b":7}}'

curl -s -X POST http://127.0.0.1:8787/mcp \
	-H "Authorization: Bearer replace-me" \
	-H "content-type: application/json" \
	-d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

Compatibility guard policy

• Canonical MCP error payloads are treated as compatibility contracts.
• tests/contract/mcp-errors.snapshot.test.ts enforces stable error.code, error.data.error_code, and snapshot shape.
• Breaking payload changes require explicit contract/versioning updates and corresponding test updates.

Scripts

• pnpm dev
• pnpm build
• pnpm test
• pnpm test:contract
• pnpm test:validation
• pnpm test:e2e
• pnpm test:snapshots