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 # Gogcf-proxy --verbose uvx yfinance-mcpUse 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-serverAny 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.
- Spawns your MCP server as a subprocess
- Proxies stdin/stdout between client and server
- Responses: intercepts JSON-RPC responses, re-encodes structured JSON as GCF
- Requests: scans tool call arguments for GCF strings, decodes to JSON
- Passes everything else through unchanged in both directions
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
- Claude Code Plugin - one-command install for Claude Code users
- Codex Plugin - one-command install for OpenAI Codex users
- GCF Specification
- Documentation
- Cost Calculator
- Go library
- TypeScript library
- Python library
- Rust library
- Swift library
- Kotlin library
MIT - Dayna Blackwell / GCF