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.

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

_{Built for the agentic era · If this helps you, please ⭐ star the repo}

MCP Servers