🛡️ mcp-firewall

The open-source security gateway for AI agents.

mcp-firewall sits between your MCP client and server, intercepting every tool call with enterprise-grade policy enforcement, real-time threat detection, and compliance-ready audit logging.

AI Agent ←→ mcp-firewall ←→ MCP Server
               ↕
         Policy Engine
         Audit Trail
         Threat Feed

AI agents can now execute tools — read files, run commands, query databases, make HTTP requests. Without guardrails, a single prompt injection can exfiltrate your credentials, execute arbitrary code, and chain tools for privilege escalation.

mcp-firewall is the WAF for AI agents.

The reviewed integration is available as the v0.2.0a1 GitHub prerelease. Download and verify its wheel as described in release instructions; this prerelease is not published to PyPI. See the changelog for changes and experimental recovery limits.

pip install mcp-firewall

# Wrap any MCP server with zero config
mcp-firewall wrap -- npx @modelcontextprotocol/server-filesystem /tmp

# Generate a starter policy
mcp-firewall init

Every tool call passes through 7 inbound security stages (plus optional human approval) and 2 outbound scanners:

Inbound (request screening):

1. Kill Switch — Emergency deny-all
2. Rate Limiter — Per-agent, per-tool, global
3. Injection Detector — Pattern-based, sensitivity configurable (low/medium/high)
4. Egress Control — Block SSRF, private IPs, cloud metadata
5. Threat Feed — Known attack patterns (built-in community rules)
6. Policy Engine — YAML policies + per-agent RBAC
7. Chain Detector — Dangerous tool sequences

When a rule requires approval, an interactive prompt asks the user; non-interactive sessions fail closed (deny).

Outbound (response scanning):

1. Secret Scanner — API keys, tokens, private keys
2. PII Detector — Email, phone, SSN, IBAN, credit cards

Simple YAML for common rules:

agents:
  claude-desktop:
    allow: [read_file, search]
    deny: [exec, shell, rm]
    rate_limit: 100/min

rules:
  - name: block-credentials
    match: { arguments: { path: "**/.ssh/**" } }
    action: deny

See Policy Reference for the full rule schema.

mcp-firewall wrap --dashboard -- python my_server.py
# → Dashboard at http://localhost:9090

Live event feed and statistics.

Enable audit.sign: true to sign every event with Ed25519 in addition to the hash chain. Export to SIEM (CEF/LEEF), Syslog, CSV, or JSON.

mcp-firewall audit    # Verify chain integrity
mcp-firewall audit export --format cef --output siem.log

Auto-generated evidence for regulatory audits:

mcp-firewall report dora     # EU Digital Operational Resilience Act
mcp-firewall report finma    # Swiss Financial Market Authority
mcp-firewall report soc2     # SOC 2 Type II evidence

Community-maintained detection rules (like Sigma for SIEM):

mcp-firewall feed list       # Show active rules

Rules detect known-bad patterns: webhook exfiltration, credential harvesting, cloud metadata SSRF, and more.

Pre-deployment security scanning (powered by mcpwn):

mcp-firewall scan -- python my_server.py

Works with every MCP client — zero code changes:

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-firewall",
      "args": ["wrap", "--", "npx", "@modelcontextprotocol/server-filesystem", "/home"]
    }
  }
}

Compatible with: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, and any MCP client.

┌─────────────┐     ┌──────────────────────────────┐     ┌─────────────┐
│  MCP Client │◄───►│          mcp-firewall            │◄───►│  MCP Server │
└─────────────┘     │                               │     └─────────────┘
                    │  Inbound ─► Policy ─► Outbound│
                    │      │         │         │     │
                    │      ▼         ▼         ▼     │
                    │  [Audit] [Alerts] [Metrics]    │
                    │      │                         │
                    │      ▼                         │
                    │  [Dashboard]  [Reports]        │
                    └──────────────────────────────--┘

• Developers: Protect your machine when trying new MCP servers
• Security Teams: Enforce tool usage policies across the organization
• Compliance Officers: Generate audit evidence for DORA, FINMA, SOC 2
• CISOs: Visibility and control over AI agent behavior
• Red Teamers: Test AI agent security posture

mcp-firewall works as a Python library, not just an MCP proxy. Use it with OpenClaw, LangChain, CrewAI, or any custom agent:

from mcp_firewall.sdk import Gateway

with Gateway(config_path="mcp-firewall.yaml") as gw:
    decision = gw.check("read_file", {"path": "/tmp/example.txt"}, agent="my-agent")
    if decision.blocked:
        print(f"Blocked: {decision.reason}")
    else:
        # Illustrative output: the SDK itself never executes the tool.
        output = "AWS_KEY=AKIAIOSFODNN7EXAMPLE"
        result = gw.scan_response(output, context=decision.context)
        print(result.content)  # "AWS_KEY=[REDACTED by mcp-firewall]"

See examples/openclaw_integration.py for a full example.

SDK approval requests now fail closed by default, and configured audit logging is respected. See the SDK migration guide for changed defaults, async methods, structured responses, and resource cleanup.

Use mcp-firewall wrap --dashboard-approvals -- <server> for authenticated, single-call approval in the local dashboard. Set MCP_FIREWALL_DASHBOARD_TOKEN and connect the controller first. Missing approval, timeout or controller loss denies the call; global restrictions still apply. See setup and limits.

A native AgentReins adapter adds the same approval controls and correlated protocol evidence to a pinned AgentReins development build.

Export versioned lifecycle events to a local desktop companion or another HTTP receiver. Events correlate admission and response decisions using session and call IDs, with bounded background delivery and sanitized metadata. Audit entries and the dashboard use the same event model. Export never grants permission or proves that a tool executed.

See the integration contract, JSON schema, and example receiver.

mcpwn — Security scanner for MCP servers. While mcp-firewall protects at runtime, mcpwn finds vulnerabilities before deployment.

Scan first, then protect:

# Step 1: Scan for vulnerabilities
mcp-firewall scan -- python my_server.py

# Step 2: Protect at runtime
mcp-firewall wrap -- python my_server.py

Opt in to before/after file snapshots with wrap --dashboard-approvals --snapshot-workspace /absolute/project. The native adapter can display diffs and restore a selected file while rejecting stale edits. Snapshots are bounded and last for the proxy process lifetime; pause external writers before restore. See workspace rollback for setup and limits.

• Getting Started
• Policy Reference
• Compliance Guide
• Threat Feed
• Architecture
• Workspace snapshots and rollback

See CONTRIBUTING.md for guidelines.

Security issues: see SECURITY.md.

AGPL-3.0 — see LICENSE.

Commercial licensing available for organizations that cannot use AGPL. Contact rr@canus.ch.

Built by Robert Ressl — Associate Director Offensive Security at Kyndryl. CISSP, OSEP, OSCP, CRTO. After 100+ penetration tests and red team engagements across banking, insurance, and critical infrastructure, I saw the gap: AI agents are the new attack surface, and MCP is the protocol everyone uses but nobody secures.

mcp-firewall is the firewall that MCP needs.