Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@distill-mcp-v2 distill these server logs keeping stack traces"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
distill-mcp-v2 is a high-performance, network-dependency-free Python FastMCP server designed to aggressively optimize Large Language Model (LLM) context windows. It provides specialized tools for compressing and analyzing massive AI‑agent payloads without losing critical semantic information.
By filtering noise, stabilizing cache prefixes, and running multi-model token cost estimations locally, Distill v2 dramatically reduces API costs and preserves LLM reasoning abilities when dealing with heavy payloads like infinite logs, monolithic API schemas, and multi-agent war room transcripts.
Related MCP server: Headroom Mini
Our rigorous, independent stress-testing benchmarks (audited via pytest and chaos blueprints) prove that distill-mcp-v2 achieves up to 99.7% token compression while retaining 100% of the crucial context.
Scenario | Payload Profile | Raw Tokens | Distilled Tokens | Savings % |
Trace Avalanche | Heavy Java Stacktraces | 150,027 | 546 | 99.6% |
Schema Monolith | Massive Microservice JSON | 56,588 | 1,355 | 97.6% |
Incident War Room | Multi-Agent Chat Logs | 117,952 | 371 | 99.7% |
(Tested against Claude-3-Opus budgets. Scenario 1 reduced costs from $2.25/call to $0.008/call.)
Read the full Benchmark & Execution Report for deeper insights.
Distill v2 exposes 8 precise tools to agents via the Model Context Protocol:
distill_json — Compresses raw JSON payloads, retaining anomalies, exceptions, and errors.
distill_logs — Compresses raw .log files, preserving head/tail contexts and stack traces.
distill_schema — Compacts massive MCP tool catalogs and JSON schemas to structural parameters.
distill_response — Progressively prunes, minifies, and truncates outputs to fit strict token budgets.
distill_conversation — Extracts goals, decisions, blockers, and actions from multi-agent transcripts without leaking raw ISO timestamps.
stabilize_for_cache — Maps chaotic raw identifiers (UUIDs, hex IDs) to sequential placeholders to stabilize LLM prompt caching.
analyze_tokens — Accurately estimates token counts using tiktoken (cl100k_base).
compare — Computes detailed diffs and cost-savings analyses between raw and distilled payloads.
Distill v2 requires Python 3.10+. We recommend using uv or pip in an isolated virtual environment.
# Clone the repository
git clone https://github.com/yatinkoul/distill.git
cd distill
# Create a virtual environment and activate it
python -m venv .venv
source .venv/bin/activate
# Install dependencies
pip install -e .Run the FastMCP server, which natively binds to a stateless HTTP endpoint.
# Run the FastMCP server (default host: 0.0.0.0, port: 8000)
distill --host 0.0.0.0 --port 8000
# Or using uvicorn directly:
.venv/bin/uvicorn src.main:app --host 0.0.0.0 --port 8000The server exposes a JSON‑RPC endpoint at http://localhost:8000/mcp.
The repository ships with an exhaustive stress-test runner that dynamically allocates ports, executes deterministic payload scenarios, and validates the integrity of the distilled outputs.
To run the complete test suite (118/118 passing):
# Install development dependencies
pip install -e ".[dev]"
# Run the test suite
pytestTo manually execute the stress-testing blueprints and regenerate the benchmark report:
python stress_tests_blueprints/run_blueprints.pyProject Goals & Strategy – High-level strategy and milestones.
Benchmark Report – Exhaustive stress-test results.
Testing Infrastructure – Notes on the testing architecture and CI/CD readiness.
Contributions, issues, and feature requests are welcome!
Please read our CONTRIBUTING.md (coming soon) for guidelines on how to propose improvements. Ensure all tests and linting (ruff) pass before submitting pull requests.
This project is licensed under the MIT License – see the LICENSE file for details.
Count tokens using model-aware tokenizers and estimate API costs across multiple configured models.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| model | No | gpt-4o |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states counting tokens and estimating costs, which implies a read-only operation, but lacks details on output format, error handling, or side effects. The description is adequate but not rich in behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core action and efficiently adds 'estimate API costs' without waste. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description is too brief. It does not explain return values, cost calculation basis, or behavior with invalid model names. More context is needed for a tool with these characteristics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate. It hints that 'model' selects a tokenizer (model-aware) and 'text' is input, but does not explain parameter values, defaults, or the meaning of 'multiple configured models'. This is insufficient for full understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Count tokens' and the resource 'tokens', with additional context of 'model-aware tokenizers' and 'estimate API costs'. It distinguishes from sibling tools (distill, compare, stabilize) which focus on different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for token counting and cost estimation but provides no explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, but the sibling tools list offers context of different functionalities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate comparison metrics (token count reduction, compression ratio, cost savings) between uncompressed and distilled text formats.
| Name | Required | Description | Default |
|---|---|---|---|
| original | Yes | ||
| distilled | Yes | ||
| model | No | gpt-4o |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description does not disclose whether the tool is read-only, destructive, requires authentication, or has rate limits. It only states the input and outputs, leaving behavioral gaps for an AI agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that captures the core functionality without any extraneous content. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists the metrics returned, which is helpful given no output schema. However, it fails to mention the model parameter or differentiate from sibling tools like stabilize_for_cache. The completeness is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain the purpose of any parameters (original, distilled, model). The term 'uncompressed and distilled text formats' loosely maps to original and distilled, but model is entirely unaddressed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates comparison metrics (token count reduction, compression ratio, cost savings) between uncompressed and distilled text formats. It uses specific verbs and resources, and aligns with sibling tools that focus on distillation processes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when having uncompressed and distilled texts to compare, but provides no explicit guidance on when to use this tool versus alternatives like analyze_tokens or the distill_* tools. No when-not or prerequisuties are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract a high-level briefing (goals, decisions, errors, current state, pending tasks) from a conversational message trace (JSON array or raw text) to fit within a token budget.
| Name | Required | Description | Default |
|---|---|---|---|
| conversation | Yes | ||
| format | No | structured | |
| token_budget | No | ||
| focus | No | all |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the input format (JSON array or raw text) and the extraction of specific elements, but does not mention permissions, rate limits, or whether the operation is read-only or modifies data. For a transformation tool, it provides moderate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently communicates the main purpose, input type, output components, and constraint. It is front-loaded and avoids unnecessary words, though it could be slightly more structured (e.g., listing components).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no output schema, and no annotations, the description covers the input type and output components but lacks details on parameter options (format, focus), error handling, or output format. It is adequate but not comprehensive for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate. It mentions the conversation input, format default 'structured', token_budget default 1000, and focus default 'all', but does not explain what 'format' or 'focus' mean or how they affect output. The description adds overall purpose but leaves parameter semantics vague.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Extract' and the resource 'conversational message trace', specifies the output components (goals, decisions, errors, current state, pending tasks), and mentions the token budget constraint. It distinguishes the tool from siblings like distill_json and distill_logs by focusing on conversational data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for conversation data but does not explicitly state when to use this tool versus alternatives like distill_json for JSON or distill_logs for log data. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compress JSON structures by collapsing large arrays and metadata while preserving error fields. Supports iterative budget-based compression.
| Name | Required | Description | Default |
|---|---|---|---|
| json_data | Yes | ||
| preserve_keys | No | ||
| collapse_keys | No | ||
| max_array_samples | No | ||
| max_depth | No | ||
| token_budget | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions iterative budget-based compression and preservation of error fields, but does not disclose side effects, idempotency, or behavior on edge cases. Since annotations are absent, the description carries full burden and is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at two sentences and front-loaded with the primary action. However, it could be slightly more structured with details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters and no output schema or annotations, the description is insufficient to guide correct usage. It omits return format, error handling, and parameter explanations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fails to explain any of the 6 parameters (json_data, preserve_keys, etc.), leaving the agent without meaningful guidance on how to populate them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (compress) on a specific resource (JSON structures), and distinguishes from sibling tools that target other data types like conversation or logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like distill_conversation or distill_logs, nor any context about prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Filter and compress raw logs by preserving startup context, shutdown state, and matching error traces while omitting large blocks of repetitive status messages.
| Name | Required | Description | Default |
|---|---|---|---|
| log_text | Yes | ||
| keep_head | No | ||
| keep_tail | No | ||
| error_patterns | No | ||
| dedup | No | ||
| token_budget | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially discloses behavior by mentioning what is preserved (startup, shutdown, errors). However, it does not specify if the tool mutates the input, requires permissions, or what happens to omitted content beyond 'omitting'. More detail on side effects would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence (22 words) that front-loads the action. It is efficient, though it omits many details that could be included without becoming overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters (including complex ones like error_patterns array and token_budget) and no output schema, the description is insufficient. It does not explain the compression algorithm, return format, or how parameters interact, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does not explain any parameter meanings; parameters like keep_head, keep_tail, error_patterns, dedup, and token_budget are only inferable from their names. The description lacks any parameter-specific guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it filters and compresses raw logs by preserving startup, shutdown, and error content while omitting repetitive messages. This distinct purpose differentiates it from sibling tools like distill_conversation or distill_json, which handle different data types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for log compression, but does not explicitly state when to use this tool versus alternatives like distill_conversation. There are no usage exclusions or alternative tool mentions, leaving the agent to infer appropriate contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Progressively compress any generic tool response (JSON, HTML, or text) to fit within a specific token budget.
| Name | Required | Description | Default |
|---|---|---|---|
| response_data | Yes | ||
| token_budget | Yes | ||
| content_type | No | auto | |
| preserve_keys | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full behavioral disclosure. It mentions 'progressively compress' but fails to specify behavioral traits such as what data is destroyed, how compression works, or any side effects. The description is too vague for safe autonomous invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and to the point. Every word adds value; there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description is insufficiently complete. It does not explain the 'progressively compress' mechanism, behavior with different content types, or the role of preserve_keys. An agent cannot fully understand the tool's operation from this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no parameter details. It does not explain response_data, token_budget, content_type, or preserve_keys beyond what the parameter names imply. The description should compensate for the missing schema descriptions but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: compressing generic tool responses (JSON, HTML, text) to fit a token budget. The verb 'compress' and resource 'generic tool response' are specific, and the mention of 'generic' hints at distinction from specialized siblings like distill_json, though not explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives like distill_json or distill_logs. It implies usage for any generic response needing token budget fitting but lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reduce token overhead of MCP tool schemas or JSON Schemas. Strips descriptions/examples (compact mode) or collapses to parameter names/types (minimal mode).
| Name | Required | Description | Default |
|---|---|---|---|
| schema | Yes | ||
| mode | No | compact | |
| keep_required | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the two different modes and their effects, which provides adequate transparency. However, it does not mention what the output format looks like or any error conditions, leaving some gaps given the absence of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two efficient sentences that front-load the purpose and then detail the modes. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, no output schema), the description is moderately complete. It covers the primary functionality but omits details on output and error handling that would be helpful for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the 'mode' parameter in terms of its effects (compact vs minimal) but does not clarify the 'keep_required' parameter or the expected format for the 'schema' input string. With 0% parameter description coverage, more detail is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: reducing token overhead of schemas. It specifies two modes (compact and minimal) and what each does, making the action unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to reduce schema size) but does not provide explicit guidance on when not to use it or how it compares to sibling tools like distill_json or distill_conversation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Normalize dynamic elements like UUIDs, timestamps, and hex IDs to sequential placeholders, maximizing provider-level prompt caching hit rates.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| stabilize_uuids | No | ||
| stabilize_timestamps | No | ||
| stabilize_hex_ids | No | ||
| custom_patterns | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must convey behavior. It explains normalization to 'sequential placeholders' but does not disclose whether the transformation is reversible, if the original text is modified, or any side effects. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that front-loads the purpose with no filler. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters and no output schema, the description is too brief. It omits details about the placeholder format, behavior of custom patterns, and whether the output is just the modified text or includes metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description only mentions types of dynamic elements without linking to the parameters. The boolean parameters and custom_patterns are not explained, leaving the agent to infer from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'normalize', the resource 'dynamic elements like UUIDs, timestamps, and hex IDs', and the goal 'maximizing provider-level prompt caching hit rates', distinguishing it from sibling tools like distill_* and analyze_tokens.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for improving caching but does not explicitly state when to use or not use this tool, nor offers alternatives. The context of cache optimization is implicit but not sufficient for clear decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0analyze_tokenscomparedistill_conversationdistill_jsondistill_logsdistill_responsedistill_schemastabilize_for_cacheScored across 8 tools
Each tool targets a specific input type or operation: token analysis, comparison, distillation for conversations/JSON/logs/responses/schemas, and cache stabilization. No two tools have overlapping purposes.
Most tools follow a consistent verb_noun pattern (e.g., distill_conversation, distill_json). The tool 'compare' is a verb-only exception, but it is still clear and fits the domain.
With 8 tools, the server covers token analysis, multiple distillation formats, comparison metrics, and cache optimization. This is well-scoped for the stated purpose without being excessive or insufficient.
The tool surface provides comprehensive coverage for the domain of token optimization and compression: cost estimation, multi-format distillation, schema reduction, and caching normalization. No obvious gaps are evident.
MCP server for building and testing AI agents with multi-model experimentation and insights.
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
InfoLang semantic memory MCP — investigate, memorize, and recall compressed agent context.
LLM Orchestration Agent (Mcp)
