MCP Transport Firewall

Fail-closed proxy for risky local MCP file/search tool calls.

mcp-transport-firewall sits between a coding-agent client and a local downstream MCP server. It inspects tools/call over stdio, lets read/search-shaped requests continue, and blocks risky exfiltration, path, and shell-style patterns before they reach the target.

Best For

• individual Codex and Claude Code users who already run local MCP servers
• local MCP-enabled coding workflows that should not run high-risk calls blindly
• file, read, list, and search-oriented downstream MCP servers
• teams that want a fail-closed transport control before downstream execution

60-Second Proof

npm install
npm --prefix ui install
npm run build
npm run demo:stdio

Expected output:

stdio demo passed
allow: tool=search_files callCount=1
cache: second response matched first response for tool=search_files
block: ShadowLeak request denied with code=SHADOWLEAK_DETECTED
block: missing auth denied with code=AUTH_FAILURE

What This Proves

• the first search_files request reaches the downstream target
• the repeated allow request is served from cache
• the risky fetch_url exfiltration sample is denied before downstream execution
• the missing-auth sample is denied at the transport boundary

See docs/DEMO_RUN_TRANSCRIPT.md for the example transcript.

Install In Your MCP Client

Protected downstream proxy mode is the primary integration path.

{
  "mcpServers": {
    "protected-local-tooling": {
      "command": "npx",
      "args": ["-y", "mcp-transport-firewall"],
      "env": {
        "PROXY_AUTH_TOKEN": "replace-with-32-byte-secret",
        "MCP_TARGET_COMMAND": "node",
        "MCP_TARGET_ARGS_JSON": "[\"C:/absolute/path/to/your-mcp-server.js\"]"
      }
    }
  }
}

Use PROXY_AUTH_TOKEN for fail-closed auth, and MCP_TARGET_COMMAND plus MCP_TARGET_ARGS_JSON as the default downstream target input. See docs/CLIENT_CONFIG_EXAMPLES.md for client examples.

Need Help Hardening A Local MCP Workflow?

Use the guided setup path when you want practical help instead of a generic feature request.

• guided setup for a Codex or Claude Code local MCP stack
• workflow hardening audit for risky file, search, fetch, or execute paths
• trust-gate tuning for a specific downstream MCP server

Start here:

• read the operator guide: docs/WORKFLOW_HARDENING.md
• open a guided setup request: guided setup request
• use the scoped intake and early-operator offer details: docs/GUIDED_SETUP_AND_AUDITS.md

What This Is Not

• not a kernel, VM, or container sandbox
• not full MCP security for every transport or deployment topology
• not post-execution containment after a tool has already started
• not a guarantee against every prompt-injection or semantic evasion variant

See docs/LIMITS_AND_NON_GOALS.md for the explicit boundaries.

What It Blocks

• missing or invalid auth envelopes when shared-secret auth is enabled
• scope escalation across tool boundaries
• mixed-trust boundary violations and missing preflight for high-trust actions
• schema-smuggled arguments on registered tool contracts
• ShadowLeak-style exfiltration strings, sensitive paths, and shell-injection markers

The primary inspected surface is JSON-RPC tools/call over stdio. Blocked requests fail closed and are not forwarded to the downstream target.

Additional Modes

Standalone Bundled MCP Server

If you want a self-contained MCP server with bundled diagnostic tools and no downstream target, the package still supports standalone mode:

npx -y mcp-transport-firewall

This exposes firewall_status and firewall_usage. It is supported, but it is not the primary onboarding story for this repository.

HTTP Compatibility Harness

The repository also includes an HTTP companion harness, admin API, dashboard, and metrics exporter. Those surfaces are useful for compatibility testing, observability, and packaging validation, but they are secondary to the primary stdio boundary.

docker compose up --build

Control-plane endpoints:

• http://localhost:3000/health
• http://localhost:9090/health
• http://localhost:9090/metrics
• http://localhost:9090

Trust Gates

Gate	Enforcement	Code
nhi-auth-validator	fail-closed shared-secret authorization envelope and scope extraction	src/middleware/nhi-auth-validator.ts
scope-validator	reject tool calls outside declared scopes	src/middleware/scope-validator.ts
color-boundary	block mixed trust domains and session color flips	src/middleware/color-boundary.ts
preflight-validator	require one-time preflight IDs for high-trust (blue) actions	src/middleware/preflight-validator.ts
schema-validator	enforce strict contracts for registered tool schemas	src/middleware/schema-validator.ts
ast-egress-filter	deny exfiltration, sensitive-path, shell-injection, and epistemic-risk markers	src/middleware/ast-egress-filter.ts

Package Contract

Supported CLI entry points are:

npx -y mcp-transport-firewall
npx -y mcp-transport-firewall --help
npm install -g mcp-transport-firewall

The recommended order is:

1. prove the boundary locally with npm run demo:stdio
2. integrate protected downstream proxy mode in your MCP client
3. use standalone bundled mode only when you explicitly want embedded status tools instead of a downstream target

Docs

• client setups: docs/CLIENT_CONFIG_EXAMPLES.md
• proxy setup: docs/PROXY_SETUP.md
• runtime contract: docs/RUNTIME_CONTRACT.md
• limits and non-goals: docs/LIMITS_AND_NON_GOALS.md
• risk model: docs/RISK_MODEL.md
• verification guide: docs/VERIFICATION_GUIDE.md
• evidence bundle: docs/EVIDENCE_BUNDLE.md
• ship checklist: docs/SHIP_CHECKLIST.md
• workflow hardening guide: docs/WORKFLOW_HARDENING.md
• guided setup and audits: docs/GUIDED_SETUP_AND_AUDITS.md

Reference docs:

• benchmark guide: docs/STDIO_BENCHMARK_GUIDE.md
• benchmark snapshot: docs/STDIO_BENCHMARK_SNAPSHOT.json
• demo transcript: docs/DEMO_RUN_TRANSCRIPT.md
• architecture: docs/ARCHITECTURE.md
• risk summary: docs/RISK_SUMMARY.md
• assurance packet: docs/ASSURANCE_PACKET.md
• distribution notes: docs/DISTRIBUTION_NOTES.md