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

• ccusage on PATH

• sqlite3 on PATH for optional Codex thread titles

Build and test

npm install
npm test
npm run typecheck
npm run build

Run the built stdio server:

node dist/index.js

Inspect it without registering it in a live client:

npx @modelcontextprotocol/inspector node dist/index.js

Registration 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.