Distil — Claude Code MCP server: compress tool output
Folds tool output into reversible handles and hands back the exact original bytes when asked. Useful when agent context and bills keep growing.
claude mcp add distil -- uvx distil-llmWhat Distil does
Distil takes what your tools return, drops the bulk and leaves a handle the agent can trade back for the original through the distil_expand tool. Compression is lossless by default, and the folded bytes stay in a local store. The design keeps the provider's prompt cache intact: bytes still cached are never rewritten, older context shifts only once that cache has expired.
It also tells you what the saving is worth. distil savings reports it from your own traffic, distil audit replays a capped sample as a named compressor would shape it and says helped, hurt or too early to tell. Shadow mode replays requests against both the plain and the compressed context; if harm goes past the budget, the proxy stays lossless-only.
Launch goes through uvx, so uv has to be on the machine. Agent coverage comes from the distil wrap -- <agent> wrapper, with presets named for claude, codex, gemini, copilot and others. On short coding tasks the published comparison does not show a cost win over no compression at all, so expect the savings figure to depend on the task.
What it helps with
- shrink tool output while keeping the original data
- pull the exact original back mid-task
- see the actual saving on your own traffic
- check whether compression changed the agent's next step
- compare compressors by dollars per solved task
Example prompts for the agent
- Compress this command's output and leave a handle I can pull back with
distil_expand - Run
distil savingsand show me what it saved on my requests - Check with
distil audit --compressor anthropic-context-editingwhether it helped or hurt
How to install Distil
Platform CLI
claude mcp add distil -- uvx distil-llmuvx runs the command named after the package; if the README names another one, use uvx --from distil-llm <command>
Platform CLI
codex mcp add distil -- uvx distil-llmuvx runs the command named after the package; if the README names another one, use uvx --from distil-llm <command>
Config file
{
"mcpServers": {
"distil": {
"command": "uvx",
"args": [
"distil-llm"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from distil-llm <command>
Config file
{
"servers": {
"distil": {
"type": "stdio",
"command": "uvx",
"args": [
"distil-llm"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from distil-llm <command>
Platform CLI
gemini mcp add distil uvx distil-llmuvx runs the command named after the package; if the README names another one, use uvx --from distil-llm <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Distil
How do I install Distil in Claude Code?
Run claude mcp add distil -- uvx distil-llm. That registers the server with Claude through uvx.
What does Distil do?
It compresses tool output into recoverable handles kept in a local store and gives the agent a distil_expand tool to get the exact bytes back. It also measures the savings and whether compression changed agent behaviour.
What do I need to run it?
The install command goes through uvx, so uv must be present. To route an agent, use the distil wrap -- <agent> wrapper with its presets.
