mcp-weight

Weigh your MCP stack. Finds the MCP configs on your machine, connects to every configured server, and reports how many context tokens their tool schemas cost — per tool, per server, per client, with provenance.

Status: published to npm — the version badge below is the single source of truth. Honest frontier: ROADMAP.md.

Why

Every MCP server injects its tool definitions (name + description + JSON schema) into context on every turn — before the user types anything. Four config files across three apps later, nobody knows what the stack costs.

Related work exists and is credited in SPEC.md §4: context-tax (per-use, Claude Code), tooltax (server leaderboard), mcp-tax (Claude configs), mcp-diet (config profiles). mcp-weight's angle: cross-client measurement with provenance, snapshots, and no fake precision.

Quick start

npx mcp-weight scan        # pretty report
npx mcp-weight scan --json # machine-readable

From source:

npm install && npm run build
node dist/src/cli.js scan

Point it at specific files instead of auto-discovery:

npx mcp-weight scan --config ~/.cursor/mcp.json --config ./opencode.jsonc

What a report looks like

Example report (a real scan on the author's machine: one Cursor config, one OpenCode config; perplexica-local was down — exactly the partial-result path). The CLI's header also prints its version (kept out of this sample so it never goes stale):

mcp-weight — MCP context weight report
Tokenizer: cl100k_base (proxy tokenizer: comparable across servers, not provider-native (up to ~15% off))
Scanned: 2026-10-05T20:36:29.374Z · window basis: 200,000 tokens

CLIENT    SERVER             TOOLS  TOKENS  ~TOKENS  STATUS
--------  -----------------  -----  ------  -------  ------
cursor    perplexica-local       -       -        -  error
cursor    memvid                 7   1,414   ~1,659  ok
cursor    home-agent-memory      2     184     ~213  ok
opencode  perplexica            11   1,312   ~1,468  ok

Total: 20 tools · 2,910 tokens (1.5% of window) · 4 servers (3 ok, 1 failed, 0 disabled)

! cursor/perplexica-local: error — MCP error -32000: Connection closed

--verbose adds a per-tool breakdown (e.g. memvid's create_memory_bank alone is 493 tokens).

What is measured

• Tool name + description + inputSchema JSON, tokenized with cl100k_base (labeled proxy) plus a chars/4 estimate.
• Per-server totals and share of a 200k-token window (configurable display).
• Provenance on every row: client, config path, transport, server version.
• Failures are per-row error / timeout — a broken server never aborts the scan.
• Secrets: env/header values are never printed; only keys.

Snapshot + diff (CI gate)

mcp-weight scan --out baseline.json         # commit this once
mcp-weight scan --out current.json
mcp-weight diff baseline.json current.json --fail-over 2000   # exit 2 if total grows > 2000 tokens

In a workflow:

- run: npm ci && npm run build
- run: node dist/src/cli.js scan --config .cursor/mcp.json --out current.json
- run: node dist/src/cli.js diff baseline.json current.json --fail-over 2000

--fail-over is absolute tokens; --fail-percent is a percentage. With neither flag, diff reports and exits 0.

Per-use accounting

mcp-weight usage transcript.jsonl                            # per-tool call counts
mcp-weight usage transcript.jsonl --format claude-code       # force a dialect
mcp-weight usage transcript.jsonl --scan-report scan.json    # + schema-token weight
mcp-weight usage transcript.jsonl --json                     # machine-readable

The transcript is a JSONL file where each line is a JSON object with a type field. Tool calls come from assistant messages in either dialect — OpenAI-style message.tool_calls[] or Claude Code-style message.content[] blocks with type: "tool_use" — auto-detected unless --format forces one. Calls carrying an id are counted once. Malformed lines (bad JSON, non-objects, missing type) are skipped with an error entry; the command never aborts. See USAGE-TRANSCRIPT-FORMAT.md.

Clients scanned

| Client | Config paths | | --- | --- | | Cursor | ~/.cursor/mcp.json, ./.cursor/mcp.json | | Claude Code | ~/.claude.json, ./.mcp.json | | Claude Desktop | %APPDATA%\Claude\claude_desktop_config.json (platform paths) | | OpenCode | ~/.config/opencode/opencode.jsonc, ./opencode.jsonc | | VS Code | %APPDATA%\Code\User\mcp.json, ./.vscode/mcp.json | | Codex | ~/.codex/config.toml, ./.codex/config.toml (TOML) | | Any (explicit) | --config <path> (JSON/JSONC/TOML auto-detected) |

Project configs are discovered from the working directory up to the git root; user-level configs are always checked.

Remote (HTTP) servers are probed as Streamable HTTP and then legacy SSE. Auth failures, missing commands, and unreachable servers get an actionable hint on the row instead of aborting the scan.

Documentation (reading order)

1. SPEC.md — source of truth: problem, scope, success criteria.
2. ROADMAP.md — ladder and current frontier.
3. ARCHITECTURE.md — design, as-built truth, limits.
4. PROJECT_CONTEXT.md — map, environment, glossary.
5. DECISIONS.md — ADR log.
6. AGENTS.md — session contract for agents (also good for humans).
7. CURRENT_STATE.md — live snapshot and session ledger.
8. docs/RELEASING.md — release process (trusted publishing / staged publish).

Research context

mcp-weight is the measurement instrument for the MCP token tax experiment in Context Lab, which studies how coding agents spend and conserve context. Sibling project: living-state-machine (prior memory research). Tools stay standalone; the lab links them.

License

MIT.