I built mcp-footprint to see how large tool definitions are in a captured MCP catalog and which ones repeat across servers.
A tools/list response can include a full JSON schema for every tool. With several servers, it's hard to compare definition sizes or spot repeats in the raw JSON. mcp-footprint takes saved listings and turns them into byte counts and a local report.
What it reports
The CLI sorts object keys recursively before serialization. It counts the UTF-8 bytes in each complete canonical tool definition, then counts the canonical aggregate catalog. A proportional map shows definition bytes by server. Searchable rows let you open each captured definition. Cross-server comparisons identify exact definitions, same-name differences, and similar descriptions. A pair can have more than one label.
The estimate is ceil(catalogBytes / 4). It's a rough byte-based proxy, not tokenizer output or a measurement of client context use.
Try the demo
The demo uses bundled synthetic snapshots. It starts no server and makes no network request. The CLI needs Node.js 20 or newer and has no runtime dependencies.
npx --yes --package git+https://github.com/Arthur031221/mcp-footprint mcp-footprint --demo --html footprint.html
For real data, save a complete tools/list result or its JSON-RPC response as JSON. The CLI also accepts an aggregate object with a servers array, where each entry has a name and a tools array. Capture every page first. If the response contains a non-empty nextCursor, the tool refuses to treat it as a complete catalog.
node bin/mcp-footprint.js --input files=files-tools.json --input search=search-tools.json --html footprint.html --json footprint.json
Why save the input first
Saving the input makes measurements repeatable. The report describes the JSON you provide, not a live server state. Keep the snapshot beside a test run, compare it after a schema change, and inspect the generated HTML without granting the tool server access. The HTML embeds the captured descriptions and schemas, so review it before sharing.
This is a CLI and JavaScript library, not an MCP server. It doesn't call tools or recommend removing them. I'd like feedback on the snapshot formats and which report details are useful during catalog review.
Top comments (2)
Two report details I'd find useful. First, a "canonically equal, raw different" label between two captures of the same server. Sorting keys is right for comparing definitions, but provider prompt caches match raw bytes, so a server that emits the same schema with its keys in a different order on each launch looks identical in your report and can still break the cache every session. We keep a test that our server's tool list is byte-identical across launches for exactly that reason. Second, a calibration line for the bytes/4 estimate. One data point: our 19-tool default list is 25,756 bytes serialized compactly in the OpenAI tool shape and 5,970 tokens in tiktoken's o200k_base, about 4.3 bytes per token, so bytes/4 reads about 8% high there. Other tokenizers will land elsewhere.
thanks, both are useful suggestions. Today I compare canonical definitions only across different servers, so I do not report same-server changes between captures. I also parse the JSON before canonicalizing it, which means I cannot compare the original response bytes, including whitespace. I should make the comparison scope and byte source explicit if I add this, since stable serialized tool definitions and byte-identical response bodies are different checks. Your calibration is a helpful example: bytes/4 gives about 6,439 tokens for 25,756 bytes, roughly 8% above 5,970. A report line could show that comparison while making clear it is one tokenizer and one tool shape.