MCP Gateway

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
No resilience	Circuit breakers, retries, rate limiting

Architecture

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

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%

Production Failsafes

Failsafe	Description
Circuit Breaker	Opens after 5 failures, half-opens after 30s
Retry with Backoff	3 attempts with exponential backoff
Rate Limiting	Per-backend request throttling
Health Checks	Periodic ping to detect failures
Graceful Shutdown	Clean connection termination
Concurrency Limits	Prevent backend overload

Protocol Support

• MCP Version: 2025-11-25 (latest)
• Transports: stdio, Streamable HTTP, SSE
• JSON-RPC 2.0: Full compliance

Quick Start

Installation

cargo install mcp-gateway

Usage

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

# Override port
mcp-gateway --config servers.yaml --port 8080

# Debug logging
mcp-gateway --config servers.yaml --log-level debug

Configuration

Create servers.yaml:

server:
  port: 39400

meta_mcp:
  enabled: true

failsafe:
  circuit_breaker:
    enabled: true
    failure_threshold: 5
  retry:
    enabled: true
    max_attempts: 3

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"

Client Configuration

Point your MCP client to the gateway:

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

API Reference

Endpoints

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

Health Check Response

{
  "status": "healthy",
  "version": "1.0.0",
  "backends": {
    "tavily": {
      "name": "tavily",
      "running": true,
      "transport": "stdio",
      "tools_cached": 3,
      "circuit_state": "Closed",
      "request_count": 42
    }
  }
}

Configuration Reference

Server

Field	Type	Default	Description
host	string	127.0.0.1	Bind address
port	u16	39400	Listen port
request_timeout	duration	30s	Request timeout
shutdown_timeout	duration	30s	Graceful shutdown timeout

Meta-MCP

Field	Type	Default	Description
enabled	bool	true	Enable Meta-MCP mode
cache_tools	bool	true	Cache tool lists
cache_ttl	duration	5m	Cache TTL

Failsafe

Field	Type	Default	Description
circuit_breaker.enabled	bool	true	Enable circuit breaker
circuit_breaker.failure_threshold	u32	5	Failures before open
circuit_breaker.success_threshold	u32	3	Successes to close
circuit_breaker.reset_timeout	duration	30s	Half-open delay
retry.enabled	bool	true	Enable retries
retry.max_attempts	u32	3	Max retry attempts
retry.initial_backoff	duration	100ms	Initial backoff
retry.max_backoff	duration	10s	Max backoff
rate_limit.enabled	bool	true	Enable rate limiting
rate_limit.requests_per_second	u32	100	RPS per backend

Backend

Field	Type	Required	Description
command	string	*	Stdio command
http_url	string	*	HTTP/SSE URL
description	string		Human description
enabled	bool		Default: true
timeout	duration		Request timeout
idle_timeout	duration		Hibernation delay
env	map		Environment variables
headers	map		HTTP headers
cwd	string		Working directory

*One of command or http_url required

Environment Variables

Variable	Description
MCP_GATEWAY_CONFIG	Config file path
MCP_GATEWAY_PORT	Override port
MCP_GATEWAY_HOST	Override host
MCP_GATEWAY_LOG_LEVEL	Log level
MCP_GATEWAY_LOG_FORMAT	text or json

Metrics

With --features metrics:

curl http://localhost:39400/metrics

Exposes Prometheus metrics for:

• Request count/latency per backend
• Circuit breaker state changes
• Rate limiter rejections
• Active connections

Building

git clone https://github.com/MikkoParkkola/mcp-gateway
cd mcp-gateway
cargo build --release

License

MIT License - see LICENSE for details.

Credits

Created by Mikko Parkkola

Implements Model Context Protocol version 2025-11-25.