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 <server>_<tool> 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 <absolute path to loom.config.json>.

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