MCP Gateway

A TypeScript gateway that aggregates multiple MCP (Model Context Protocol) servers into a single endpoint, enabling AI agents to access tools from many backends through one connection.

AI Agent
   │
   ▼
MCP Gateway  ←─── servers.json (config)
   │
   ├── Ceph Storage Assistant  (fastmcp)
   ├── Other MCP Server        (sse / streamable-http)
   └── Local Tool              (stdio)

⚠️ Agent Support

Currently, MCP Gateway officially supports Hermes Agent only.

Hermes connects using the MCP Streamable HTTP protocol (2025-11-25) via mcp.client.streamable_http. Support for other agents (LangChain, AutoGen, OpenAI Agents SDK, etc.) is planned for future development.

Features

• Multi-server aggregation — connect as many MCP servers as needed, tools are merged into one list
• Namespace isolation — tools are prefixed with server ID (ceph_alpha__get_health_summary) so agents know exactly which backend to target, even when multiple servers expose the same tool names
• 4 transport types — supports all current MCP transport protocols plus a custom Ceph-compatible transport
• Persistent config — servers.json is the single source of truth; adding/removing servers via the dashboard persists across restarts
• Web dashboard — visual overview of connected servers and aggregated tools
• Docker-ready — runs in a container with host networking for internal backend access

Transport Types

| Value | Protocol | Use when | |---|---|---| | streamable-http | MCP 2025-11-25 | Server uses modern Streamable HTTP | | sse | MCP 2024-11-05 | Server uses legacy SSE protocol | | fastmcp | Custom (Ceph) | Ceph Storage Assistant — persistent POST stream | | stdio | stdio | Local process (npx, python, etc.) |

Quick Start

1. Start the gateway

docker compose up -d --build

Dashboard: http://localhost:3010

2. Add MCP servers

Open the dashboard and click "Add New MCP-Client". Select the transport type, enter the URL and an ID — the server connects immediately and is saved automatically.

servers.json is automatically updated by the gateway whenever you add or remove a server via the dashboard or API. There is no need to edit this file manually.

Only edit it directly if you want to pre-configure servers before the very first docker compose up.

3. Connect Hermes

In your Hermes config.yaml:

mcp_servers:
  Ceph-Alpha:
    url: http://localhost:3010/sse?apiKey=mcp_gateway_secret_123

Hermes will discover all aggregated tools automatically. Tools are namespaced by server ID:

• ceph_alpha__get_health_summary
• ceph_alpha__get_cluster_capacity
• my_other_mcp__some_tool

Configuration

Environment variables (docker-compose.yaml)

| Variable | Default | Description | |---|---|---| | PORT | 3010 | Gateway listen port | | API_KEY | mcp_gateway_secret_123 | Auth key required in ?apiKey= | | SERVERS_CONFIG | /app/servers.json | Path to servers config file |

servers.json schema

[
  { "id": "string", "transport": "streamable-http", "url": "http://..." },
  { "id": "string", "transport": "sse",             "url": "http://..." },
  { "id": "string", "transport": "fastmcp",         "url": "http://..." },
  { "id": "string", "transport": "stdio", "command": "npx", "args": ["pkg"] }
]

servers.json is automatically updated whenever you add or remove a server via the dashboard or API. Only edit it manually to pre-configure servers before the first docker compose up — after that, use the dashboard.

Management API

# List connected servers + status
curl http://localhost:3010/api/status

# List all aggregated tools
curl http://localhost:3010/api/tools

# Add a server at runtime (persisted to servers.json)
curl -X POST http://localhost:3010/api/servers \
  -H "Content-Type: application/json" \
  -d '{"id":"new-server","transport":"streamable-http","url":"http://..."}'

# Remove a server at runtime (removed from servers.json)
curl -X DELETE http://localhost:3010/api/servers/new-server

# Test tools/list as an agent would
curl -X POST "http://localhost:3010/sse?apiKey=mcp_gateway_secret_123" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{}}'

Development

# Install dependencies
npm install

# Run in dev mode (hot reload)
npm run dev

# Build
npm run build

# Start production
npm start

# Docker
docker compose up -d --build   # build & start
docker compose restart          # restart (picks up servers.json changes)
docker compose logs -f          # stream logs

Project Structure

mcp-gateway/
├── src/
│   ├── index.ts        # Express app, /sse endpoint, management API
│   ├── aggregator.ts   # Tool/resource/prompt fan-out + namespace prefixing
│   ├── upstream.ts     # Transport classes, UpstreamManager
│   └── config.ts       # Zod schema for servers.json
├── public/             # Web dashboard (HTML/CSS/JS)
├── docs/
│   └── plan.md         # Architecture & issue history
├── servers.json        # Upstream server registry (persistent)
└── docker-compose.yaml

Roadmap

• [ ] Support for additional AI agents (LangChain, AutoGen, OpenAI Agents SDK, ...)
• [ ] Auto-reconnect on upstream stream drop
• [ ] Health check endpoint per upstream server
• [ ] Authentication per upstream (API key injection)