Drop-in MCP proxy. 71% fewer tokens. Session dedup compounds to 92%. Zero code changes.
Bidirectional MCP proxy that translates between JSON and GCF. Drop-in, zero changes to your server or client. Works with any structured data format.
100% comprehension on every frontier model. 29% fewer tokens than TOON, 56% fewer than JSON (2,400+ evals, 11 models, 3 providers). Nested object flattening with opt-out for open-weight models. One line change in your MCP config.
pip install gcf-proxy # PyPI
npm install -g @blackwell-systems/gcf-proxy # npm
go install github.com/blackwell-systems/gcf-proxy@latest # Go
gcf-proxy --verbose uvx yfinance-mcp
Use it with any MCP client. When tools return structured JSON, the proxy re-encodes to GCF and logs savings to stderr:
gcf-proxy: get_price_history 54.0KB -> 28.1KB (48% saved)
gcf-proxy: get_ticker_info 10.0KB -> 7.4KB (26% saved)
gcf-proxy: get_price_history 53.8KB -> 27.9KB (48% saved)
--- gcf-proxy session stats ---
Tool calls rewritten: 3
JSON bytes in: 117.8KB
GCF bytes out: 63.4KB
Bytes saved: 54.4KB (46.2%)
Est. tokens saved: ~13.6K
-------------------------------
Real live stock data from Yahoo Finance. 118KB of JSON reduced to 63KB. ~13,600 tokens saved in 3 tool calls.
Add gcf-proxy in front of any MCP server command:
{
"mcpServers": {
"memory": {
"command": "gcf-proxy",
"args": ["npx", "-y", "@modelcontextprotocol/server-memory"]
}
}
}
Point --upstream at any Streamable HTTP MCP server:
{
"mcpServers": {
"remote": {
"command": "gcf-proxy",
"args": ["--upstream", "http://host:3000/mcp"]
}
}
}
Supports JSON and SSE responses. Session ID tracking via Mcp-Session-Id is automatic.
--http turns the proxy into a remote Streamable HTTP server:
gcf-proxy --http :9090 --session your-mcp-server
Any MCP client that supports HTTP transport connects directly. Health check at /health. Chains with --upstream for fully remote deployments.
Both modes are bidirectional: server responses are encoded to GCF, GCF in tool call arguments is decoded to JSON. Neither side needs to change.
| Flag | Description |
|---|---|
--session | Enable session dedup (bare refs for previously-transmitted symbols) |
--cache | Cache encoded responses for identical tool calls |
--delta | Send only changed symbols when a tool's response changes slightly |
--no-flatten | Use expanded encoding for nested objects (open-weight models currently comprehend this form better; GCF still outperforms JSON either way) |
--min-size N | Skip encoding for responses smaller than N bytes (default: 100) |
--stream-threshold N | Min symbols before streaming mode activates (default: 5) |
--stats-file PATH | Write JSON stats to file after each call |
--upstream URL | Connect to a remote MCP server over HTTP |
--http ADDR | Serve MCP over Streamable HTTP |
--no-progress | Disable progress notifications |
--verbose | Log per-call savings to stderr |
Before: {"tool":"context_for_task","symbols":[{"qualified_name":"pkg.Auth","kind":"function","score":0.78,...},...]}
After: GCF profile=graph tool=context_for_task budget=5000 tokens=1900 symbols=50 edges=20
## targets
@0 fn pkg.Auth 0.78 lsp_resolved
...
53-71% fewer input tokens.
If the LLM produces GCF in a tool call argument (63% fewer output tokens), the proxy decodes it to JSON before forwarding:
LLM sends: {"tool": "process", "arguments": {"data": "GCF profile=generic\nname=Alice\nage=30\n"}}
Server gets: {"tool": "process", "arguments": {"data": {"name": "Alice", "age": 30}}}
Detection is a 4-byte prefix check (GCF ). Zero overhead. Non-GCF strings pass through untouched.
Sometimes you can't. The server is a third-party binary, or it's maintained by another team, or you just don't want to add a dependency. gcf-proxy gives you the token savings without touching server code.
If you control the server, use the GCF libraries directly for better control over session deduplication and delta encoding.
100% general comprehension on every frontier model. 91.2% on adversarial code graphs (vs TOON 68.8%, JSON 54.1%). Wins 15/16 datasets on token benchmark.
| Eval | GCF | TOON | JSON |
|---|---|---|---|
| General comprehension | 100% | 100% | 100% |
| Adversarial code graphs (500 symbols) | 91.2% | 68.8% | 54.1% |
| Token efficiency (16 datasets) | 15/16 wins | 1/16 | baseline |
Reproduce comprehension eval: git clone https://github.com/blackwell-systems/gcf-go && cd gcf-go/eval && GOWORK=off go test -run TestComprehension -v -timeout 0
Reproduce token benchmark: git clone https://github.com/blackwell-systems/toon && cd toon && git checkout gcf-comparison && cd benchmarks && pnpm install && pnpm benchmark:tokens
MIT - Dayna Blackwell / GCF
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y @blackwell-systems/gcf-proxyMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-blackwell-systems-gcf-proxy": {
"command": "npx",
"args": [
"-y",
"@blackwell-systems/gcf-proxy"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup reference@blackwell-systems/gcf-proxynpmio.github.blackwell-systems/gcf-proxy works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.