MCP Context Budget

Know what your MCP tools cost before they fill the window.

MCP Context Budget connects to your MCP servers, reads their tool definitions, and ranks every tool by how many context tokens it consumes — name, description, and input schema. Use it before enabling a server, when an agent feels slow, or in CI to keep tool bloat out of your setup.

Sister project of TokenSaver MCP: TokenSaver cuts tokens on the way out, Context Budget cuts them on the way in.

Product requirements: PRD.md · PRD.id.md (Bahasa Indonesia)

Why

Every MCP tool ships its name, description, and JSON schema into the model's context on every request. A handful of verbose servers can quietly consume tens of thousands of tokens — and with many clients still paying per token, that is money and attention spent before the first user message. This tool makes the cost visible and rankable.

Related MCP server: mcp-schema-bloat-fixer

Quick start

Audit a single server command with no config file:

npx -y mcp-context-budget probe -- npx -y @modelcontextprotocol/server-filesystem .

Audit every server in an MCP client config:

npx -y mcp-context-budget scan --config ./mcp.json

mcp.json uses the familiar Claude Desktop shape:

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "..." } }
  }
}

Example output

$ mcp-context-budget probe -- node tests/fixtures/echo-server.mjs

MCP Context Budget — 1 server(s) | 3 tools | ~1,383 tokens (0.7% of 200,000)

echo-fixture  3 tools  ~1,383 tokens (0.7%)
  ! big                          ~ 1,311 tokens  (name 1, description 808, schema 502)
    echo                         ~    48 tokens  (name 1, description 7, schema 40)
    tiny                         ~    24 tokens  (name 1, description 1, schema 22)

! tools above the 800 token threshold
token counts are estimated at four characters per token

One oversized description can cost more than 2% of a working context window on its own — this is what the tool surfaces.

What counts

Totals are compared against your context window (--context, default 200,000) and a per-tool threshold (--threshold, default 800). Token counts are estimated at four characters per token so the audit stays fully offline and deterministic.

Commands

Options: --context <tokens>, --threshold <n>, --timeout <ms>, --json, --soft.

Exit codes: 0 ok, 1 a tool crossed the threshold or a server failed to connect, 2 usage error. Use --soft to always exit 0 — handy while exploring.

Use it as an MCP tool

Agents can budget their own tools if you add the server:

{
  "mcpServers": {
    "contextbudget": {
      "command": "npx",
      "args": ["-y", "mcp-context-budget", "serve"]
    }
  }
}

The audit_context tool accepts either config (a path) or command + args and returns the ranked report.

CI usage

- name: Audit MCP context budget
  run: npx -y mcp-context-budget scan --config ./mcp.json --threshold 1500

The job fails when any tool exceeds the threshold or a configured server cannot start.

Supported configs

scan understands mcpServers, servers, or a bare map of server entries with command, args, env, and cwd. Only stdio servers are supported in v0.1.0; HTTP/SSE support is on the roadmap.

Development

npm install
npm run typecheck
npm run build
npm test

The suite covers config parsing, costing math, stdio probing (including timeouts and missing binaries), CLI behavior, and exit codes.

Roadmap

• Optional exact tokenizer mode per model family.

• HTTP/SSE server support.

• Baseline snapshots and diffing so budget regressions show up in review.

• Per-project budgets with allowlists.

License

MIT — see LICENSE.