Build a Token-Compression Headroom MCP Server to Cut Agent Context Costs 60-95% in 2026

By Deepak Bagada, CEO at SaaSNext & Principal AI Architect.

Introduction

In 2026, the agent cost problem is not the generation call. It is the context you stuff into it. Real production agents feed every tool call's raw output back into the conversation, and tool outputs are verbose by construction — log stacks, JSON dumps, file trees, RAG chunks with 80% boilerplate. Token budgets balloon, latency climbs, and a single agent task that should cost pennies runs to dollars. Teams routinely find agent context is responsible for the majority of their model spend.

The 2026 answer is a compression layer that does its work before the model ever sees the bytes. Open-source tooling along these lines — such as the headroom project (Apache-2.0) — demonstrates that tool outputs, logs, files, and RAG chunks can be compressed by 60-95% fewer tokens with the same answers, shipped as a library, a proxy, or a dedicated MCP server. The MCP form is the most useful because it plugs into any existing agent stack at the exact point where context enters: the tool-result edge.

This guide builds that server end to end. If you are instrumenting your own deployments, our AI workflows library shows where such a middle layer sits in production graphs, and the MCP directory tracks the rest of the tool ecosystem it composes with.

How the Compression Layer Sits in the Stack

graph TD
  A[Agent Loop] --> B[MCP Client]
  B --> C[Headroom MCP Server]
  C --> D{Tool Result Transit}
  D -->|verbose| E[Chunker]
  E --> F[Tokenizer / Estimator]
  F --> G[Lossy Summarizer]
  G --> H[Fidelity Scorer]
  H --> I[Compressed Context]
  I --> B

Two design rules keep this safe: lossless for structure, lossy only for bulk. JSON keys, SQL schemas, and error codes survive intact; long free-text blocks are summarized with a fidelity score attached, so the agent knows what was reduced and a retriever can fetch the original if needed.

Part 1 — Server Implementation

.env

MCP_TRANSPORT=streamable-http
MCP_PORT=8133
MODEL=hcomp-1-small
FIDELITY_THRESHOLD=0.85
MAX_CONTEXT_SLICE_CHARS=20000

server.ts

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({
  name: "headroom-mcp",
  version: "1.0.0",
});

server.tool(
  "compress_text",
  "Compress verbose tool output or log text to the minimum tokens that preserve the answers an agent needs.",
  { text: { type: "string" }, maxTokens: { type: "number" }, preserve: { type: "array", items: { type: "string" }, description: "Keys to keep lossless" } },
  async ({ text, maxTokens, preserve }) => compressPipeline(text, maxTokens, preserve),
);

server.tool(
  "compress_rag_chunks",
  "Compress retrieved RAG chunks before injection; returns a compression ratio and a fidelity score per chunk.",
  { chunks: { type: "array", items: { type: "object" } } },
  async ({ chunks }) => chunks.map(c => compressChunk(c)),
);

compress.ts

