mcp-firewall

Purpose

mcpwall is a deterministic security proxy for MCP (Model Context Protocol) tool calls, described as "iptables for MCP." It is used to add a layer of policy control between AI coding tools and MCP servers, because MCP servers usually have full access to the file system, shell, databases, and APIs, and when an AI agent calls tools/call, the server directly executes its request, and the protocol itself has no built-in policy layer. mcpwall is designed precisely to fill this gap.

Main Capabilities

• Block access to sensitive files: such as .ssh/, .env, credentials, browser data.
• Block dangerous commands: such as rm -rf, piping to shell, reverse shells.
• Scan for secret leakage: for API keys, tokens, private keys, using regex plus entropy detection.
• Scan server responses: redact leaked secrets, block prompt injection patterns, flag suspicious content.
• Log everything: record every tool call and response in a JSON Lines audit trail.
• Zero AI: uses deterministic rules, makes no LLM decisions, and calls no cloud services.
• Rule testing: via mcpwall check, instantly get a pass or fail result for any tool call without running the proxy.

Usage

It can be used directly via npx. Configuration methods include:

• Option 1: Docker MCP Toolkit. If using this toolkit, change the MCP configuration to be wrapped via mcpwall; no configuration file is needed, and sensible defaults are applied automatically.
• Option 2: Interactive setup. It can automatically discover existing MCP servers in Claude Code, Cursor, Windsurf, and VS Code configurations and wrap them, with optional security profiles.
• Option 3: Manually wrap any MCP server. Modify the MCP configuration to go through mcpwall.
• Option 4: Wrap a specific server.

The workflow is divided into inbound and outbound:

• Inbound (requests): intercept every JSON-RPC request on stdin, parse tools/call, extract the tool name and parameters, match rules top-down, and the first match takes effect. If Allow, forward to the real server; if Deny, return a JSON-RPC error to the host and log it, without forwarding.
• Outbound(Response): Before forwarding, parse each response returned by the server and evaluate it against outbound_rules (also first-match-wins). Allow forwards as-is; Deny replaces the response with a block message; Redact replaces the secret exactly with [REDACTED BY MCPWALL] and then forwards the modified response; Log only forwards as-is and logs the match.

Configuration is YAML, looked up at ~/.mcpwall/config.yml (global) and .mcpwall.yml (project-level, overrides global). If neither exists, built-in default rules are applied. mcpwall does not support the interactive ask action; you must explicitly choose allow or deny. The special key _any_value lets a matcher apply to all argument values.

Optional security baselines are available (chosen at init time); each baseline is a YAML file under rules/profiles/, which can be copied and customized. Server-specific recipes are provided under rules/servers/: filesystem-mcp.yaml (restricts read/write/list to ${PROJECT_DIR}, blocks dotfiles and traversal), github-mcp.yaml (logs all file reads, blocks broad private repository enumeration), shell-mcp.yaml (adds network command and package installation blocking). Built-in rule packs include rules/default.yml (sensible defaults: block SSH, .env, credentials, dangerous commands, secrets) and rules/strict.yml (a paranoid default-deny mode that allowlists only project reads/writes).

Command-line arguments: -c/--config <path> specifies the config file; --log-level <level> overrides the log level (debug/info/warn/error); --strict rejects malformed JSON-RPC lines instead of forwarding them as-is. Use mcpwall check to test rules; exit codes: 0 means allow, 1 means deny or redacted, 2 means input or configuration error, suitable for pipelines and can be integrated into CI or scripts.

By default all tool calls are logged, including allowed and denied ones. Logs are written as JSON Lines to ~/.mcpwall/logs/YYYY-MM-DD.jsonl. In denied entries, arguments are redacted to prevent secrets from leaking into logs. They are also output in colorto stderr for real-time viewing of decisions.

Security Design

• Bidirectional scanning: both inbound requests and outbound responses are evaluated against the rules.
• Fail closed on invalid configuration: bad regexes in rules crash at startup, never silently letting traffic through.
• Fail open on malformed messages by default: non-JSON-RPC lines are forwarded as-is to preserve compatibility; with --strict, malformed JSON-RPC is rejected.
• Argument redaction on deny: arguments of blocked tool calls are never written to logs.
• Exact redaction: secrets in responses are replaced in place, preserving the JSON-RPC response structure.
• Path traversal defense: the not_under matcher uses path.resolve() to prevent ../ bypasses.
• Precompiled regexes: all patterns are compiled once at startup to ensure consistent performance.
• No network: zero cloud calls, zero telemetry, fully local operation.
• Deterministic: same input plus same rules yields the same output every time.

Use Cases and Limitations

Suitable for AI coding tool environments that use MCP servers, especially for teams or individuals who want to enforce deterministic security policies, auditing, and secret-leak prevention on tool calls without introducing LLM decisions and cloud dependencies. It can wrap servers in configurations for Docker MCP Toolkit, Claude Code, Cursor, Windsurf, VS Code, and others. In terms of limitations: you must explicitly choose allow or deny, with no support for interactive prompting; malformed messages fail open by default, and strict mode must be enabled manually; specific pricing, cost, and platform support details are not yet provided in the materials. mcpwall is not affiliated with or endorsed by Anthropic or the Model Context Protocol project; MCP is an open protocol maintained by the Agentic AI Foundation under the Linux Foundation.