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

MCP Gateway