Skip to content
MCPFirewall

How It Works

The problem

Section titled “The problem”

When your AI client calls an MCP tool, the request goes directly to the MCP server. There is no visibility, no approval step, and no way to restrict which tools get used.

The proxy

Section titled “The proxy”

MCPFirewall inserts itself between the AI client and the MCP server:

AI Client  ->  mcpfw shim  ->  Gateway  ->  MCP Server
  (Claude)     (stdio bridge)  (localhost)   (upstream)

Each MCP server gets a shim process. The shim is a lightweight bridge that your AI client spawns instead of the real server. It looks like a normal MCP server to the AI, but forwards everything to the MCPFirewall gateway.

The gateway is the core of the system. It runs on localhost, stores all configuration in a local SQLite database, and makes every governance decision: allow, block, or hold for approval.

What the gateway does

Section titled “What the gateway does”

When a tool call arrives, the gateway:

  1. Identifies the tool and the server it belongs to
  2. Resolves the active ruleset based on the project directory, the AI client, or the global default
  3. Checks the tool’s mode: enabled, requires approval, or disabled
  4. Applies the decision: forwards to the server, parks the request for human review, or silently filters the tool out
  5. Logs the result in the audit trail

All of this happens in milliseconds for enabled tools. Approval-mode tools wait for your decision without consuming CPU.

Transport security

Section titled “Transport security”

Shims prefer a Unix domain socket (~/.mcpfw/gateway.sock) over TCP. The socket has owner-only permissions, so only your user can talk to the gateway. TCP on localhost:8765 is the fallback when sockets are not available.

On Linux, the gateway also verifies the connecting process belongs to your user via SO_PEERCRED.

Everything stays local

Section titled “Everything stays local”

The gateway, database, vault, and audit log all live in ~/.mcpfw/ on your machine. No data leaves your computer unless you connect to a team organization (Team tier — coming soon).

Next steps

Section titled “Next steps”