Refract

Cuts up to 98% of the tokens your AI agents spend using MCP tools — without losing anything.

What it actually changes

Fewer tokens sent = lower API bills, faster responses. And nothing is lost. Every check confirmed tools stay 100% usable after compression.

Reproduce these numbers yourself — every input is a static fixture in the repo, tokens counted with tiktoken cl100k_base:

python benchmarks/run_benchmark.py            # the table above
python benchmarks/run_benchmark.py --json     # machine-readable
python benchmarks/run_benchmark.py --fixture path/to/your_schemas.json

Related MCP server: Bifrost-MCP Gateway

Install

One-liner (macOS / Linux) — installs the package and configures Claude Desktop:

curl -sSL https://raw.githubusercontent.com/LoudiliMed/Refract/main/install-refract.sh | sh

Piping a script from the internet into your shell deserves a quick look first: inspect install-refract.sh on GitHub. It never uses sudo.

Or with pip directly:

pip install refract-mcp

Optional extras:

pip install refract-mcp[semantic]   # semantic tool routing with embeddings
pip install refract-mcp[multilang]  # JavaScript, TypeScript, JSX, TSX support

Two modes

Mode 1 — MCP Proxy

Sits between your agent and any MCP server. Compresses tool schemas on the fly so your agent does not load the full catalogue on every request.

Local subprocess (stdio):

refract-proxy --target "npx @modelcontextprotocol/server-filesystem /tmp" --verbose

Remote HTTP/SSE server:

# --url implies SSE transport (explicit, recommended for remote endpoints)
refract-proxy --url https://my-mcp-server.com/sse

# or with --transport flag (auto-detection can be overridden)
refract-proxy --target https://my-mcp-server.com/sse --transport sse

Proxy flags:

Add it to Claude Desktop:

{
  "mcpServers": {
    "my-server-via-refract": {
      "command": "/path/to/refract-proxy",
      "args": [
        "--target",
        "npx @modelcontextprotocol/server-filesystem /path/to/folder",
        "--verbose"
      ]
    }
  }
}

For a remote MCP server (SSE):

{
  "mcpServers": {
    "remote-via-refract": {
      "command": "/path/to/refract-proxy",
      "args": ["--url", "https://my-mcp-server.com/sse"]
    }
  }
}

refract-wrap-all — wrap every server at once

Instead of editing entries one by one (or running refract-install per server), refract-wrap-all rewrites all stdio servers in claude_desktop_config.json to go through refract-proxy in a single command:

# Preview what would change — writes nothing
refract-wrap-all --dry-run

# Wrap every stdio server not already going through refract
refract-wrap-all

# Restore the original commands
refract-wrap-all --unwrap

Example: this entry

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {"MY_VAR": "1"}
    }
  }
}

becomes

{
  "mcpServers": {
    "filesystem": {
      "command": "/path/to/refract-proxy",
      "args": ["--stdio-cmd", "npx @modelcontextprotocol/server-filesystem /tmp"],
      "env": {"MY_VAR": "1"}
    }
  }
}

Guarantees:

• A backup of the config is taken before every write (claude_desktop_config.json.bak, then .bak2, .bak3… — an existing backup is never overwritten).

• env, cwd and any other server fields are preserved.

• Servers already going through refract-proxy or refract-server are skipped (already wrapped).

• Remote SSE/HTTP servers (url entries) are skipped — only stdio servers are wrapped.

• --unwrap is an exact round-trip: wrap then unwrap restores every original command, args and fields.

Transports supported by refract-proxy

Both sse and http require an HTTP(S) URL in --target.

# Connect to a remote MCP server via Streamable HTTP (recommended)
refract-proxy --target "https://my-mcp-server.com/mcp" --transport http

# Connect via SSE (legacy)
refract-proxy --target "https://my-mcp-server.com/sse" --transport sse

# Local subprocess (auto-detected, --transport stdio optional)
refract-proxy --target "npx @modelcontextprotocol/server-filesystem /tmp"

Mode 2 — MCP Server

Exposes your codebase as an MCP server. Your agent can index a repo, get compressed file context, expand specific functions, analyze impact, detect breaking changes, and map security risks.

refract-server --root /path/to/your/repo

Add it to Claude Desktop:

{
  "mcpServers": {
    "refract-code": {
      "command": "/path/to/refract-server",
      "args": ["--root", "/path/to/your/repo"]
    }
  }
}

How it works, no jargon

Imagine a library with 50 books.

Without Refract: your agent gets a detailed summary of all 50 books on every question, even if the answer only needs one of them.

With Refract: your agent first gets a list of titles (the index). Once it knows which book it needs, it only receives that book's content.

Technically:

The index (always sent): just tool names and a short description of each.

The detail (sent only when needed): the full description of the tool actually used, everything required to use it correctly, nothing more.

The verification: after every compression, Refract automatically checks that nothing important was removed. If there is any doubt, it sends the full version instead of taking a risk.

No AI model is involved in this process. It is fully automatic, fast, and deterministic.

MCP Proxy tools

MCP Server tools

Repository health check

refract-status --root /path/to/repo
refract-status --root /path/to/repo --json

Shows: files per language, raw vs compressed tokens, functions/classes indexed, dangerous calls by category, languages without tree-sitter support.

blast_radius

Ask Claude which functions break if you change a target function.

Example result:

{
  "target": "authenticate",
  "direct_callers": ["login_user"],
  "all_impacted": ["login_user", "verify_session", "admin_access"],
  "impacted_count": 3,
  "risk_level": "MEDIUM"
}

Risk levels: LOW (0 to 2 impacted), MEDIUM (3 to 5), HIGH (6 or more).

semantic_diff

Detects breaking API changes by comparing function interfaces, not bodies. Use it as a CI gate.

Example result:

{
  "breaking": ["authenticate"],
  "body_only": ["logout"],
  "added": ["new_function"],
  "removed": [],
  "unchanged": ["hash_password"],
  "is_breaking": true
}

If is_breaking is true, the PR changes the public API and must be reviewed.

security_surface

Maps every function that calls dangerous primitives across your repo.

HIGH risk: subprocess, os.system, eval, exec, pickle, ctypes

MEDIUM risk: open (write mode), socket, requests, httpx, urllib

Example result:

{
  "high_risk": [
    {
      "file": "src/llm_client.py",
      "function": "run_command",
      "calls": ["subprocess.run"]
    }
  ],
  "summary": {
    "high_risk_count": 1,
    "medium_risk_count": 3,
    "total_functions_scanned": 87,
    "clean_files": 8
  }
}

Languages supported

Python (via ast module), JavaScript, TypeScript, JSX, TSX (via tree-sitter, opt-in with pip install refract-mcp[multilang]).

Language is auto-detected from file extension. Graceful fallback if tree-sitter is not installed.

Built-in Anthropic caching

Refract integrates with Anthropic prompt caching. as_anthropic_tools() automatically marks the compressed catalogue as cacheable, cutting costs further on repeated requests.

Example over 30 days, 100 requests per day, 5,000 tokens of schemas:

Troubleshooting

"Failed to spawn process: No such file or directory" in Claude Desktop

Claude Desktop cannot find refract-proxy in its PATH. Find the absolute path and use it directly:

which refract-proxy

Then use the full path in claude_desktop_config.json:

{
  "mcpServers": {
    "my-tool-via-refract": {
      "command": "/full/path/to/refract-proxy",
      "args": [
        "--target",
        "npx @modelcontextprotocol/server-filesystem /path/to/folder"
      ]
    }
  }
}

Works with

Claude Desktop, Cursor, any client that follows the MCP standard, any existing MCP server.

License

MIT — free to use, including commercially.