Which integrations are available for this server?

Provides optional Prometheus metrics support for monitoring the gateway's performance, health status, and backend operations.

How do I use MCP Gateway?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Gateway list all the connected servers and their tools" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Gateway

PyPI version Python 3.11+ License: MIT

Universal Model Context Protocol (MCP) Gateway - Single-port multiplexing with Meta-MCP for ~95% context token savings.

The Problem

MCP is powerful, but scaling to many servers creates problems:

Without Gateway	With Gateway
100+ tool definitions in context	4 meta-tools
~15,000 tokens overhead	~400 tokens
Multiple ports to manage	Single port
Session loss on reconnect	Persistent proxy

The Solution

┌─────────────────────────────────────────────────────────────────┐
│                     MCP Gateway (:39400)                         │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  Meta-MCP Mode: 4 Tools → Access 100+ Tools Dynamically  │    │
│  │  • gateway_list_servers    • gateway_search_tools        │    │
│  │  • gateway_list_tools      • gateway_invoke              │    │
│  └─────────────────────────────────────────────────────────┘    │
│                              │                                   │
│         ┌────────────────────┼────────────────────┐             │
│         ▼                    ▼                    ▼             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
│  │   Tavily    │    │  Context7   │    │   Pieces    │         │
│  │  (stdio)    │    │   (http)    │    │   (sse)     │         │
│  └─────────────┘    └─────────────┘    └─────────────┘         │
└─────────────────────────────────────────────────────────────────┘

Quick Start

Installation

pip install mcp-gateway

Basic Usage

# Start with configuration file
mcp-gateway --config servers.yaml --port 39400

Configuration

Create servers.yaml:

port: 39400
enable_meta_mcp: true

backends:
  tavily:
    command: "npx -y @anthropic/mcp-server-tavily"
    description: "Web search"
    env:
      TAVILY_API_KEY: "${TAVILY_API_KEY}"

  context7:
    http_url: "http://localhost:8080/mcp"
    description: "Documentation lookup"

  pieces:
    http_url: "http://localhost:39300/sse"
    description: "Long-term memory"

Client Configuration

Point your MCP client to the gateway:

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

Features

Meta-MCP Mode (~95% Token Savings)

Instead of loading 100+ tool definitions, Meta-MCP exposes 4 meta-tools:

Meta-Tool	Purpose
`gateway_list_servers`	List available backends
`gateway_list_tools`	List tools from a specific backend
`gateway_search_tools`	Search tools by keyword across all backends
`gateway_invoke`	Invoke any tool on any backend

Token Math:

Traditional: 100 tools × 150 tokens = 15,000 tokens
Meta-MCP: 4 tools × 100 tokens = 400 tokens
Savings: 97%

Transport Support

Transport	Description	Example
stdio	Subprocess with JSON-RPC	`command: "npx server"`
http	HTTP POST	`http_url: "http://localhost:8080/mcp"`
sse	Server-Sent Events	`http_url: "http://localhost:8080/sse"`

Operational Features

Lazy Loading: Backends start on first access
Idle Timeout: Hibernate unused backends (configurable)
Auto-Reconnect: Survives client context compaction
Health Aggregation: Single /health endpoint
Tool Caching: Cached for session persistence

API Reference

HTTP Endpoints

Endpoint	Description
`GET /health`	Health check with backend status
`POST /mcp`	Meta-MCP mode (dynamic discovery)
`POST /mcp/{backend}`	Direct backend access

Environment Variables

Configuration values support environment variable expansion:

backends:
  tavily:
    command: "npx -y @anthropic/mcp-server-tavily"
    env:
      TAVILY_API_KEY: "${TAVILY_API_KEY}"  # Expanded at runtime

CLI Options

mcp-gateway [OPTIONS]

Options:
  -c, --config PATH       YAML configuration file
  -p, --port PORT         Port to listen on (default: 39400)
  --host HOST             Host to bind to (default: 127.0.0.1)
  --log-level LEVEL       DEBUG, INFO, WARNING, ERROR
  --no-meta-mcp           Disable Meta-MCP mode
  --version               Show version
  --help                  Show help

Programmatic Usage

import asyncio
from mcp_gateway import Gateway, GatewayConfig, BackendConfig

# Create configuration
config = GatewayConfig(
    port=39400,
    enable_meta_mcp=True,
    backends={
        "tavily": BackendConfig(
            name="tavily",
            command="npx -y @anthropic/mcp-server-tavily",
            description="Web search",
        )
    }
)

# Or load from YAML
config = GatewayConfig.from_yaml("servers.yaml")

# Create and run gateway
gateway = Gateway(config)
asyncio.run(gateway.run())

Production Deployment

systemd Service

[Unit]
Description=MCP Gateway
After=network.target

[Service]
Type=simple
User=mcp
ExecStart=/usr/local/bin/mcp-gateway --config /etc/mcp-gateway/servers.yaml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

macOS launchd

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.mcp.gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/mcp-gateway</string>
        <string>--config</string>
        <string>/etc/mcp-gateway/servers.yaml</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Docker

FROM python:3.12-slim

RUN pip install mcp-gateway

COPY servers.yaml /etc/mcp-gateway/
EXPOSE 39400

CMD ["mcp-gateway", "--config", "/etc/mcp-gateway/servers.yaml", "--host", "0.0.0.0"]

Metrics & Monitoring

Health Endpoint

curl http://localhost:39400/health

{
  "status": "healthy",
  "backends": {
    "tavily": {
      "running": true,
      "restart_count": 1,
      "tools_cached": 3
    }
  }
}

Prometheus Metrics (Optional)

Install with metrics support:

pip install mcp-gateway[metrics]

Troubleshooting

Backend Won't Start

Check the command is correct: npx -y @package/name
Verify environment variables are set
Check logs with --log-level DEBUG

Tool Not Found

Use gateway_search_tools to verify tool exists
Check backend is running: gateway_list_servers
Verify backend has started: check /health

Session Issues

The gateway caches tool lists on startup. If a backend restarts:

Tools are re-cached automatically
Check restart_count in health endpoint

Contributing

git clone https://github.com/MikkoParkkola/mcp-gateway
cd mcp-gateway
pip install -e ".[dev]"
pytest

License

MIT License - see LICENSE for details.

Credits

Created by Mikko Parkkola

Inspired by the need to scale MCP beyond a handful of servers without drowning in context tokens.

MCP Gateway

MCP Gateway

The Problem

The Solution

Quick Start

Installation

Basic Usage

Configuration

Client Configuration

Features

Meta-MCP Mode (~95% Token Savings)

Transport Support

Operational Features

API Reference

HTTP Endpoints

Environment Variables

CLI Options

Programmatic Usage

Production Deployment

systemd Service

macOS launchd

Docker

Metrics & Monitoring

Health Endpoint

Prometheus Metrics (Optional)

Troubleshooting

Backend Won't Start

Tool Not Found

Session Issues

Contributing

License

Credits

Resources

Latest Blog Posts

MCP directory API