MCP Firewall

A policy and audit layer for Model Context Protocol (MCP).

MCP Firewall sits transparently between any MCP client (Claude Desktop, Cursor, VS Code, etc.) and an upstream MCP server, allowing you to inspect, allow, block, or audit requests before they reach the server.

No changes are required to your client or your MCP server.

---

Status

MCP Firewall is an early open-source project.

The core stdio proxy, policy engine, audit logging, and enforcement pipeline are implemented and tested against the official MCP reference servers.

Feedback, bug reports, and contributions are welcome.

---

Why?

MCP servers can expose powerful capabilities such as:

• Reading files
• Writing files
• Executing shell commands
• Accessing databases
• Calling internal APIs

Once an AI agent has access to those tools, there is normally no policy layer deciding what should or shouldn't be allowed.

MCP Firewall adds that missing layer.

Instead of talking directly to an MCP server, the client talks to MCP Firewall. Every request is evaluated against your policy, recorded in the audit log, and either forwarded or blocked before reaching the upstream server.

---

How it works

Without MCP Firewall

Claude Desktop
      │
      ▼
Filesystem MCP Server
      │
      ▼
delete_file()
      │
      ▼
File deleted

With MCP Firewall

Claude Desktop
      │
      ▼
MCP Firewall
      │
      ├── Policy Evaluation
      ├── Audit Logging
      └── Read-only Checks
      │
      ▼
BLOCK delete_file()
      │
      ▼
JSON-RPC Error returned to the client

(The upstream server never receives the request.)

---

Features

Current release includes:

• Transparent stdio proxy
• Tool allow lists
• Tool deny lists
• Parameter-aware policy rules (match_params)
• Read-only mode
• Structured JSON audit logging
• Audit-only mode
• JSON-RPC compliant error responses
• Single Go binary
• No changes required to existing MCP clients or servers

---

Installation

Option 1: Download Pre-built Binary (Recommended)

Download the latest ready-to-run binary for Windows from the GitHub Releases page.

1. Download mcp-firewall.exe.
2. Place it in your project directory or system PATH.
3. Run mcp-firewall.exe init to generate a default configuration file.

---

Option 2: Build from Source (Requires Go 1.22+)

Requirements

• Go 1.22+
• Node.js (only if using official Node-based MCP reference servers)

Clone the repository:

git clone https://github.com/venu1222g/mcp-firewall.git
cd mcp-firewall

Build:

```bash
make build

or

go build -o mcp-firewall ./cmd/firewall

---

Quick Start

Generate a configuration:

./mcp-firewall init

Start the firewall:

./mcp-firewall run --config mcp-firewall.yaml

Then point your MCP client at the firewall instead of the upstream server.

Example (Claude Desktop):

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/mcp-firewall",
      "args": [
        "run",
        "--config",
        "/path/to/mcp-firewall.yaml"
      ]
    }
  }
}

Restart your MCP client.

Every request now passes through MCP Firewall before reaching the upstream server.

---

Configuration Examples

Block a tool

policy:
  default_action: allow
  tools:
    deny:
      - delete_file

---

Allow only selected tools

policy:
  default_action: block
  tools:
    allow:
      - read_file
      - list_directory

---

Protect a specific file

policy:
  default_action: allow
  rules:
    - id: protect-secrets
      method: tools/call
      action: block
      match_params:
        path: /etc/secrets.env

---

Audit a policy before enforcing it

server:
  mode: audit-only

Requests continue to reach the upstream server, but every policy decision is evaluated and recorded.

When you're satisfied with the policy, switch to:

server:
  mode: enforce

---

Enable read-only mode

read_only:
  enabled: true

Read-only mode blocks supported write/delete operations while continuing to allow read operations.

---

CLI

Generate a default configuration:

mcp-firewall init

Run the proxy:

mcp-firewall run --config mcp-firewall.yaml

Validate configuration and environment:

mcp-firewall doctor

Show version information:

mcp-firewall version

---

Tested Against

This release has been verified against:

• Official @modelcontextprotocol/server-filesystem
• Official @modelcontextprotocol/server-everything
• JSON-RPC 2.0 stdio transport
• Windows

---

Known Limitations

MCP Firewall is currently at v0.1.x.

The following limitations are known:

• Tool allow/deny policies perform exact tool-name matching.
• match_params currently matches scalar values only. Array-valued parameters are not matched.
• Read-only mode protects a built-in list of supported write/delete tools using exact tool names.
• Dynamic MCP capability annotations (readOnlyHint / destructiveHint) are not yet used.
• action: redact is reserved for a future release and currently behaves as a block.

---

Roadmap

Planned improvements include:

• Regex and glob matching
• Dynamic capability discovery
• Parameter redaction
• HTTP/SSE transport support
• Web dashboard

---

Contributing

Contributions are welcome.

make fmt
make test

Please open an issue before making large architectural changes or adding new features.

---

License

Apache License 2.0.