Skip to content

✨ Features Overview

MCP Gateway is a gateway + registry + proxy purpose-built for the Model Context Protocol (MCP). It unifies REST, MCP, and stdio worlds while adding auth, caching, federation, and an HTMX-powered Admin UI.

🌐 Multi-Transport Core

Supported Transports
Transport Description Typical Use-case
HTTP / JSON-RPC Low-latency request-response, default for most REST clients Simple tool invocations
WebSocket Bi-directional, full-duplex Streaming chat or incremental tool results
Server-Sent Events (SSE) Uni-directional server → client stream LLM completions or real-time updates
STDIO Local process pipes via mcpgateway-wrapper Editor plugins, headless CLI clients
Try it: SSE from curl 
curl -N -H "Accept: text/event-stream" \
     -H "Authorization: Bearer $TOKEN" \
     http://localhost:4444/servers/UUID_OF_SERVER_1/sse

🌍 Federation & Discovery

Features
  • Auto-discovery - DNS-SD (_mcp._tcp.local.) or static peer list
  • Health checks - fail-over + removal of unhealthy gateways
  • Capability sync - merges remote tool catalogs into the local DB
  • Request forwarding - automatic routing to the correct gateway
Architecture 
graph TD
  subgraph Local_Gateway
    A[MCP Gateway Core]
  end
  subgraph Remote_Gateway_1
    B[Peer 1]
  end
  subgraph Remote_Gateway_2
    C[Peer 2]
  end
  A <-- ping / register --> B
  A <-- ping / register --> C
Configuration

Enable or tweak discovery via .env:

FEDERATION_ENABLED=true
FEDERATION_DISCOVERY=true
FEDERATION_PEERS=https://remote.example.com
HEALTH_CHECK_INTERVAL=30

🔐 Security

Auth mechanisms
  • JWT bearer (default, signed with JWT_SECRET_KEY)
  • HTTP Basic for the Admin UI
  • Custom headers (e.g., API keys) per tool or gateway
Rate limiting

Set MAX_TOOL_CALLS_PER_MINUTE to throttle abusive clients. Exceeding the limit returns HTTP 429 with a Retry-After header.

Generate a 24 h token 
python3 -m mcpgateway.utils.create_jwt_token \
  --username alice --exp 1440 --secret "$JWT_SECRET_KEY"

🛠 Tool & Server Registry

What you can register
Registry Entities Notes
Tools Native MCP tools or wrapped REST / CLI functions JSON Schema input validation
Resources URIs for blobs, text, images Optional SSE change notifications
Prompts Jinja2 templates + multimodal content Versioning & rollback
Servers Virtual collections of tools/prompts/resources Exposed as full MCP servers
gRPC Services gRPC microservices via automatic reflection Protocol translation to MCP/JSON
REST tool example 
curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "joke_api",
           "url": "https://icanhazdadjoke.com/",
           "requestType": "GET",
           "integrationType": "REST",
           "headers": {"Accept":"application/json"}
         }' \
     http://localhost:4444/tools

🔌 gRPC-to-MCP Translation

Automatic gRPC Integration
  • Server Reflection - Automatically discovers gRPC services and methods
  • Protocol Translation - Converts between gRPC/Protobuf ↔ MCP/JSON
  • Zero Configuration - No manual schema definition required
  • TLS Support - Secure connections to gRPC servers
  • Metadata Headers - Custom gRPC metadata for authentication
  • Admin UI - Manage gRPC services via web interface
Register a gRPC service 
# CLI: Expose gRPC service via HTTP/SSE
python3 -m mcpgateway.translate --grpc localhost:50051 --port 9000

# REST API: Register for persistence
curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "payment-service",
           "target": "payments.example.com:50051",
           "reflection_enabled": true,
           "tls_enabled": true
         }' \
     http://localhost:4444/grpc
How it works
  1. Gateway connects to gRPC server using Server Reflection Protocol
  2. Discovers all available services and methods automatically
  3. Translates Protobuf messages to/from JSON
  4. Exposes each gRPC method as an MCP tool
  5. Handles streaming (unary and server-streaming)
Supported gRPC features
Feature Status Notes
Unary RPCs ✅ Supported Request-response methods
Server Streaming ⚠️ Partial Basic support implemented
Client Streaming 🚧 Planned Future enhancement
Bidirectional Streaming 🚧 Planned Future enhancement
TLS/mTLS ✅ Supported Certificate-based auth
Metadata Headers ✅ Supported Custom headers for auth
Reflection ✅ Required Auto-discovery mechanism

🖥 Admin UI

Built with
  • FastAPI + Jinja2 + HTMX + Alpine.js
  • Tailwind CSS for styling
📊 Audit & Metadata Tracking
  • Comprehensive metadata for all entities (Tools, Resources, Prompts, Servers, Gateways)
  • Creation tracking - who, when, from where, how
  • Modification history - change attribution and versioning
  • Federation source tracking for MCP server entities
  • Bulk import batch identification
  • Auth-agnostic - works with/without authentication
  • Backwards compatible - legacy entities show graceful fallbacks

🗄 Persistence, Caching & Observability

Storage options
  • SQLite (default dev)
  • PostgreSQL, MySQL/MariaDB, MongoDB - via DATABASE_URL
Redis cache 
CACHE_TYPE=redis
REDIS_URL=redis://localhost:6379/0
Observability
  • Structured JSON logs (tap with jq)
  • /metrics - Prometheus-friendly counters (tool_calls_total, gateway_up)
  • /health - readiness + dependency checks

🧩 Dev & Extensibility

Highlights
  • Makefile targets - make dev, make test, make lint
  • 400+ unit tests - Pytest + HTTPX TestClient
  • VS Code Dev Container - Python 3.11 + Docker/Podman CLI
  • Plug-in friendly - drop-in FastAPI routers or Pydantic models

Next Steps

Ready to explore

With transports, federation, and security handled for you, focus on building great MCP tools, prompts, and agents-the gateway has your back.