mcp-top

# mcp-top > mcp-top profiles your local MCP context footprint: what servers advertise, what may load into context, and which tools your agents actually use. License: MIT - Dependencies: none (Python stdlib, 3.11+) ## Install The PyPI package is available as of v0.5.0: ```sh uvx mcp-top ``` ```sh pipx install mcp-top ``` ```sh pip install mcp-top ``` Clone-and-run still works: ```sh python bin/mcp-top ``` You can also run the package module directly when `src` is on `PYTHONPATH`: ```sh PYTHONPATH=src python -m mcp_top ``` ## The Problem MCP servers accumulate. Their advertised tools can be large, but modern clients do not all load those definitions the same way. Ordinary spend dashboards show money rather than context composition. `mcp-top` shows the join that is usually missing: advertised MCP footprint, possible upfront context footprint, and actual local usage. ## Quickstart This real output is captured by the reproducible case study in [docs/examples/prune-case-study.md](docs/examples/prune-case-study.md): ```text Coverage: 2 transcripts found, 2 parsed, 0 skipped; 2 in window; 3 tool calls (2 MCP); server queries: 2 ok, 0 failed, 0 not queried recorded results: 2 paired, 0 partial, 0 unsupported, 0 unmeasurable, 0 unpaired result(s), 0 unpaired call(s) (recorded result footprint is a recorded-bytes lower bound) SERVER SCOPE TOOLS TOKEN RANGE REGIME CALLS(window) VERDICT ------------- ----- ----- ----------- ------- ------------- ------------------------------------------------------------ unused-server user 2 >=~23..~77 unknown 0 prune -> removes advertised up to ~77 / upfront at least ~23 used-server user 2 >=~22..~76 unknown 2 review used-server recorded result footprint: 37 recorded UTF-8 byte(s) (lower bound) -> ~10 tok (estimate) across 2 result(s) (max ~5, p90 ~5) used-server called tools: - first_tool: 1 - second_tool: 1 ``` Definition token counts use the ch…