mcp-gateway

The enterprise infrastructure layer for MCP. Authentication, authorization, audit logging, rate limiting, usage metering, and secret management — for AI agents calling MCP tools in production.

Think: Cloudflare + Okta + Datadog, but for Model Context Protocol.

Why

MCP today: agent → server. Direct connection. No auth, no audit trail, no rate limits, no billing, no secret management.

That's fine for demos. It's not fine for:

• Healthcare (HIPAA audit requirements)
• Finance (SOC 2, regulatory compliance)
• Enterprise (RBAC, cost allocation, security)

MCP Gateway sits between agents and servers, enforcing policy on every tool call.

Agent (Claude, GPT, etc.)
  ↓ MCP protocol
┌──────────────────────────┐
│      MCP Gateway         │
│  Auth → Policy → Audit   │
│  Rate Limit → Meter      │
│  Secrets → Sandbox       │
└──────────────────────────┘
  ↓ MCP protocol
MCP Server (any server)

Five Pillars

1. Registry + Discovery

Register MCP servers. Agents discover available tools through the gateway. Multi-tenant: each consumer sees only what they're allowed to see.

2. Policy + Permissions (RBAC)

• API key authentication per agent/consumer
• Role-based tool permissions (reader can get_* and search_*, not delete_*)
• Server-level restrictions (block access to mcp-stripe for read-only agents)
• Parameter-level conditions (only allow queries for own customer ID)

3. Audit + Provenance

• Every tool call logged: who, what, when, args, response, latency
• Tamper-evident hash chain — each entry hashes the previous, detectable if modified
• Exportable to S3, webhook, SIEM
• Query by consumer, server, tool, status, time range

4. Metering + Billing

• Usage tracking per consumer, per server, per tool
• Calls, latency, error rates
• Cost allocation for chargeback
• Stripe integration ready

5. Runtime Sandbox + Secrets

• MCP servers run as managed child processes
• Secrets injected via environment variables — never exposed to agents
• Timeout enforcement, automatic restart on crash
• Server health monitoring

Quick Start

# Install
git clone https://github.com/PetrefiedThunder/mcp-gateway.git
cd mcp-gateway
npm install && npm run build

# Generate config
npx mcp-gateway init

# Edit gateway.yaml with your servers and API keys

# Start the gateway (as an MCP server)
npx mcp-gateway serve

Configuration

The gateway is configured via gateway.yaml:

auth:
  type: api-key
  keys:
    - id: key-1
      key: gw_your_key_here
      name: "Production Agent"
      consumerId: agent-prod
      roles: [reader, writer]
      enabled: true

servers:
  - id: mcp-fred
    name: "Federal Reserve Economic Data"
    command: node
    args: ["./mcp-fred/dist/index.js"]
    enabled: true

  - id: mcp-stripe
    name: "Stripe Payments"
    command: node
    args: ["./mcp-stripe/dist/index.js"]
    env:
      STRIPE_SECRET_KEY: "${STRIPE_SECRET_KEY}"
    enabled: true

policies:
  - id: reader-policy
    name: "Read-only access"
    roles: [reader]
    rules:
      - tool: "get_*"
        action: allow
      - tool: "search_*"
        action: allow
      - tool: "*"
        action: deny

  - id: admin-policy
    name: "Full access"
    roles: [admin]
    rules:
      - action: allow

audit:
  enabled: true
  storage: sqlite
  path: ./gateway-audit.db
  hashChain: true

metering:
  enabled: true
  dimensions: [calls, latency, errors]

rateLimit:
  enabled: true
  defaultPerMinute: 60

CLI

# API Key Management
mcp-gateway keys list
mcp-gateway keys create "My Agent" agent-1 reader,writer
mcp-gateway keys revoke key-123

# Server Management
mcp-gateway servers list

# Audit
mcp-gateway audit log --limit=50
mcp-gateway audit stats
mcp-gateway audit verify    # verify hash chain integrity

# Usage
mcp-gateway usage
mcp-gateway usage agent-1

