# gcf-proxy

A proxy that sits between an MCP client and server, re-encoding tool responses as GCF to cut token use. One line in your config.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 11
- Author: blackwell-systems
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/blackwell-systems/gcf-proxy
- Updated: 2026-09-23
- HTML: https://affpapa.org/en/nevibecode/mcp/gcf-proxy

## What it does

gcf-proxy wraps any MCP server and rewrites what comes back. Structured JSON from a tool gets re-encoded as GCF; GCF that shows up inside tool call arguments gets decoded to JSON before forwarding. Nothing on either side has to change.

Two ways to run it. Locally over stdio, where `gcf-proxy` is the command and your server goes in the args. For a remote server, point `--upstream` at a Streamable HTTP endpoint. The `--http :9090` flag turns the proxy itself into an HTTP service with a `/health` check.

Three flags do the heavy lifting: `--session` for dedup of symbols already sent, `--cache` for repeated identical calls, `--delta` for responses that shift a little. Responses under 100 bytes are left alone. On open-weight models, `--no-flatten` keeps nested objects expanded, since that form reads better there.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add gcf-proxy -- npx -y @blackwell-systems/gcf-proxy
```

### Codex

**Platform CLI**
```bash
codex mcp add gcf-proxy -- npx -y @blackwell-systems/gcf-proxy
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "gcf-proxy": {
            "command": "npx",
            "args": [
                "-y",
                "@blackwell-systems/gcf-proxy"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "gcf-proxy": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@blackwell-systems/gcf-proxy"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add gcf-proxy npx -y @blackwell-systems/gcf-proxy
```

## When to use it
- shrink the JSON an MCP server dumps into context
- add compression to a third-party server you cannot edit
- proxy a remote MCP server over HTTP
- watch per-call token savings in stderr logs
- keep nested objects readable for models that struggle with flat encoding

## Example prompts
- Wrap the memory MCP server with gcf-proxy and show me the savings
- Run `gcf-proxy --verbose uvx yfinance-mcp` and report how many tokens were saved
- Connect gcf-proxy to a remote server with `--upstream http://host:3000/mcp`

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md