MCP Gateway

One local MCP endpoint for all your MCP servers.

MCP Gateway sits between your MCP clients and your MCP servers. Configure it once, point every client at it, and manage everything in one place: namespaced tools, profiles, policy, context budgets, audit logs, and a local dashboard — over stdio or Streamable HTTP.

Claude / Cursor / opencode / any MCP client
                  │ stdio or HTTP
                  ▼
          ┌───────────────────────────┐
          │        MCP Gateway        │  namespacing · profiles · policy
          │                           │  budget · audit · dashboard
          └─────────────┬─────────────┘
      ┌───────────┬─────┴─────┬───────────┐
      ▼           ▼           ▼           ▼
 filesystem    github     tokensaver   … more servers

Why

Every MCP client keeps its own copy of every server configuration. Five clients times eight servers is forty places to update a token, a path, or a flag. And as servers accumulate, so do questions: which server exposes which tool, which ones are down, which tools may run, and what is eating the context window. The gateway answers all of it once.

Related MCP server: mcp-gw

Features

• Aggregation — any number of stdio MCP servers behind one endpoint.

• Namespacing — stable server__tool names; no collisions, clear origin.

• Profiles — different server sets for different contexts (work, docs, personal).

• Policy — allow/deny rules with glob patterns, plus a read-only mode that blocks mutating tools.

• Budgets — token cost of aggregated tool schemas, ranked per server and per tool.

• Audit — JSONL log of every tool call with duration and outcome; stats summaries.

• Health — per-server timeouts; broken servers never block startup; gateway_status and gateway_policy tools.

• Transports — MCP over stdio, or Streamable HTTP with a local dashboard.

Quick start

npx -y mcp-gateway init
npx -y mcp-gateway add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
npx -y mcp-gateway add tokensaver -- npx -y tokensaver-mcp
npx -y mcp-gateway list

Point clients at the gateway:

{
  "mcpServers": {
    "gateway": {
      "command": "npx",
      "args": ["-y", "mcp-gateway", "serve"]
    }
  }
}

HTTP mode with the dashboard:

npx -y mcp-gateway serve --http --port 8787
# MCP endpoint: http://127.0.0.1:8787/mcp
# Dashboard:    http://127.0.0.1:8787/

Configuration

mcp-gateway.json:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "..." }
    }
  },
  "profiles": {
    "default": { "servers": ["filesystem", "github"] },
    "docs": {
      "servers": ["filesystem"],
      "policy": { "readOnly": true }
    }
  },
  "activeProfile": "default",
  "policy": {
    "defaultAction": "allow",
    "readOnly": false,
    "rules": [
      { "server": "github", "tool": "delete_*", "action": "deny" },
      { "server": "github", "tool": "get_*", "action": "allow" }
    ]
  },
  "audit": { "enabled": true, "path": "mcp-gateway.audit.jsonl" }
}

Policy rules use glob patterns (*, ?), first match wins, and read-only mode blocks tools whose names look mutating (write_*, create_*, delete_*, run_*, …). Profiles can override the global policy.

CLI reference

Global options: --config <path>, --profile <name>, --audit, --audit-path <p>, --json, --force.

Exit codes: 0 success, 1 config or runtime failure, 2 usage error.

MCP tools exposed by the gateway

Design principles

• Local-first: no network service, no telemetry; everything runs on your machine.

• Transparent: tool names show origin; blocked calls explain which rule denied them.

• Bounded: per-server timeouts, bounded startup, token estimates instead of tokenizers.

• Safe by default: audit disabled unless enabled; read-only mode available per profile.

• Composable: works with any stdio MCP server, including the TokenSaver family.

Development

npm install
npm run typecheck
npm run build
npm test

The suite covers config parsing, upstream lifecycle, policy decisions, namespacing, budgets, audit logs, CLI flows, end-to-end stdio routing, and MCP over Streamable HTTP with a live dashboard API.

License

MIT — see LICENSE.