MCP Router

Extensible MCP server that aggregates multiple backends behind a single endpoint.

Architecture

Remote MCP client → CF Worker (OAuth) → Workers VPC → CF Tunnel → MCP Router → [Backends]
                                   │                        ↓
                            (private backbone)         email backend → ProtonMail Bridge
                                                       (add more backends here)

Security: No public DNS exposure. Traffic flows through Cloudflare's private network via Workers VPC binding to a Cloudflare Tunnel with no public hostname.

Related MCP server: Todoist MCP Server

Quick Start

1. Clone and install

curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/marklubin/mcp-email-server.git mcp-infrastructure
cd mcp-infrastructure

2. Configure

cp .env.example .env
# Edit .env with your credentials

3. ProtonMail Bridge (one-time)

protonmail-bridge --cli
# > login
# > info  (note the bridge password)

4. Run

uv run python router/server.py

Or with systemd:

./setup.sh
sudo systemctl enable --now mcp-router@$USER

5. Set up Cloudflare Tunnel (for private backend)

cloudflared tunnel login
cloudflared tunnel create mcp-router
# Configure ~/.cloudflared/config.yml (see cloudflare/tunnel-config.yml.example)
sudo systemctl enable --now cloudflared

6. Create Workers VPC Service

In Cloudflare Dashboard → Workers & Pages → Workers VPC:

• Create service: mcp-router-vpc

• Select tunnel: mcp-router

• Target: http://127.0.0.1:8080

7. Deploy Worker

cd cloudflare/worker && npx wrangler deploy

Google Tasks backend (gtasks_*)

Mark's interview-preparation board lives in Google Tasks: one list per lane (Coding, System design, AI systems, Behavioral and projects), one task per curriculum unit titled <ID> - <title>, one subtask per depth. The backend derives the board and applies bounded changes; it never creates or deletes lists and never deletes tasks.

Tools: gtasks_lists, gtasks_board, gtasks_tasks (list, get, add, complete, reopen, note, move, update), gtasks_seed (idempotent curriculum load, dry run by default).

Credentials: a long-lived OAuth refresh token for Mark's Google account. Produce it once with python3 scripts/gtasks_auth.py <client_secret.json> (Desktop-app OAuth client from a Google Cloud project with the Tasks API enabled and the app published, not in Testing mode, or the token expires weekly). Append the three lines it writes to .env and restart the router. Optional GOOGLE_TASKS_LANES overrides list titles.

Deployment

The canonical deployed instance runs on oxnard as the systemd unit mcp-router@mark.service.

Steady-state flow:

1. Edit code locally on a dev machine (clone of this repo).

2. Commit and push to origin/master.

3. From the local clone, run ./scripts/deploy.sh — pushes (if needed), SSHes to the remote, runs git pull, and restarts the service.

4. If dependencies changed (pyproject.toml / uv.lock), deploy.sh's uv sync keeps the venv in sync. If it doesn't, restart will still pick up the new deps on next uv run.

Do not edit code directly on oxnard. The repo is the source of truth — changes made only on the box will drift and get lost. If you must hotpatch in an emergency, copy the fix back into the repo and commit it before doing anything else.

Override the deploy target with MCP_REMOTE=hostname ./scripts/deploy.sh.

Backends

Each backend lives in router/backends/ and exposes tools under its mount prefix.

Also available but not currently mounted in server.py:

• browser.py — Playwright-over-CDP MCP tools; its internal HTTP route remains enabled.

• memory.py — agent memory tools.

• todoist.py — Todoist tasks/projects.

• notifications.py — notification MCP tools; its internal HTTP routes remain enabled.

• discord.py — Discord MCP tools; its internal HTTP routes remain enabled.

• twitter.py — Twitter read tools via twitterapi.io.

• unified_memory.py — proxies all synix MCP tools from the agent-mesh server on salinas. Wire it up by importing + mounting if you want to replace or augment memory.

Email Backend (prefix: email_)

Web Backend (prefix: web_)

Uses Exa under the hood. Free tier: 1,000 searches/month.

Finance Backend (prefix: finance_)

