Submit
MikkoParkkola

MCP Gateway

Community MikkoParkkola
Updated

Universal MCP Gateway - Single-port multiplexing with Meta-MCP for ~95% context token savings

MCP Gateway

Crates.ioRustLicense: 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
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.

MCP Server · Populars

MCP Server · New