🛡️ MCP Guard

Production guardrails for MCP (Model Context Protocol) servers. Lightweight, framework-agnostic ASGI gateway with multi-tenant auth, per-tool rate limiting, sensitive data redaction, and audit logging.

English | 中文文档

🎯 The Problem

The Model Context Protocol (MCP) standardizes how LLMs invoke local and remote tools. However, almost all open-source MCP servers assume single-user, local stdio usage.

When organizations expose MCP servers over HTTP/SSE across teams or to external partners, they face immediate production roadblocks:

• ❌ No Multi-Tenant Auth: No standard mechanism for issuing, validating, or revoking API keys per client.

• ❌ Lack of Tool-Aware Rate Limiting: Generic API gateways treat all HTTP calls the same. They cannot differentiate between cheap retrieval tools (search_docs) and expensive reasoning tools (ask_llm) nested inside JSON-RPC payloads.

• ❌ Data Leakage Risks: Output text easily leaks internal pricing, PII, API tokens, or internal database exceptions.

• ❌ Audit Blindspots: Missing structured records of who called which tool, with what arguments, execution latency, and error states.

Related MCP server: mcp-gateway

💡 The Solution: MCP Guard

MCP Guard is a lightweight, zero-bloat security layer for MCP servers. It sits directly in front of your tools and provides enterprise-ready guardrails out-of-the-box.

• 🔑 Multi-Tenant Key Manager: Bearer token authentication with constant-time comparison (hmac.compare_digest), SHA-256 hash storage, and dynamic hot-reloading.

• ⏱️ Per-Tool TokenBucket Rate Limiting: Independent QPS and burst capacity policies per tool, tenant-tier multipliers, and bounded memory with LRU idle client eviction.

• 🛡️ Dynamic Sensitive Data Redaction: Over-masking defense pipeline that strips sensitive patterns (prices, tokens, custom regex) across MCP content blocks.

• 📜 Structured Daily JSONL Audit Logs: High-performance, injection-safe audit trail recording caller_id, tool, duration_ms, redaction_hits, and sanitized arguments.

• 🔌 Universal ASGI / Starlette Bridge: Seamlessly works with Uvicorn, FastAPI, or any ASGI server.

🚀 Quick Start

1. Installation

git clone https://github.com/wangkun5212-hue/mcp-guard.git
cd mcp-guard
pip install -e .

2. Create a Protected MCP Server

import uvicorn
from mcp_guard.gateway import MCPGuardGateway
from mcp_guard.auth import KeyManager
from mcp_guard.limiter import PerToolRateLimiter, ToolRatePolicy
from mcp_guard.redactor import RedactionPipeline
from mcp_guard.audit import AuditLogger

# 1. Multi-Tenant Auth
key_mgr = KeyManager()
key_mgr.add_key(
    raw_key="sk-client-key-123",
    caller_id="partner_client",
    allowed_tools=["search_catalog"], # Whitelist access
    rate_multiplier=1.0,
)

# 2. Per-Tool Rate Limiter
limiter = PerToolRateLimiter(
    default_policy=ToolRatePolicy(rate_per_minute=60, burst_capacity=10),
    tool_policies={
        "heavy_reasoning_tool": ToolRatePolicy(rate_per_minute=5, burst_capacity=1),
    }
)

# 3. Create Guard Gateway
gateway = MCPGuardGateway(
    key_manager=key_mgr,
    rate_limiter=limiter,
    redactor=RedactionPipeline(),
    audit_logger=AuditLogger(log_dir="./logs"),
)

# 4. Register Tools
def search_catalog(query: str):
    return f"Result for '{query}'. Catalog license quote: $8,000 USD."

gateway.register_tool(
    schema={
        "name": "search_catalog",
        "description": "Search items in catalog",
        "inputSchema": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
    handler=search_catalog,
)

app = gateway.as_asgi_app()

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8000)

Run server:

python main.py

🔌 Connect Any MCP Client

Clients can connect using standard HTTP POST JSON-RPC 2.0 requests to /mcp with Authorization: Bearer <token>:

curl -X POST http://127.0.0.1:8000/mcp \
  -H "Authorization: Bearer sk-client-key-123" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search_catalog",
      "arguments": {"query": "server"}
    },
    "id": 1
  }'

Response with automatic data redaction:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Result for 'server'. Catalog license quote: ***."
      },
      {
        "type": "text",
        "text": "[Note: Sensitive info redacted by guardrails]"
      }
    ],
    "isError": false
  },
  "id": 1
}

🧪 Testing

Run test suite:

PYTHONPATH=. pytest tests/ -v

📄 License

MIT License. Free for commercial and research use.