Token Optimizer MCP: A Local Ledger for Agent Context, With a Knowledge Graph Attached

The context waste this targets, and the agent it assumes you run

The README frames the problem in four parts: re-reading files that have not changed, dumping an entire file to see three lines, running unbounded searches, and re-deriving conclusions from a previous session. Each of those is a token cost that recurs on every session, which is why the project measures per-session rather than per-request. The intended user is someone running a coding agent through one of the sixteen supported CLI clients, with Claude Code treated as the primary path. The README is explicit that installing the bare MCP server without the plugin gives the model tools it can ignore. Enforcement lives in the plugin, not in the server. If you are not on a client the project supports, most of the value described here does not reach you.

Denial as the mechanism, not a suggestion in the system prompt

The core mechanism is a hook that refuses the expensive call. According to the README, a built-in Read of a 200 KB file is denied, and the refusal names the cached, diffed replacement. The same treatment applies to Grep, Glob, Edit, Write, and shell invocations of cat, head, and grep -r. The README states there is no setting to turn this on, which means the enforcement is part of the plugin install rather than a config flag you flip later. The second mechanism is diffing: re-reading a file already read in the same session returns only a diff. The README calls this usually the single biggest win and notes that size-based rules cannot catch it, since a small file re-read repeatedly costs the same as a large one read once. That distinction matters when you compare this to a context-truncation tool that only looks at payload size.

The knowledge graph fills itself from work, and its cost is carried separately

Each project gets a graph with nodes for files, symbols, tasks, and findings, and edges typed derived_from, contains, supersedes, contradicts, and related. The README says it fills from real work with no ingestion job, no embedding model, no rebuild step, and no query to formulate. The example given is a touch on src/auth.ts pulling up a finding about clock skew, a decision about per-host retry budgets, a recorded dead end, and recent git history. The stated economics are about 150 tokens to carry a finding against 5k to 50k to re-derive it. The README does not claim that reuse has been proven: it reports 6,332 tokens of modeled graph-substitution potential, excluded from the verified headline, while the causal graph-reuse study remains marked Collecting. Treat the graph as a useful side effect of working, not as a measured saving you can budget against.

Install, the audit command, and what the numbers are allowed to include

For Claude Code the README gives three commands: /plugin marketplace add ooples/token-optimizer-mcp, /plugin install token-optimizer@token-optimizer, and /reload-plugins. After that, token_audit returns one ranked queue of what costs the most per session, with an optional monthly cost equivalent only after you configure your own effective rate. Node.js 22 or newer is the stated runtime requirement. The accounting contract is the part worth reading before you quote any figure. The dashboard separates net verified MCP transport savings from quarantined historical or tool-reported tokens, and the README describes the headline as 43,491 net verified tokens avoided, computed as 54,037 gross reduction minus a deliberate 10,546-token expansion. Records without a client identity stay explicitly unattributed rather than being assigned to whichever agent is open. See docs/TOKEN_ACCOUNTING.md for how uncached input, cache reads, cache writes, and output are priced, and why ambiguous model ids stay Not priced.

Where the measurement stops being a measurement

The honest boundary is drawn in the README itself. MCP progressive disclosure has a materialized before and actual-return measurement, with later expansions debited from the same net. Graph substitutions are modeled, and the randomized control arm for downstream graph effects is a separate thing that is not yet finished. The 486,074,740 quarantined tokens are dominated by repository scan volume that never entered model context, so that number describes scanning activity rather than savings. The dashboard also reports more than 1,000 hook runs with zero failures and zero timeouts across six active CLI clients in a rolling 24-hour window, which is an availability claim about the hook, not a token claim. If you need a single defensible number for a budget review, the net verified MCP transport figure is the only one the README presents as measured end to end.

When this is the wrong tool

Denial is a blunt instrument. If your workflow depends on reading a file in full after it changed outside the session, or on shell pipelines the hook does not model, the refusal becomes friction you have to work around. The README lists cat, head, and grep -r as covered shell patterns, which implies other invocations are not. The graph is per project and local, so a team cannot share findings across machines through this tool, and nothing in the README describes a sync or export path. The pricing layer reads native CLI usage receipts and keeps API list-price equivalents separate from provider-reported charges, and it never labels those equivalents as a subscription invoice. If you are looking for a hosted cache that many developers share, this is not that; the README states no account, no telemetry, no hosted service.

What a context-compression proxy does differently

A common alternative is a proxy or middleware that sits between the client and the model provider and compresses or truncates the request payload before it leaves the machine. That approach is transport-level and client-agnostic: it works with any tool that speaks the provider API, and it does not need per-client plugin support. The trade-off is that it sees text, not intent. It cannot know that a Read call targets a file already read this session, so it cannot return a diff instead of a body, and it cannot name the cached replacement in a refusal. Token Optimizer MCP works one layer up, inside the client's tool dispatch, which is why it can deny a specific call and why it needs a plugin per client. The two are not mutually exclusive, but they fail in different places: a proxy degrades gracefully by compressing, while a hook fails closed by refusing.

Maintenance surface and licence terms

The project is JavaScript, MIT licensed, with the README stating commercial use is allowed. Releases v6.0.0 through v6.0.2 landed within about two weeks in August 2026, and the last push recorded is 2026-09-10. That cadence means the install matrix and the accounting contract are both moving targets; pinning a version is reasonable if you depend on a specific dashboard figure. The sixteen-client support claim is the largest ongoing maintenance cost the project carries, since each client integration can break independently of the core server. MIT places few obligations on you beyond preserving the licence notice, and nothing here constitutes legal advice. The practical upgrade check is whether your client's hook surface still matches what the plugin expects after a client update, since a silently ignored hook would look like savings that are not happening.

Editorial conclusion

Adopt it if you run Claude Code or another supported CLI and your sessions keep re-reading unchanged files, because the plugin path is one marketplace command and the refusal names its own replacement. Skip it if you need a hosted shared cache or a causal graph-reuse number today, since the repository marks that study Collecting and the graph potential is excluded from the verified headline. Before trusting the dashboard, check which rows carry an MCP handshake identity and which are filed as unattributed, and read docs/TOKEN_ACCOUNTING.md to see how ambiguous model ids are priced.

Official sources

1. Issues
2. License: MIT
3. ooples/token-optimizer-mcp on GitHub
4. README
5. Releases