CtxSlim

Your MCP servers are eating your context. Put them on a diet.

One config entry. Every MCP server you already have. A fraction of the context.

Every MCP server you connect dumps its entire tool catalog into your LLM's context — every name, every description, every JSON Schema property. Connect a database server, a browser server and a GitHub server and you can burn 30,000+ tokens before you've asked a single question. Your responses get slower, your bill gets bigger, and your agent gets dumber because it's drowning in tool definitions it doesn't need.

CtxSlim is a proxy that fixes this. It sits between your MCP client and your servers, exposes only the tools that matter for the current task, and compresses the schemas of what it does expose — with zero API keys, zero cloud calls, zero config rewriting.

📊 Measured savings

Real numbers from the bundled benchmark (npm run bench), measured through actual MCP transports — not marketing math:

The more servers you stack, the more Slim saves. And that's with modest schemas — real-world servers (GitHub, Notion, browser automation) ship far heavier definitions.

⚡ Quick start

Option 1 — the one-liner. Let CtxSlim wire itself into your client:

npx -y ctxslim init                # shows what it found on your machine
npx -y ctxslim init --client cursor --yes   # writes it (with a backup first)

Option 2 — manual. Replace your stack of MCP server entries with a single one:

{
  "mcpServers": {
    "ctxslim": {
      "command": "npx",
      "args": ["-y", "ctxslim"]
    }
  }
}

That's it. CtxSlim auto-discovers the servers already configured in your existing client config (read-only — your files are never modified) and connects to all of them itself.

Works with:

• Claude Desktop · Claude Code · Cursor · Windsurf · VS Code

• Or point it at any config explicitly: npx -y ctxslim --config /path/to/mcp.json

• Or drop a ctxslim.json in your project directory

{
  "mcpServers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
    "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"] }
  },
  "slim": {
    "mode": "auto",
    "maxTools": 24
  }
}

🧠 How it works

flowchart LR
    C[MCP Client<br/>Claude · Cursor · Codex] <--> S[CtxSlim<br/>stdio proxy]
    S <--> A[Server A<br/>files]
    S <--> B[Server B<br/>database]
    S <--> D[Server D<br/>browser]
    style S fill:#16a34a,stroke:#14532d,color:#fff

1. On connection, Slim aggregates every upstream server behind one surface.

2. In auto mode it exposes only the top-K most relevant tools, plus a search_tools meta-tool your agent uses to pull in anything else on demand — progressive disclosure instead of a 40-tool firehose.

3. Exposed schemas are compressed: boilerplate keywords stripped, descriptions trimmed to a budget, unused $defs dropped — measured with a chars/4 token estimator and reported back to you.

4. Tool calls are routed transparently to the right upstream server. Your agent can't tell the difference — except its context is lighter.

Your agent gets four superpowers:

🎛 Modes

🛠 CLI

ctxslim                       start the proxy
ctxslim init                  wire the proxy into a detected client config
                              (--client <name|path>, --yes to write, backup included)
ctxslim --config <path>       use a specific config
ctxslim --mode <mode>         auto | manual | off
ctxslim --max-tools <n>       override top-K (default 24)
ctxslim --no-stats            don't persist session stats
ctxslim --quiet               minimal logging
ctxslim stats                 show lifetime savings
ctxslim doctor                validate config + connectivity

Session stats live in ~/.ctxslim/stats.jsonl. Run ctxslim stats after a week of work and watch the cumulative savings.

🔒 Privacy

CtxSlim is 100% local. No API keys. No telemetry. No network calls except to the MCP servers you configure. Your tool definitions never leave your machine. The optional stats file stays on your disk and never leaves it.

❓ FAQ

Does my agent really find tools that aren't exposed? Yes — that's what search_tools is for. Modern agents call it when a task needs something outside the exposed set, get the full compressed schema back, and call the tool. Even if a model skips search and calls a known-but-hidden tool by name, Slim routes it anyway. Nothing is ever hard-blocked.

Why not just install fewer servers? Because you installed them for a reason. The problem isn't having tools — it's paying for all of them in every single prompt.

What about tool-name collisions? If two servers expose the same tool name, Slim prefixes them (server__tool) and routes correctly.

Does it work with HTTP servers? Yes — url entries are proxied via Streamable HTTP alongside stdio servers.

Where are the tests? 43 of them, covering the compressor, the ranking engine, config discovery and a full integration suite that speaks real MCP over real transports. npm test.

🤝 Contributing

Contributions are genuinely welcome — see CONTRIBUTING.md for the how and the why. The codebase is small, strict and comment-free on purpose; it's a nice one to read.

⭐ Star history

If CtxSlim saved you tokens, a star helps other developers find it:

License

MIT © 2026