mcp-usage: specs

Constants at the top of mcp_usage.py: DAYS=7, ROOT="~/.claude/projects", CLAUDE_JSON="~/.claude.json", CHARS_PER_TOKEN=4, IMAGE_TOKENS=1500, PREFIX="mcp__".

M-name: server and tool

Claude Code names MCP tools mcp__<server>__<tool>, where <server> is the configured name with every char outside [A-Za-z0-9_-] replaced by _ (claude.ai Gmail -> claude_ai_Gmail). Split at the first __ after the prefix. Config and attachment names are normalized the same way so they join. Pitfall: a server name containing __ splits wrong; the same server under two names counts twice.

M-scan: what is read

Every *.jsonl under the root (subagent transcripts included, under their parent sessionId) whose mtime is at or after since, lines with timestamp >= since (since = now - --days). A tool_use block is one call, keyed by its id (repeated lines collapse). Its tool_result (same tool_use_id) gives size and error (is_error: true). A call with no result counts with result size 0 and no error. Unparseable lines are skipped.

M-size: tokens

input_tokens_est = ceil(len(JSON of input) / CHARS_PER_TOKEN); result_tokens_est = same over the result text (string, or the sum of text blocks; IMAGE_TOKENS per image block; other blocks as JSON). Counted once per call, though the result stays in context for every later turn of the session (real cost is higher and grows with session length).

M-agg: records

One record per server (kind: "server", tool: null) and per called tool (kind: "tool"): calls, errors, token estimates, sessions (distinct session ids), first/last call (UTC). context_share = (input + result tokens) / the same sum over all tool calls in the window, MCP and built-in, so it reads as "share of tool context this server took". Sorted by server, server record first.

M-config: configured servers

From CLAUDE_JSON: top-level mcpServers keys, each projects.<path>.mcpServers key, and <path>/.mcp.json mcpServers keys; disabledMcpServers and disabledMcpjsonServers names. config on server records: disabled if disabled in any project, else enabled if configured anywhere, else none (claude.ai connectors and plugins called but not in these files). Only names are read; values (commands, URLs, env, headers) never leave the function.

M-loaded: available in a session

Servers named in mcp_instructions_delta.addedNames or as mcp__ names in deferred_tools_delta.addedNames attachments; loaded_sessions = sessions where that happened. Servers whose tools sit in the system prompt (not deferred) and send no instructions leave no trace, so this undercounts.

M-unused

never_called = server record with 0 calls in the window: configured or loaded, costing tool definitions in context, never used (flag "configured but never used" in ../mcp-usage.md).

M-ex: worked example (../tests/test_mcp_usage.py, ../tests/fixtures/mcp_usage/)

since 2026-10-01. Session s1: t0 mcp__gh__search on Sep 30 (dropped); t1 mcp__gh__search input 4 tok, result 400 chars = 100 tok; t2 mcp__gh__get_issue input 2, result 10, is_error; t3 Bash input 5, result 20; attachments load docs server and gh. Subagent of s2: t4 mcp__claude_ai_Docs__read input 1, one image result = 1500. Total tool context 1642. gh: 2 calls, 1 error, 116 tok, share 0.070646, config enabled, loaded 1. claude_ai_Docs: share 0.914129, config none. docs_server (project config, loaded), unused-db (project .mcp.json) and claude_ai_Gmail (disabled) never called.