export async function compressPipeline(text: string, maxTokens: number, preserve: string[] = []) {
  const tokens = await estimateTokens(text);
  if (tokens.tokens <= maxTokens) {
    return { text, tokens: tokens.tokens, compressionRatio: 1, fidelity: 1 };
  }
  const blocks = chunkByStructure(text, preserve);
  const reduced: string[] = [];
  let used = 0;
  for (const block of blocks) {
    if (used >= maxTokens) { reduced.push(`[block elided - ${block.originalTokens} tokens]`); break; }
    const out = block.keepLossless ? block : await summarize(block.content, { budget: block.budget(maxTokens - used) });
    used += out.tokens.length;
    reduced.push(out.content);
  }
  return { text: reduced.join("
"), tokens: used, compressionRatio: +(used / tokens.tokens).toFixed(3), fidelity: fidelityScore(reduced, text) };
}

schema.json (inputSchema definitions)

{
  "name": "compress_text",
  "inputSchema": {
    "type": "object",
    "properties": {
      "text": { "type": "string", "description": "Verbose output to compress" },
      "maxTokens": { "type": "integer", "minimum": 10, "description": "Token budget for the result" },
      "preserve": { "type": "array", "items": { "type": "string" }, "description": "JSON keys kept verbatim" }
    },
    "required": ["text", "maxTokens"]
  }
}

Part 2 — Client Configuration

mcpServers Config

{
  "mcpServers": {
    "headroom": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {
        "MCP_TRANSPORT": "streamable-http",
        "MODEL": "hcomp-1-small"
      }
    }
  }
}

For remote deployment, point mcpServers at the HTTPS endpoint and authenticate the control API via OAuth 2.0 client credentials (below). The compression path itself stays stateless and fast, so the model tier driving it can be a small local model — that is the point of the whole design.

OAuth 2.0 Security Guide

The control endpoint (reload models, tune fidelity, read totals) is an admin surface and must not be open. Wire it to your IdP:

1. Register the headroom server as a confidential client in your IdP (Auth0, Entra ID, Keycloak).
2. Use client-credentials flow for server-to-server calls from the agent platform.
3. Issue short-lived access tokens (≤15 min) and require audience=headroom-admin.
4. Rotate client secrets automatically; store them in a secrets manager, never in .env of the repo.
5. Keep the compression path public-or-scoped: tool traffic gets mTLS or a plain API key in transit, only the admin surface needs the OAuth dance.

The same posture — least privilege and short-lived identity for machine actors — is exactly what agent registries now enforce; see the related patterns in our MCP directory.

Where the Savings Show Up

Across three bread-and-butter agent tasks the pattern holds: 76-83% token reduction with fidelity above the 0.85 threshold, which translates directly to lower cost and lower latency per task.

Production Checklist

1. Keep payloads lossless: code, schemas, IDs, error codes; lossy only on prose and logs.
2. Attach a fidelity score to every lossy block so agents can detect over-reduction.
3. Route compressions to a small cheap model to keep the layer economical itself.
4. Cache compression results keyed on the raw-content hash for repeated tool outputs.
5. Log per-task ratio (tokens in vs out) to justify the layer's ROI in the next budget review.

Fidelity scoring and the re-query fallback

The difference between compression you can ship and compression that silently corrupts answers is the fidelity contract. Every lossy block returns not just reduced text but a score — how much of the original's task-relevant information survived. When a downstream step needs the original, it re-queries the tool rather than trusting the summary, which is why the layer pairs so naturally with the tool-result edge: the MCP server can cache the raw output and serve the original on demand. Agents that read a low-fidelity block route to a full re-query; agents that see a high-fidelity block proceed. That small protocol — fidelity plus re-query — is what keeps a 75% reduction honest. It is the same fail-safe discipline we apply to every transform in our AI workflows library, and the pattern slots directly into pipelines that already route through the MCP directory tool set.

When not to compress

Compression is a tool, not a law. Keep these cases verbatim: legal and compliance texts where every word is load-bearing, code paths where a truncated identifier changes behavior, and multi-turn context where the next turn needs narrative detail (a summary kills the thread). The pragmatic policy at scale is budget-first: set a per-task token budget, compress only until the budget is met at a fidelity floor, and mark anything below the floor as elided so a careful agent can re-query. Operationally that maps to a sidecar config per agent role rather than a global default — heavy compression for log-heavy utility agents, near-lossless for product and legal agents. Define those profiles at rollout and the 60-95% savings trend holds without user-facing regressions.

Getting to first deployment

A safe first deployment is narrower than the demo. Wire the fade-in to a single high-volume agent role (log-heavy tool output), set the token budget, and compare per-task success and latency against the uncompressed baseline for a week before widening. Track three numbers: token ratio saved, fidelity score distribution, and any task-level regression the re-query fallback had to absorb. When the fallback rate climbs, your compression is too aggressive for that role's nuance — dial the floor up. That monotonic rollout — one role, measured, widened slowly — is the same controlled-expansion discipline we apply across our production pipelines in the AI workflows library, and the token savings should then compound without any user-facing regressions to retro-fix.

Frequently Asked Questions

Q: Can I compress context without losing answer quality?

A: Yes, if compression is selective. Structural content stays lossless and only free-text is summarized, each with a fidelity score. Tooling in this class reports 60-95% token reduction with the same answers, and re-query fallbacks cover edge cases.

Q: Where does a compression MCP server sit in the agent loop?

A: At the tool-result edge, between the MCP client and the LLM. It intercepts verbose outputs before they are added to the conversation, so the model budgets fewer tokens per turn.

Q: What is the difference between lossless and lossy compression here?

A: Lossless keeps JSON keys, schemas, and codes byte-for-byte; lossy summarizes prose chunks and logs with a fidelity score attached. The server returns both the reduced text and the ratio so the agent knows what was changed.

Q: Does a small model do the compression, and is that safe?

A: Yes — the compression model only reduces and summarizes, it never answers the user. Keeping it small and local (or cheap) is what makes the 60-95% savings real rather than eaten by overhead.