Gateway Tools (MCP Interface)

The gateway itself is an MCP server. Connect to it and use these tools:

Tool	Description
call	Call any registered tool through the auth/policy/audit pipeline
list_tools	List available tools (filtered by caller permissions)
list_servers	List registered MCP servers and status
server_status	Detailed server health status
audit_log	Query the audit log
audit_verify	Verify tamper-evident hash chain
audit_stats	Audit statistics
usage	Usage metrics by consumer

Usage with Claude Desktop

{
  "mcpServers": {
    "gateway": {
      "command": "node",
      "args": ["/path/to/mcp-gateway/dist/index.js"],
      "env": {
        "MCP_GATEWAY_CONFIG": "/path/to/gateway.yaml"
      }
    }
  }
}

Architecture

src/
├── index.ts          # MCP server entry point (stdio transport)
├── serve.ts          # HTTP server entry point (network transport)
├── cli.ts            # CLI management tool
├── gateway.ts        # Core orchestrator — auth → policy → audit → meter → proxy
├── auth.ts           # API key + JWT + OIDC authentication
├── policy.ts         # RBAC policy engine (glob matching, conditions)
├── audit.ts          # SQLite/Postgres audit log with hash chain
├── storage.ts        # Storage abstraction (SQLite embedded, PostgreSQL)
├── ratelimit.ts      # Token bucket rate limiter with burst
├── meter.ts          # Usage metering and aggregation
├── metrics.ts        # Prometheus /metrics endpoint
├── registry.ts       # Server lifecycle management + auto-restart
├── proxy.ts          # MCP JSON-RPC proxy (stdio)
├── redact.ts         # PII redaction (SSN, credit card, field-level)
├── ipfilter.ts       # IP allowlist/denylist (CIDR, wildcard)
├── tenant.ts         # Multi-tenant workspace isolation
├── export.ts         # Audit export (JSONL, CSV, webhook, S3)
├── config.ts         # YAML config loader + validation + hot-reload
├── middleware.ts      # Request tracking, timeouts, structured logging
├── openapi.ts        # OpenAPI 3.1 spec generation
└── types.ts          # TypeScript domain types

Production Deployment

# Docker Compose (Gateway + Postgres + Prometheus + Grafana)
docker-compose up -d

# Access:
# Gateway:     http://localhost:3100
# Prometheus:  http://localhost:9090
# Grafana:     http://localhost:3000 (admin/admin)
# Metrics:     http://localhost:3100/metrics
# OpenAPI:     http://localhost:3100/openapi.json

Compliance

• HIPAA: PII redaction, tamper-evident audit log, field-level access control
• SOC 2: Complete audit trail, RBAC, rate limiting, IP filtering
• PCI-DSS: Credit card redaction, API key rotation, network controls
• GDPR: Per-tenant data isolation, audit export for data requests

58 Tests

 ✓ auth.test.ts       (6 tests)   — API key auth, disabled/expired keys
 ✓ auth-jwt.test.ts   (5 tests)   — JWT verification, claims, issuer
 ✓ policy.test.ts     (6 tests)   — RBAC, glob matching, deny precedence
 ✓ ratelimit.test.ts  (6 tests)   — token bucket, burst, isolation
 ✓ audit.test.ts      (3 tests)   — log, query, hash chain verify
 ✓ meter.test.ts      (4 tests)   — usage tracking, isolation
 ✓ storage.test.ts    (4 tests)   — SQLite insert, query, upsert, stats
 ✓ config.test.ts     (5 tests)   — validation, duplicates, missing fields
 ✓ redact.test.ts     (7 tests)   — SSN, CC, email, field-level, per-server
 ✓ ipfilter.test.ts   (5 tests)   — allowlist, denylist, CIDR, wildcard
 ✓ metrics.test.ts    (3 tests)   — Prometheus format, counters, histograms
 ✓ middleware.test.ts  (4 tests)   — request tracking, timeout, drain

License

MIT