MCP ConfigsMay 14, 2026·2 min read

Headroom — Context Compression + MCP for Agents

Local context optimization layer: proxy/wrap/CCR + MCP tools to compress logs/files/RAG for agents; verified 1742★, pushed 2026-05-14.

Agent Toolkit
Agent Toolkit · Community
Agent ready

This asset can be read and installed directly by agents

TokRepo exposes a universal CLI command, install contract, metadata JSON, adapter-aware plan, and raw content links so agents can judge fit, risk, and next actions.

Native · 94/100Policy: allow
Agent surface
Any MCP/CLI agent
Kind
Mcp
Install
Pip|Npm
Trust
Trust: Established
Entrypoint
pip install "headroom-ai[all]" && headroom wrap claude
Universal CLI install command
npx tokrepo install 274eb518-e8b5-52ac-a2be-88acde3b1164
install contractmetadata JSONadapter planraw content
Intro

Local context optimization layer: proxy/wrap/CCR + MCP tools to compress logs/files/RAG for agents; verified 1742★, pushed 2026-05-14.

Best for: Agent-heavy teams hitting context limits on logs, tool output, and long histories

Works with: Python/Node apps, OpenAI-compatible clients via proxy, and MCP clients via Headroom MCP tools (per README)

Setup time: 8-20 minutes

Key facts (verified)

  • GitHub: 1742 stars · 158 forks · pushed 2026-05-14.
  • License: Apache-2.0 · owner avatar + repo URL verified via GitHub API.
  • README-backed entrypoint: pip install "headroom-ai[all]" && headroom wrap claude.

Main

  • Start with wrap mode: headroom wrap claude|codex|cursor gives quick wins without rewriting your app stack.

  • Use proxy mode for language-agnostic pipelines: point any OpenAI-compatible client at the proxy and keep data local (per README).

  • Treat CCR as reversible: README emphasizes originals are retrievable, so you can compress aggressively without losing auditability.

  • Measure savings: capture before/after token counts (README demo shows 10,144 → 1,260) and tune only where it matters.

Source-backed notes

  • README lists three usage modes: library, proxy (headroom proxy), and agent wrap (headroom wrap ...).
  • README states it provides an MCP server with tools like headroom_compress/headroom_retrieve/headroom_stats.
  • README demo includes a concrete token reduction example (10,144 → 1,260) and describes CCR as reversible.

FAQ

  • Do I need to change my app?: Not necessarily — start with headroom wrap ... or run headroom proxy as a drop-in endpoint.
  • Is compression reversible?: README says CCR keeps originals; the agent can retrieve raw content on demand.
  • How do MCP clients use it?: Install/enable the Headroom MCP server (README mentions MCP-native entrypoints) and call compress/retrieve tools.
🙏

Source & Thanks

Source: https://github.com/chopratejas/headroom > License: Apache-2.0 > GitHub stars: 1742 · forks: 158

Discussion

Sign in to join the discussion.
No comments yet. Be the first to share your thoughts.

Related Assets

lean-ctx — Context Runtime (MCP + Shell Hook)

lean-ctx is a local-first context runtime (MCP + shell hook) that compresses file reads and CLI output to cut token waste for coding agents.

MCP Configs
MCP Hub

dbt-mcp — dbt Context MCP Server for Agents

Give AI agents structured access to dbt project context and tools (SQL, semantic layer, docs search). Ships an experimental MCP bundle in releases.

MCP Configs
MCP Hub

Figma Context MCP — Design-to-Code for AI Agents

MCP server that gives AI coding agents access to Figma design context. Provides layout, styles, and component info so agents like Cursor and Claude Code can generate pixel-perfect code. 14K+ stars.

MCP Configs
MCP Hub

Apify MCP Server — 8,000+ Web Scrapers for Agents

Apify MCP Server connects agents to Apify Actors via a hosted endpoint (mcp.apify.com) or local run, turning thousands of web scrapers into callable tools.

MCP Configs
MCP Hub
◈Home🔍Search👤Me