Skip to main content
OPEN SOURCE · MIT

mcp-context-budget

Measure and enforce MCP tool-surface budgets before your coding agent starts.

Open source (MIT) · Local-first · Dependency-free core · CI-enforceable.

View on GitHub (opens in a new tab)Read the v0.4.0 release notes (opens in a new tab)

Watch scan, select and enforce

Download the demo video
Recorded CLI output from v0.4.0 using the bundled synthetic fixture and estimated schema tokens. Edited replay with synthetic narration based on Dan's voice. These counts are not a provider benchmark.
Read the transcript

Your MCP tool list can crowd the context before an agent starts. This is MCP context budget, a local tool for measuring and enforcing that surface. I'm using the package's bundled synthetic fixture: five servers and one hundred twenty tools. These are estimated schema tokens, not a provider benchmark. For issue triage, select keeps five relevant tools under a six thousand token cap. The selected schemas total two thousand nine hundred thirty four estimated tokens. The selected lock passes. The original full catalog fails the same cap and returns a nonzero exit code, so CI can stop the regression. Install from PyPI, try the bundled demo, then scan your own tools. The source and quickstart are linked below.

The problem

MCP servers quietly inflate an agent's tool surface — many tools, thousands of tokens of schemas — bloating context, slowing runs, and raising cost before the agent does any real work, with no static way to see or cap it.

A local-first CLI that scans your MCP config, measures the token budget each server and tool adds, selects a lean task-relevant tool set, and enforces the budget in CI — failing the build when the surface exceeds budget. No runtime service, no proxy, nothing leaves your machine.

Demo

A scan measures the surface, select trims it under budget, the result is written to a lockfile, and check fails the build when the surface regresses past the cap.

terminal
# 1. Measure the current MCP tool surface
mcp-context-budget scan --tool-list tools.json --lock-out mcp-budget.lock.json
CATALOG_SERVERS=5   CATALOG_TOOLS=120
SCHEMA_TOKENS=18,420   RESPONSE_TOKENS=9,310
 
# 2. Select a lean task-relevant tool set under budget
mcp-context-budget select --tool-list tools.json \
  --task "triage a GitHub issue" --max-tools 8 \
  --max-schema-tokens 6000 --out-lock mcp-budget.lock.json
SELECTED_TOOLS=8   AFTER_SCHEMA_TOKENS=5,740
wrote mcp-budget.lock.json
 
# 3. Enforce the budget in CI
mcp-context-budget check --lock mcp-budget.lock.json \
  --max-schema-tokens 6000 --max-response-tokens 4000
BUDGET_STATUS=PASS
 
# ...later, someone adds three more MCP servers. CI re-runs check:
SCHEMA_TOKENS=7,980 exceeds --max-schema-tokens 6000
BUDGET_STATUS=FAIL  (exit 1 — build blocked)

Quickstart

Install from PyPI, from source, or run the Docker image. The core CLI has no external runtime dependency.

Install from PyPIRequires Python 3.11+
pip install mcp-context-budget
Install from sourceRequires Python 3.11+
git clone https://github.com/OrionArchitekton/mcp-context-budget
cd mcp-context-budget
python3.11 -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
Prove the spine (no config required)
mcp-context-budget demo \
  --task "triage a GitHub issue and update one ticket" \
  --max-tools 8 \
  --max-schema-tokens 6000 \
  --max-response-tokens 4000
Or run it via Docker
docker build -t mcp-context-budget:local .
docker run --rm mcp-context-budget:local demo \
  --task "triage a GitHub issue" \
  --max-tools 8 --max-schema-tokens 6000 --max-response-tokens 4000

Command surface

scan
Estimate schema and response-token cost from an MCP config or tools/list fixture; emit a report and a lockfile.
select
Pick a smaller task-relevant tool set with deterministic SQLite FTS5/BM25 ranking, under max-tools and max-schema-tokens.
semantic-select
Rank tools by embedding similarity (deterministic fixture mode, or optional local Ollama) before applying the budget caps.
check
Re-validate a lockfile against schema and response budgets — the CI gate that fails the build on a regression.
compress-responses
Deterministically compress recorded response fixtures under a response budget, with before/after proof.
config-apply
Turn a selected-tool lock into a safe local MCP config patch — dry-run by default, write requires --write and makes a backup.
config-audit
Read-only hygiene check that flags plaintext secrets in MCP config files without ever printing the values.
export
Export the budget result (e.g. SARIF) for code-scanning and CI surfacing.

Why it is different

Local-first

No runtime service, no proxy, no hosted dashboard. The CLI runs on your machine and nothing leaves it. Semantic ranking can optionally call a local Ollama — only when you explicitly ask for it.

Dependency-free core

The core package ships with zero Python dependencies. It scans, measures, selects, and enforces using the standard library — easy to vendor, audit, and trust in a build pipeline.

CI-enforceable

A lockfile plus a check command turns "our context is bloated" into a build gate. The check exits non-zero when the schema or response budget regresses, so the surface stops growing silently.

Honest, never a false PASS

config-apply binds each lock to its config by fingerprint and reports PARTIAL (not a fake PASS) when a command-discovered server cannot be statically enforced. Secret audits redact values; reports never print literal secrets.