Context Firewall

Context Firewall

中文文档

Shrink large MCP tool outputs by 60–95% before they reach your model's context window — and collapse 50+ tool definitions into 4. Real HTML/JSON, measured — see benchmarks. Works with any MCP client, any model. Anything still over your configured token budget after compression is hard-truncated to that budget, with the full original always retrievable via read_more.

*The session report printed on shutdown — this one from a real 3-call session (two large file reads, one echo). Every number measured, none simulated.*

Context Firewall is a local MCP proxy that sits between your AI agent (Claude Code, Claude Desktop, Cursor, Cline, ...) and every downstream MCP server you've configured. Large tool outputs (raw HTML, base64 blobs, giant JSON) are compressed before they ever reach the model's context window, and the client sees exactly 4 tools no matter how many the downstream servers actually have.

Measured results

All figures measured against real downstream MCP servers, not synthetic data — full methodology and tables in docs/BENCHMARKS.md.

What it does

• Progressive tool disclosure — instead of loading every downstream tool's full schema at startup, the client sees 4 meta-tools (list_tool_categories, search_tools, invoke_tool, read_more) and only pays the token cost of a tool's full schema when it actually searches for it.
• Output compression pipeline — large tool results are run through base64 stripping, main-content extraction + HTML→Markdown conversion (page chrome — nav, site headers/footers — is stripped when the page has a recognizable content region, so your token budget goes to actual content instead of navigation links), JSON structure-aware summarization, and finally character-budget truncation, in that order, before being returned.
• Full output retrievable via `read_more` — nothing is silently thrown away. Every compressed output is stored in full (in memory, opaque handle) and can be paged back with read_more(handle, offset, length).
• Session savings report — on shutdown, prints a shareable terminal card (and optional Markdown file) showing tool-definition and output-token savings for the session, plus a breakdown of which tools saved the most.

Quickstart

npx context-firewall --config context-firewall.json

Minimal context-firewall.json (the downstreams block mirrors the mcpServers format you already know):

{

"downstreams": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"] }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" } } } }

(${GITHUB_TOKEN} above is just this example's environment variable *name* — pick whatever's already set in your shell; it gets expanded into GITHUB_PERSONAL_ACCESS_TOKEN, the env var name the downstream server itself actually reads.)

Which GitHub server? Two options, different tool counts:

• `@modelcontextprotocol/server-github` (used above) — the original npm package, 26 tools, one npx -y line, zero extra setup. Archived/no longer maintained upstream, but still functional.
• [`github/github-mcp-server`](https://github.com/github/github-mcp-server) — the actively-maintained official server, 44 tools (default toolset) to 85 (GITHUB_TOOLSETS=all). Ships as a Go binary or Docker image, not an npm package:

  "github": {

"command": "docker", "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" } }

or, running a locally-built/downloaded binary directly: "command": "/path/to/github-mcp-server", "args": ["stdio"] (same env block; add GITHUB_TOOLSETS to scope which of the 85 tools are exposed).

Per-tool allow/deny policy. Add allowTools/denyTools (array of exact names or * globs) to any downstream entry to restrict which of its tools can be invoked:

"github": {

"command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "denyTools": ["delete_*"] }

Deny always wins over allow. When allowTools is set, only matching tools are permitted; everything else on that server is blocked. An empty allowTools: [] is treated the same as omitting it (allow everything), not "deny everything". Blocked tools are hidden from search_tools results, and invoke_tool rejects them before dispatching to the downstream server. Tool counts in list_tool_categories and in the meta-tool descriptions are unfiltered totals — the policy is only enforced at search_tools/invoke_tool time.

Client setup

Set Context Firewall as your only MCP server — move every downstream server you currently configure directly (filesystem, github, everything, ...) into context-firewall.json's downstreams block instead. Your agent then sees 4 tools instead of the sum of every downstream server's tool count; pointing the client at Context Firewall *alongside* your existing servers doesn't give you the tool-collapse or compression benefit.

Each client below takes the same server entry:

{

"mcpServers": { "context-firewall": { "command": "npx", "args": ["-y", "context-firewall", "--config", "/absolute/path/to/context-firewall.json"] } } }

Claude Code

Project-scoped .mcp.json in your repo root (shown above), or via the CLI:

claude mcp add --transport stdio context-firewall -- npx -y context-firewall --config /absolute/path/to/context-firewall.json

Claude Desktop

claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json) — same mcpServers block as above.

Cursor

.cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (global) — same mcpServers block as above.

Cline

cline_mcp_settings.json (VS Code extension storage; macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json) — same mcpServers block as above.

Compatibility status

\* Verified via MCP protocol integration tests (236 automated tests, including full stdio protocol round-trips against real downstream servers, run in CI on every push). Real-client reports welcome.

Configuration

downstreams

Each entry is either a stdio server (same shape as mcpServers) or a Streamable HTTP server:

{

"downstreams": { "local-tool": { "command": "npx", "args": ["-y", "some-mcp-server"], "env": { "TOKEN": "${TOKEN}" } }, "remote-tool": { "url": "https://mcp.example.com/mcp", "transport": "streamable-http" } } }

${VAR_NAME} in any string value is expanded from the environment; a missing variable fails config load with a readable error.

compression

Policy resolution order is default < perServer < perTool (later overrides earlier, field by field):

{

"compression": { "default": { "maxOutputTokens": 2000, "htmlToMarkdown": true, "stripBase64": true, "jsonSummary": true, "llmSummary": false, "bypass": false }, "perServer": { "github": { "maxOutputTokens": 4000 } }, "perTool": { "filesystem/read_file": { "maxOutputTokens": 8000 } } } }

report

{

"report": { "enabled": true, "markdownPath": "./context-firewall-report.md" } }

callToolTimeoutMs

Top-level (not nested under compression). Per-invoke_tool timeout in milliseconds passed to the downstream MCP SDK client; a downstream that hangs without responding causes invoke_tool to return an isError result once this elapses, instead of blocking. Defaults to the SDK's own default (60,000ms) when unset.

{ "callToolTimeoutMs": 30000 }

How it works

The client calls list_tool_categories() to see what's connected and what it's roughly capable of, search_tools(query) to pull the full input schema for candidate tools, invoke_tool(server, tool, args) to actually run one (compressed on the way back), and read_more(handle, offset, length) to page through anything that got compressed. Compression, when it runs, always applies in the same order: strip base64 → main-content extraction + HTML to Markdown → JSON structure summary → truncate to budget (if the opt-in LLM summarization stage below is enabled, it runs right before truncation). Content extraction is conservative by design: it only strips chrome when a semantic content region ( / ) is recognizable or the removal clearly isn't the page's actual content, and falls back to whole