# 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

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

Connect an MCP client to:

```text
http://127.0.0.1:8000/mcp
```

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

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

## Configuration

```toml
[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

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

The admin API is loopback-only by default:

```text
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

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

See [SPEC.md](SPEC.md) and [tasks/plan.md](tasks/plan.md) for the current contract and deferred work.