Summary
If you're burning 40-72% of your context window on MCP tool definitions before writing a single line of code, this helps you find the waste. It audits token costs per tool using character approximation, recommends minimal tool sets based on task descriptions, and compresses verbose JSON schemas at three aggression levels. The analyze_session_usage tool tracks which tools actually get called versus just loaded, and suggest_removals scores candidates for removal based on usage patterns. The get_optimization_report combines everything into a health check with an executive summary. Helpful when you're hitting context limits or want to understand what's consuming tokens before user work begins.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
token-lens-mcp
MCP server for analyzing and optimizing context window token usage. MCP tool definitions consume 40-72% of context windows before any user work begins — this server helps you measure, compress, and eliminate that waste.
Install
npx token-lens-mcp
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"token-lens": {
"command": "npx",
"args": ["token-lens-mcp"]
}
}
}
Claude Code
claude mcp add token-lens -- npx token-lens-mcp
Tools
audit_context_budget
Analyze the token cost of your MCP tool definitions. Estimates tokens per tool using chars/4 approximation on the full JSON definition.
Params:
tools— Array of{name, description, schema}objects
Returns: Per-tool token cost (sorted by cost), total tokens, percentage of 128K/200K/1M context windows.
optimize_tool_loading
Given a task description, recommend the minimal set of tools needed. Uses keyword matching and category relevance scoring.
Params:
task_description— What you're trying to accomplishavailable_tools— Array of{name, description, category?}
Returns: Recommended tools sorted by relevance, excluded tools, estimated tokens saved.
compress_schema
Compress verbose tool schemas to reduce token usage.
Params:
tool_name— Name of the toolschema— JSON Schema object to compresslevel—"light"|"medium"|"aggressive"
Levels:
- light — Remove descriptions under 20 chars
- medium — Shorten descriptions to 50 chars, remove examples
- aggressive — Strip all descriptions, keep only types and required fields
Returns: Compressed schema, original/compressed token counts, savings percentage.
analyze_session_usage
Track which tools are actually called vs loaded during a session.
Params:
session_id— Unique session identifieraction—"register_tool"|"log_call"|"report"tool_name— Tool name (required for register_tool/log_call)tool_tokens— Token cost (for register_tool, default 50)
Report returns: Loaded vs used counts, waste percentage, unused tools ranked by token cost.
suggest_removals
Identify tools that can be safely removed based on usage patterns.
Params:
usage_history— Array of{tool_name, call_count, last_used_days_ago}
Scoring: never_used (priority 3) > not_used_30_days (priority 2) > rarely_used (priority 1)
Returns: Removal candidates with reasons and estimated token savings.
get_optimization_report
Full context window health check combining audit, removal suggestions, and compression recommendations.
Params:
tools— Array of tool definitionsusage_history— Optional usage history array
Returns: Executive summary with health grade (excellent/good/fair/poor), audit results, removal suggestions, compression opportunities, and actionable recommendations.
Resources
token-lens://tips
Best practices guide for reducing MCP context window bloat, including schema design tips, token budget guidelines, and dynamic tool loading strategies.
Development
npm install
npm test
npm run dev # watch mode
License
MIT
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →