mcp-gw

An aggregating MCP (Model Context Protocol) gateway that runs as a Docker container. Claude Code connects to one endpoint and gets tools from all registered backend MCP servers combined.

Architecture

Claude Code
    │  HTTP MCP (localhost:3000/mcp)
    ▼
┌─────────────────────────────┐
│       mcp-gateway           │  ← Alpine Docker container
│  ┌─────────┐ ┌──────────┐  │
│  │ MCP srv │ │Dashboard │  │
│  └────┬────┘ └──────────┘  │
│       │  mcp-gw-net         │
└───────┼─────────────────────┘
        │
        ├── backend-a:8080
        ├── backend-b:8080
        └── ...

Tools from all backends are aggregated and namespaced as backend__tool_name so Claude Code sees them in a single tool list.

Related MCP server: Multi MCP

Quick Start

git clone https://github.com/gpimthong/mcp-gw
cd mcp-gw
docker compose up -d

The gateway starts on port 3000.

• Dashboard: http://localhost:3000

• MCP endpoint: http://localhost:3000/mcp

• Health: http://localhost:3000/api/health

Connect Claude Code

Add to ~/.mcp.json:

{
  "mcpServers": {
    "gateway": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Restart Claude Code to pick up the change.

Adding Backend MCP Servers

Backend servers must be containers on the mcp-gw-net Docker network.

# Attach an existing container to the network
docker network connect mcp-gw-net <container-name>

# Or start a new backend directly on the network
docker run -d --name my-mcp --network mcp-gw-net my-mcp-image

Then register the backend via the dashboard form or the REST API:

curl -X POST http://localhost:3000/api/backends \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-mcp","url":"http://my-mcp:8080/mcp","transport":"http","enabled":true}'

The registration is saved to config/backends.json and reconnects automatically on gateway restart.

Dashboard

The dashboard at http://localhost:3000 shows:

• Backend cards — connection status, tool count, latency, last ping

• Live request log — real-time stream of every tool call with duration and status

• Tool catalog — all tools from all backends, expandable by backend

Use the + Add Backend button to register new backends, or click Remove / Reconnect on each card.

REST API

Tool Namespacing

Backend memory with tool search_notes → exposed to Claude Code as memory__search_notes.

The double-underscore separator avoids collisions between backends. The gateway parses the prefix at call time to route to the right backend client.

Transport Support

Development

Requires Node.js 22+.

npm install
npm run dev        # tsx hot-reload
npm run build      # compile TypeScript → dist/

Config is read from ./config/backends.json in dev mode (set CONFIG_PATH env var to override).

Versioning

Version is set in package.json. The gateway advertises it in the MCP initialize handshake and at /api/health. Git tags follow v<semver> (e.g. v0.1.0).

Project Structure

src/
  index.ts            — entry point
  version.ts          — reads version from package.json
  types.ts            — shared interfaces
  logger.ts           — circular log buffer + SSE emitter
  config.ts           — load/save backends.json
  backend-registry.ts — MCP client connections + heartbeat
  tool-aggregator.ts  — namespace + route tool calls
  mcp-server.ts       — MCP HTTP server (session management)
  dashboard.ts        — Express app (REST API + SSE)
public/
  index.html          — dashboard SPA (no build step)
config/
  backends.json       — persisted backend definitions