Context Firewall is a local MCP proxy used to reduce the context token consumption of AI agents when using MCP tools. It sits between AI agents (such as Claude Code, Claude Desktop, Cursor, Cline, etc.) and all configured downstream MCP servers, and is responsible for compressing large tool outputs and collapsing tool definitions.
Purpose
- Solve MCP tool definition bloat: collapse 50+ tool definitions into 4 meta-tools, so the client only loads these 4 tools, greatly reducing token usage at startup.
- Compress tool output: compress large outputs such as raw HTML, base64 data blocks, and oversized JSON before they enter the model context window, with a measured compression rate of 60–95%.
Main capabilities
- Progressive tool disclosure: the client only sees 4 meta-tools—list_tool_categories, search_tools, invoke_tool, read_more. Only when a tool is actually searched for does it pay the token cost of that tool's complete schema.
- Output compression pipeline: executed in a fixed order—strip base64 → main content extraction and HTML-to-Markdown (if the page has an identifiable content area, strip page chrome such as navigation, header, and footer) → JSON structure-aware summarization → truncation by character budget.
- Full output is retrievable: all compressed output is stored in full in memory (opaque handle) and can be retrieved in pages via read_more(handle, offset, length), without being silently discarded.
- Session savings report: on shutdown, print a shareable terminal card (optionally a Markdown file) showing the savings in tool definition and output tokens, as well as which tools saved the most.
- Per-tool allow/deny policy: allowTools / denyTools can be added to downstream entries (exact names or * wildcards) to restrict which tools can be called; deny takes precedence over allow.
- Optional LLM summarization (disabled by default): send over-budget text to an OpenAI /chat/completions-compatible endpoint for factual summarization, preserving IDs, paths, URLs, numbers, and error information, with a read_more pointer attached. Requires explicit enablement at two levels: top-level llm block and llmSummary: true in the compression policy. Silently falls back to deterministic truncation when the endpoint is unavailable.
Usage
- Make Context Firewall the only MCP server: move all currently directly configured downstream servers (filesystem, github, everything, etc.) into the downstreams block of context-firewall.json. If the client points to both Context Firewall and existing servers, tool folding or compression benefits cannot be obtained.
- Configuration format: the downstreams block mirrors the mcpServers format. Each entry is either a stdio server (same shape as mcpServers) or a Streamable HTTP server. ${VAR_NAME} in string values is expanded from environment variables; a missing variable causes configuration loading to fail with a readable error.
- Client integration: use the same mcpServers block in .mcp.json, claude_desktop_config.json, .cursor/mcp.json, or cline_mcp_settings.json in the project root.
- Policy resolution order is default < perServer < perTool. callToolTimeoutMs is a top-level configuration (not nested under compression) and is the per-invoke_tool timeout (in milliseconds) passed to the downstream MCP SDK client; by default the SDK default of 60000ms is used.
Applicable scenarios
- Environments using any MCP client and any model that need to control context token costs.
- Scenarios with a large number of downstream MCP servers configured (e.g., 50+ tools).
- Scenarios where tool output contains large amounts of HTML, base64, or oversized JSON that needs to be compressed before entering the context.
Limitations and caveats
- Progressive disclosure involves trade-offs: tool descriptions arrive on demand mid-session, which is also the moment when the model is least likely to review embedded instructions. Mitigations in v0.3.0 include: search_tools results are wrapped in <untrusted-tool-descriptions> delimiters with a random nonce, and only a closing tag matching the nonce can end the block; the CLI prints a readable summary to stderr at startup. However, this is a text-level convention rather than a sandbox, and relies on the calling model to read and comply with nonce matching, and does not sanitize the description content itself. This delimiter framing consumes approximately 80–85 tokens per search_tools call.
- The categories shown by list_tool_categories also come from data provided downstream (via a rough verb-prefix heuristic in registry.ts), are not wrapped with the above delimiters, and are considered lower risk but not risk-free.
- Downstream tool descriptions are treated as untrusted input, are only displayed and never executed, but are passed through as-is without sanitization; search_tools does not strip or filter prompt injection text that a malicious downstream may insert. The trust boundary lies in choosing which downstream servers to configure.
- Token counting is always estimated as chars / 3.5, not an exact model-specific count, and session reports are always labeled "(estimated)".
- By default, no code path sends tool output content to an external API. When optional LLM summarization is enabled, over-budget non-security-sensitive output is sent to the configured endpoint. Security-related output (errors, permission denials, warnings, confirmations) is bypassed before this stage of the compression pipeline and is never sent.
- Security-related output is never silently compressed and passes through directly, with only a hard cap of 50000 characters.
- Tool parameters and output content are never written to logs or session reports; only server/tool names and character/token counts are recorded.
- No specific charging or pricing information is provided in the official documentation.
