Mcp Distill

mcp-distill

[](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/)

Field projection layer for MCP tools. Reduce LLM context window usage by letting agents request only the fields they need.

The Problem

MCP tools often return large JSON responses. When an agent only needs a few fields, the full response wastes precious context window tokens.

Without mcp-distill (1,157 tokens):
{"id": "123", "name": "Item", "description": "...(2000 chars)...", "metadata": {...}, "content": "...(10000 chars)..."}

With mcp-distill (23 tokens):
{"id": "123", "name": "Item"}

Installation

pip install git+https://github.com/shoegazerstella/mcp-distill.git

Or with uv:

uv add git+https://github.com/shoegazerstella/mcp-distill.git

Quick Start

from fastmcp import FastMCP
from mcp_distill import projectable

mcp = FastMCP("my-server")

@mcp.tool
@projectable(fields=["id", "name", "metadata.created_by"])
def get_resource(resource_id: str) -> dict:
    """Fetch a resource by ID."""
    return {
        "id": resource_id,
        "name": "Example Resource",
        "description": "A" * 2000,      # Large field - not advertised
        "metadata": {
            "created_by": "admin",
            "huge_audit_log": [...],    # Large field - not advertised
        },
        "content": "B" * 10000,         # Large field - not advertised
    }

How It Works

1. You advertise available fields

The `fields` parameter in `@projectable()` tells the agent what fields it can request:

@projectable(fields=["id", "name", "metadata.created_by"])

2. The agent sees them in the tool description

Tool: get_resource
Description: Fetch a resource by ID.

Projectable fields: id, name, metadata.created_by

Parameters:
  - resource_id: string (required)
  - _fields: ar