Token Guardian MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Token Guardian MCP show me my token usage for the last 7 days, broken down by agent and model"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Token Guardian MCP
Token Guardian is a local, read-only MCP server for finding Claude Code and Codex token waste without making either client dumber.
It does two jobs:
Reports which agents, models, and sessions are processing the most tokens.
Recommends the cheapest safe model and effort level for a specific task.
It also includes a dry-run route-task command for testing prompt-first routing before the MCP is registered anywhere.
Hard safety boundary
Token Guardian cannot change model settings, effort levels, context limits, compaction, MCP registration, or running sessions. It has no model credentials and makes no paid API calls.
The usage tool calls ccusage with --offline and --no-cost. Codex titles are optional metadata read through sqlite3 -readonly. Every MCP tool is marked read-only, non-destructive, idempotent, and closed-world.
Related MCP server: token-pilot
Tools
token_guardian_usage_snapshot
Reads one through thirty days of local usage and returns:
Totals by agent and model
Cache-read, output, and frontier-model shares
Largest sessions
Exact duplicate Codex work titles
Evidence-backed quick wins
Processed tokens are a workload diagnostic. They are not the same as a subscription meter, especially when cached input dominates.
token_guardian_recommend_route
Accepts the client, task, risk, and current context size. It returns a model, effort level, reasons, and an optional frontier validator.
The policy fails closed. Security, architecture, production, destructive, high-risk, critical, or ambiguous work stays on a frontier model. Cheap models handle bounded mechanical work. Balanced models handle normal coding and debugging, with a frontier review when needed.
Test prompt-first routing
Build the project, then run the router from any folder:
node ./dist/route-cli.js --client codex --prompt "Implement a bounded TypeScript parser with tests." --cwd .The working folder does not need to be a repository. The router primarily uses the prompt. It checks up to 256 names in the current folder for optional project markers, without opening file contents or scanning subfolders.
The command only prints a recommendation and a session-scoped launch command. It does not run that command, change configuration, register the MCP, or touch an active session. Vague continuation prompts such as yeah, test that stay on the frontier route because their real context is missing.
Local requirements
Node.js 24 or newer
ccusageon PATHsqlite3on PATH for optional Codex thread titles
Build and test
npm install
npm test
npm run typecheck
npm run buildRun the built stdio server:
node dist/index.jsInspect it without registering it in a live client:
npx @modelcontextprotocol/inspector node dist/index.jsRegistration status
This first build is intentionally not registered with Claude, Codex, or the shared Kitsune gateway. Registration and any client restart are a separate change after the isolated server is accepted.
License
MIT. See LICENSE.
Available Tools
2 toolstoken_guardian_recommend_routeRecommend Model RouteARead-onlyIdempotent
Recommend a conservative Claude, Codex, or local model and effort for one task. Returns advice only and never switches the active client.
Inputs: client (required), task_summary (required), risk, task_kind, +3 more. Returns: tier, model, client, effort, +5 more
token_guardian_usage_snapshotToken Usage SnapshotARead-onlyIdempotent
Read local Claude Code and Codex usage, identify large contexts and expensive routing, and return evidence-backed quick wins. Never changes settings or sessions.
Inputs: days, agent, top_sessions. Returns: caveat, totals, window, byAgent, +5 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
Each tool serves a distinct, non-overlapping purpose: one provides a usage snapshot with improvement suggestions, the other recommends a routing choice for a task. There is no ambiguity between them.
Both tool names follow a consistent 'token_guardian_<verb>_<noun>' pattern using snake_case, with descriptive verbs ('usage_snapshot', 'recommend_route') that clearly indicate their function.
With only 2 tools, the server feels minimal for a domain that might benefit from additional diagnostics (e.g., cost breakdown, model listing) or configuration advice. The count is on the low end of acceptable for a focused utility.
The server explicitly avoids any action tools, being read-only. It covers snapshot analysis and routing recommendations but lacks tools for detailed queries (e.g., by time period, by model) or applying any changes, leaving notable gaps for hands-on usage optimization.
Maintenance
Related MCP Connectors
LLM cost optimization gateway, repo token-waste auditor & model arbitrage MCP server.
Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Veqen brings together work and coding agent costs per person and team, product inference costs per customer, agent spending, protection incidents, invoice checks, chargeback and the month-end close. Ask your assistant to investigate recorded spending, compare model prices, review provider keys and incidents, record bills and credits, or manage budgets, alerts, teams and spending policies. Your account role and plan govern access. Provider-key shut-off and agent-card controls require the appropriate role and provider permissions. Destructive actions require confirmation, and organizations can require a second person to approve a shut-off. SDK budget blocking is not a guaranteed spending cap. Work and coding agents are free for up to 3 people; product inference is free up to $1,000 in monthly AI spend. Connect your Veqen account for private organization data. The separate public model-price server needs no account. Estimates remain separate from provider invoices. Setup and permissions: https://veqen-app.com/docs/mcp
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that helps AI agents reduce token usage by compressing, summarizing, and managing conversation/context data more efficiently.11MIT
- AlicenseAqualityBmaintenanceMCP server that reduces token consumption in AI coding assistants by up to 90% via structural reads, PreToolUse hooks, and tp-\* subagents.25481 npm5MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that analyzes AI agent session logs to find token waste and optimization opportunities.19 npmMIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that reduces token usage by lazily loading skills and tools only when needed, and routing repetitive subtasks to ML backends instead of the LLM.Apache 2.0