MCP Loom

   ███╗   ███╗ ██████╗██████╗       ██╗      ██████╗  ██████╗ ███╗   ███╗

████╗ ████║██╔════╝██╔══██╗ ██║ ██╔═══██╗██╔═══██╗████╗ ████║ ██╔████╔██║██║ ██████╔╝█████╗██║ ██║ ██║██║ ██║██╔████╔██║ ██║╚██╔╝██║██║ ██╔═══╝ ╚════╝██║ ██║ ██║██║ ██║██║╚██╔╝██║ ██║ ╚═╝ ██║╚██████╗██║ ███████╗╚██████╔╝╚██████╔╝██║ ╚═╝ ██║ ╚═╝ ╚═╝ ╚═════╝╚═╝ ╚══════╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝

The context loom for MCP.

One proxy in front of N servers. Oversized tool results are woven into queryable datasets — 48k tokens in, 2k envelope out.

warp: results stream in weft: the loom shuttles across ══════════════════════ ═════════════════════════════

│ │ │ │ │ │ │ │ 48,377 tokens ┄┄┄┄┄┄┄┄┄> ✂ intercept ●━━━━┿━━━━┿━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ │ ●━━━━┿━━━━┿━━━━━━━ ingest → DuckDB ━━━━━━┫ │ │ ●━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫ │ │ │ ●━━━━ schema · stats · joins ━━┛ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ [ raw floods, dropped ] [ 2,104-token envelope ] ref · sample · SQL

What it does

An MCP client asks a tool a question, and the answer comes back as a ten-thousand-row JSON dump — most of which the model didn't need but now has to hold in context. Loom sits in the middle.

When a result is small, it passes through untouched. When a result is large and tabular, Loom ingests it into an embedded DuckDB and hands the model a compact envelope instead: a dataset ref, the schema, column stats, a few sample rows, join hints, and provenance. The model then queries precisely what it needs — including joins across data from *different* servers, which no single server can answer alone.

The economics: a 48k-token tool result becomes a ~2k-token envelope. The model spends its context on answers, not raw dumps.

When loom helps — and when it won't

Loom earns its place in three situations that cover the ordinary case of real MCP usage:

• Clients with no shell. Claude Desktop, mobile, and agent platforms — the largest client surfaces — have no CLI to fall back to. MCP tools are the model's only path to the data, so interception engages by construction.
• Servers with no model-reachable CLI. Internal tools, SaaS connectors, and credentialed databases whose secrets live only in the server's env block — the bulk of real connectors. There is no gh-equivalent for the model to route around.
• Auditable analysis over persistent datasets. Loom turns "the model eyeballed a dump" into "the model ran verifiable queries over data you can still inspect" — exact SQL over provenance-stamped datasets that stay reopenable and re-queryable after the fact. This one applies *everywhere*, shell or no shell, and is the honest answer to "why route through loom at all."

Cross-server joins run through all three: no single CLI answers a question spanning two services' data.

Two boundaries, stated plainly:

• A shell-bearing agent will skip the MCP layer for a service it can reach directly. Give a model bash and a service with a known CLI and ambient credentials — gh against GitHub is the sharpest case — and it goes straight to the CLI, faster and cheaper, skipping loom and MCP both. That is the agent preferring a CLI to MCP, not a loom defect; loom is an MCP-layer product and will not beat gh at being gh. It is also the minority case: most servers wrap things with no model-reachable CLI, and the largest client surfaces have no shell.
• Envelope fidelity is bounded by what the downstream returns. Loom flattens faithfully what a server sends — but it cannot add fields the server never sent. The GitHub MCP server, for instance, returns a trimmed 17-field repo object (no stargazersCount, language, or forks); loom captured all 17 faithfully, and a star-ranking question was still unanswerable from that data. The bound is the downstream's, not loom's.

How it works

Loom is itself a stdio MCP server. It sits between one upstream MCP client (Claude Desktop, Claude Code, Cursor, etc.) and N downstream MCP servers that you configure:

