Universal MCP Gateway

One local MCP entry point for multiple coding agents. It proxies configured upstream MCP tools, keeps upstream sessions warm, serializes calls for exclusive services, reports process resources, and exposes small SQLite-backed task, lock, and memory tools.

Quick start

python -m pip install -e '.[dev]'
cp config.example.toml config.toml
mcp-gateway serve --config config.toml

Connect an MCP client to:

http://127.0.0.1:8000/mcp

Clients that only support stdio can run one gateway bridge process:

{
  "command": "mcp-gateway",
  "args": ["serve", "--config", "/absolute/path/config.toml", "--transport", "stdio"]
}

Configuration

[gateway]
host = "127.0.0.1"
port = 8000
database = "gateway.db"
auth_token_env = "MCP_GATEWAY_TOKEN"

[servers.example]
transport = "stdio"
command = "npx"
args = ["-y", "some-mcp-server"]
mode = "exclusive"
max_in_flight = 1
queue_limit = 32

[servers.remote]
transport = "streamable_http"
url = "http://127.0.0.1:9000/mcp"
mode = "pool"
max_connections = 2
queue_limit = 64

Upstream tools are exposed as <server_id>__<tool_name>. Gateway coordination tools use the gateway__ prefix. per_agent is process-scoped in v0.1; run one stdio gateway bridge per agent when separate upstream sessions are required. The first release proxies tools only; resources, prompts, sampling, and distributed scheduling are deliberately deferred.

Operations

mcp-gateway status
mcp-gateway start example
mcp-gateway stop example
mcp-gateway restart example

The admin API is loopback-only by default:

GET  /health
GET  /v1/status
POST /v1/servers/{id}/start
POST /v1/servers/{id}/stop
POST /v1/servers/{id}/restart

Set the configured token environment variable to require Authorization: Bearer ... for MCP and admin HTTP requests. Commands and arguments are read from TOML only; the gateway never executes a shell string received from an agent.

Shared work tools

The gateway provides task leases, optimistic task updates, resource locks, and project-scoped text memory through gateway__* tools. SQLite uses WAL mode and short transactions. Locks and task leases expire, so a disconnected agent does not hold work forever.

Do not store credentials, raw transcripts, or production data in the local memory store.

Development

python -m pytest -q
python -m compileall -q universal_mcp_gateway
git diff --check

See SPEC.md and tasks/plan.md for the current contract and deferred work.