This is a read-only gateway to a separate finance data service on the same host. Plaid credentials, sync operations, and account administration stay inside that service and are never exposed through MCP.

For detailed signatures of other backends, read the source — each tool's docstring is its contract.

Router

Adding New Backends

1. Create router/backends/yourbackend.py:

from fastmcp import FastMCP

mcp = FastMCP('yourbackend')

@mcp.tool()
async def your_tool(arg: str) -> dict:
    """Your tool description."""
    return {'result': 'value'}

2. Mount in router/server.py:

from backends import yourbackend
router.mount(yourbackend.mcp, prefix='yourbackend')

Also append the prefix to the health() backend list.

3. If the backend needs secrets, add them to .env.example and .env.

4. Commit and run ./scripts/deploy.sh. Tools appear as yourbackend_your_tool.

Remote MCP endpoint

Use https://mcp-router-proxy.melubin.workers.dev/mcp as a Streamable HTTP MCP endpoint. The Cloudflare Worker handles OAuth, then streams MCP traffic to the private router through Workers VPC.

In ChatGPT developer mode, add the URL as a custom connector and complete the GitHub OAuth flow. Only the GitHub users listed in cloudflare/worker/src/github-handler.ts can connect. Refresh the connector after deploying router tool changes or Worker OAuth changes.

Environment Variables

See .env.example for the full list. Required for core operation:

MCP_SECRET=              # API key for auth from CF Worker
ROUTER_HOST=127.0.0.1
ROUTER_PORT=8080
PROTON_BRIDGE_HOST=127.0.0.1
PROTON_BRIDGE_IMAP_PORT=1143
PROTON_BRIDGE_SMTP_PORT=1025
PROTON_BRIDGE_USER=you@proton.me
PROTON_BRIDGE_PASSWORD=bridge-password

Integration-specific keys (only required when the corresponding MCP or HTTP integration is enabled):

EXA_API_KEY=             # web search
TODOIST_API_TOKEN=       # todoist
TWITTERAPI_IO_KEY=       # twitter
DISCORD_TOKEN=           # discord
FINANCE_SERVICE_URL=     # finance service loopback URL (default http://127.0.0.1:8090)
FINANCE_SERVICE_TOKEN=   # bearer token shared with finance-data-service
MESH_SERVER_URL=         # memory
MESH_TOKEN=              # memory
AGENT_MESH_MCP_URL=      # unified_memory (if mounted)

Project Structure

mcp-infrastructure/
├── router/
│   ├── server.py                   # Main router, mounts backends
│   └── backends/
│       ├── __init__.py
│       ├── email.py                # ProtonMail
│       ├── browser.py              # Playwright over CDP
│       ├── todoist.py              # Todoist
│       ├── notifications.py        # Push/inbox
│       ├── discord.py              # Discord user-token
│       ├── memory.py               # Agent memory
│       ├── twitter.py              # Twitter (twitterapi.io)
│       ├── web.py                  # Web search (Exa)
│       └── unified_memory.py       # Synix proxy (not mounted by default)
├── services/
│   ├── mcp-router.service          # systemd template for router
│   ├── cloudflared.service         # systemd service for tunnel
│   ├── headless-brave.service      # headless browser
│   └── protonmail-bridge.service   # ProtonMail Bridge
├── cloudflare/
│   ├── tunnel-config.yml.example   # Tunnel config template
│   └── worker/                     # CF Worker for OAuth + VPC proxy
├── scripts/
│   ├── deploy.sh                   # Push and deploy to remote
│   ├── logs.sh                     # View service logs
│   ├── status.sh                   # Check service status
│   ├── tunnel.sh                   # Manage Cloudflare Tunnel
│   ├── test-email.sh               # Test email tools
│   ├── test.sh                     # Run tests
│   ├── browser-connect.sh          # Connect to CDP browser
│   ├── run-headless-brave.sh       # Launch headless Brave
│   ├── run-headless-firefox.sh     # Launch headless Firefox + VNC
│   └── notify-check.sh             # Notification health check
├── setup.sh                        # One-shot setup script
├── pyproject.toml                  # Python dependencies
└── .env.example                    # Config template

Management Scripts