• Spawns and supervises each configured downstream server (handshake health check, restart with backoff, delists tools and emits list_changed if a server exhausts its restart budget).
• Namespaces every downstream tool as _ and re-exposes the aggregated tool list upward, keeping it live via list_changed.
• Routes call_tool to the correct downstream child. Small results return unmodified — pass-through is byte-identical. Large tabular results are intercepted into DuckDB and replaced with a loom_dataset_ref envelope; any interception failure degrades to the untouched original.
• Exposes the synthetic query surface over cached datasets: loom_query (guarded read-only SQL, cross-server joins included), loom_list_datasets, loom_describe (full schema, stats, and fresh join hints for a dataset), loom_materialize (pin a derived query result as a new dataset), and loom_export (sealed csv/json export). Interception depth is capped at 1 per upstream call; loom_materialize does not consume that budget.
• Shuts down cleanly on signals or upward stdin EOF, with no orphaned child processes and the spill dir removed.

Loom intercepts both structured results and formatted text: when a result carries a structuredContent channel it ingests from that; otherwise it parses JSON-in-text, and failing that, extracts repeating records from formatted text under a strict never-lie bar (it never emits a table it isn't sure of — any uncertainty degrades to an untouched pass-through). See SPEC.md for the full normative specification.

Usage

npx mcp-loom --config loom.config.json

Point any MCP client at that command. Configuration can also be supplied via the LOOM_CONFIG environment variable instead of --config:

LOOM_CONFIG=/path/to/loom.config.json npx mcp-loom

(--config takes precedence if both are set.) See loom.config.example.json for a minimal working example.

Client recipes

Loom is launched by your MCP client the same way any stdio server is — point the client at npx -y mcp-loom --config .

Claude Desktop (claude_desktop_config.json):

{

"mcpServers": { "loom": { "command": "npx", "args": ["-y", "mcp-loom", "--config", "/absolute/path/to/loom.config.json"] } } }

Cursor (.cursor/mcp.json): the same mcpServers block as above.

Claude Code — add it from the CLI:

claude mcp add loom -- npx -y mcp-loom --config /absolute/path/to/loom.config.json

Use an absolute path to loom.config.json — MCP clients spawn servers with an unspecified working directory. Loom then spawns and namespaces the downstream servers listed in that config.

Config reference

Config is a single JSON file, validated with zod at startup; invalid config fails fast with a readable error listing every violated field.

If every configured server fails to start, Loom itself fails to start (fatal). If only some fail, Loom starts with a warning and the surviving servers' tools available.

Interception & querying

Large tabular tool results are intercepted and ingested into the embedded DuckDB store as queryable datasets. A tool result that exceeds tokenThreshold and carries structured data — read from the protocol's structuredContent channel when present, otherwise parsed from the text render — becomes a loom_dataset_ref envelope: a reference ID, the inferred schema, column statistics, sample rows, and join hints — keeping the token cost low. Query these datasets with the synthetic loom_query tool: it accepts read-only SQL in DuckDB dialect (single SELECT or WITH statement), classified read-only by the engine parser. If you lose a dataset reference, loom_list_datasets recovers it or lists all available datasets in the current session.

Dataset references are session-scoped: they exist only for the duration of your conversation and are automatically evicted under memory pressure (implicit query results are evicted first, preserving explicitly-ingested data longer). Sample rows in the envelope are arbitrary — DuckDB does not preserve insertion order by default — so always use an explicit ORDER BY clause when row order matters. The token estimator is a coarse magnitude dial and undercounts text containing CJK characters, so monitor actual token usage if you regularly cross tokenThreshold.

Inspecting datasets with loom_describe

Call loom_describe on a dataset ref to inspect its structure and contents in detail: full schema with per-column statistics, a 10-row sample, fresh join hints to other datasets (with value-overlap scores that rank real joins above coincidental name matches), provenance, and creation timestamp. Use this when you need to understand a dataset's shape before querying it, or to rediscover a dataset's schema after many intermediate operations.

Materializing query results with loom_materialize

Query results are cached implicitly, but if you want to keep a derived result across the session boundary or ensure it is never evicted, use `