mcp-gateway

A lightweight, open-source gateway for your MCP servers.

Route · Authenticate · Rate-limit · Monitor — all your Model Context Protocol servers from a single endpoint.

English · 中文 · Docs · Examples

The Problem

As MCP becomes the standard protocol for AI agents to interact with tools, teams are running dozens of MCP servers — filesystem, GitHub, databases, Slack, search, and more. Managing them is chaos:

• Every AI client connects to every server independently
• No central authentication or access control
• No visibility into which tools are being called, by whom, and how often
• No rate limiting to prevent runaway agents from hammering your APIs

mcp-gateway solves this. It sits between your AI clients and your MCP servers, acting as a single, observable, secure entry point.

┌─────────────────────────────────────────────────────────┐
│                      AI Clients                         │
│   Claude Code · Cursor · Copilot · Your App · Scripts   │
└─────────────────────┬───────────────────────────────────┘
                      │  HTTP / REST
                      ▼
┌─────────────────────────────────────────────────────────┐
│                   mcp-gateway                           │
│                                                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────────┐  │
│  │   Auth   │  │  Router  │  │  Metrics / Monitor   │  │
│  │ API Key  │  │ Tool →   │  │  Prometheus · Logs   │  │
│  │   JWT    │  │ Server   │  │  Dashboard           │  │
│  └──────────┘  └──────────┘  └──────────────────────┘  │
│                                                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │Rate Limit│  │ Registry │  │  Health  │              │
│  └──────────┘  └──────────┘  └──────────┘              │
└──────┬──────────────┬──────────────┬────────────────────┘
       │              │              │  stdio / SSE / WS
       ▼              ▼              ▼
┌──────────┐  ┌──────────┐  ┌──────────┐
│Filesystem│  │  GitHub  │  │PostgreSQL│  ... more
│  Server  │  │  Server  │  │  Server  │
└──────────┘  └──────────┘  └──────────┘

Features

• Unified API endpoint — one URL for all your MCP tools, auto-routed by tool name
• Authentication — API key, JWT, or no-auth modes
• Rate limiting — per-key sliding window, with standard X-RateLimit-* headers
• Health monitoring — automatic health checks with configurable intervals
• Metrics — Prometheus-compatible /metrics endpoint + JSON aggregation
• Tool discovery — GET /api/v1/tools lists all tools across all servers
• YAML/JSON config — simple, declarative configuration with env var overrides
• Docker-ready — official Docker image, Compose examples included
• TypeScript SDK — embed the gateway as a library in your own project

Quick Start

Install

npm install -g mcp-gateway
# or
npx mcp-gateway init

Configure

# Generate a default config file
mcp-gateway init

# Edit mcp-gateway.yml to add your servers

# mcp-gateway.yml
port: 4000

servers:
  - id: filesystem
    name: Filesystem
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

  - id: github
    name: GitHub
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

Run

mcp-gateway start
# → mcp-gateway listening on http://0.0.0.0:4000
# → ✓ Filesystem — 8 tools available
# → ✓ GitHub — 26 tools available

Call a Tool

# List all available tools
curl http://localhost:4000/api/v1/tools

# Call a tool (auto-routes to the right server)
curl -X POST http://localhost:4000/api/v1/tools/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "read_file", "arguments": {"path": "/tmp/hello.txt"}}'

# With authentication
curl -X POST http://localhost:4000/api/v1/tools/call \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"tool": "create_issue", "server": "github", "arguments": {"title": "Bug report", "body": "..."}}'

API Reference

| Method | Path | Description | |--------|------|-------------| | GET | /api/v1/health | Gateway health and server summary | | GET | /api/v1/servers | List all registered servers | | GET | /api/v1/servers/:id | Get server details and tools | | GET | /api/v1/tools | List all tools (filterable by ?server= or ?tag=) | | POST | /api/v1/tools/call | Invoke a tool | | GET | /api/v1/metrics | Aggregated metrics (JSON or Prometheus) | | GET | /api/v1/requests | Recent request log |

Configuration Reference

port: 4000                    # HTTP port (env: MCP_GATEWAY_PORT)
host: 0.0.0.0                 # Bind address (env: MCP_GATEWAY_HOST)
logLevel: info                # debug | info | warn | error

auth:
  strategy: api-key           # none | api-key | jwt
  apiKeys:
    - "your-secret-key"

rateLimit:
  limit: 100                  # Max requests per window
  windowSeconds: 60           # Window duration
  perKey: true                # Per-key or global

monitor:
  requestLog: true            # Log all requests
  prometheus: true            # Enable Prometheus /metrics
  retentionHours: 24          # Metrics retention

corsOrigins:
  - "https://your-app.com"

servers:
  - id: my-server             # Unique identifier
    name: My Server           # Display name
    transport: stdio          # stdio | sse | websocket
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    env:
      MY_VAR: "${ENV_VAR}"    # Environment variable substitution
    tags: [files, local]
    enabled: true
    timeout: 30000            # ms
    maxConcurrency: 10

Docker

# Pull and run
docker run -p 4000:4000 \
  -v $(pwd)/mcp-gateway.yml:/app/mcp-gateway.yml \
  -e GITHUB_TOKEN=ghp_... \
  ghcr.io/harrisonCN/mcp-gateway:latest

# Or with Docker Compose
cd examples/docker
docker compose up

Embed as a Library

import { Gateway, loadConfig } from 'mcp-gateway';

const config = await loadConfig('./mcp-gateway.yml');
const gateway = new Gateway(config);

await gateway.start();
// Gateway is now running at http://localhost:4000

// Graceful shutdown
process.on('SIGTERM', () => gateway.stop());

Roadmap

| Feature | Status | |---------|--------| | stdio transport | ✅ Done | | SSE transport | 🔄 In Progress | | WebSocket transport | 📋 Planned | | Web dashboard UI | 📋 Planned | | Redis-backed rate limiting | 📋 Planned | | OAuth2 / OIDC auth | 📋 Planned | | Tool-level access control (RBAC) | 📋 Planned | | Request replay & debugging | 📋 Planned | | Multi-tenant mode | 📋 Planned | | OpenTelemetry tracing | 📋 Planned |

Contributing

Contributions are welcome! See CONTRIBUTING.md.

git clone https://github.com/HarrisonCN/mcp-gateway.git
cd mcp-gateway
npm install
npm run dev -- start -c examples/basic/mcp-gateway.yml

License

MIT © 2026 HarrisonCN