TokenOps MCP Server

Local-first token usage tracking, budget enforcement, and LLM routing for any MCP-compatible coding agent.

Why TokenOps?

Every coding agent (Claude Code, Cursor, Kiro, Cline, Windsurf) makes LLM calls — but none of them tell you what it costs. TokenOps fixes that:

• Track every LLM call with token counts and cost
• Budget with circuit breaker (allow → warn → degrade → block)
• Route to the cheapest model that can handle each task
• Audit monthly reports with savings opportunities
• Zero infra — local SQLite, MCP stdio, no servers

Quick Start

npx -y @finoptix/tokenops-mcp

That's it. The server starts on stdio and your agent connects automatically.

Register in your agent

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "tokenops": {
      "command": "npx",
      "args": ["-y", "@finoptix/tokenops-mcp"]
    }
  }
}

Kiro CLI (~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "tokenops": {
      "command": "npx",
      "args": ["-y", "@finoptix/tokenops-mcp"]
    }
  }
}

Cursor: Settings → MCP → Add server → Name: tokenops, Type: command, Command: npx -y @finoptix/tokenops-mcp

Tools

| Tool | Description | |------|-------------| | track_usage | Log an LLM call — model, tokens, cost, task type, complexity | | get_budget | Check remaining daily, monthly, and session budgets | | session_report | Cost summary for current or past sessions | | set_budget | Configure budget limits and over-limit actions | | run_audit | Monthly audit with model breakdown + savings opportunities |

track_usage

{
  "model": "claude-sonnet-4",
  "tokens_in": 500,
  "tokens_out": 200,
  "task_type": "code",
  "complexity": "simple"
}

Returns event ID, session ID, running session total, and budget status.

get_budget

{
  "period": "daily"
}

Returns limits, used amounts, remaining, and current action for each period.

session_report

{
  "session_id": "optional-defaults-to-current"
}

Returns total calls, tokens, cost, duration, and per-model breakdown.

Resources

| URI | Description | |-----|-------------| | tokenops://budget/status | Current budget state for all periods | | tokenops://sessions/recent | Last 10 sessions with totals | | tokenops://report/monthly | Current month aggregated report | | tokenops://usage/today | Today's usage breakdown by model |

Configuration

Config lives at ~/.tokenops/config.json (auto-created with defaults):

{
  "budgets": {
    "daily": { "limit_usd": 5.00, "action": "degrade" },
    "monthly": { "limit_usd": 100.00, "action": "block" }
  },
  "session": {
    "auto_track": true,
    "agent_type": "open-code"
  },
  "db_path": "~/.tokenops/usage.db"
}

Override with TOKENOPS_DB_PATH env var.

Steering (for agent-level installs)

Add this to your agent's instructions to use TokenOps:

TokenOps — Active Cost Management

Call get_budget before expensive operations. Call track_usage after each LLM call with model, tokens_in, tokens_out, task_type, complexity. Call session_report when asked about cost. Call run_audit monthly.

Architecture

┌──────────────────────────────────────┐
│        Coding Agent (MCP host)       │
└──────────────┬───────────────────────┘
               │ MCP stdio
               ▼
┌──────────────────────────────────────┐
│            tokenops-mcp              │
│                                      │
│  track_usage  get_budget  route_llm  │
│  session_report  set_budget  audit   │
│                                      │
│  ┌────────────────────────────────┐  │
│  │         SQLite (local)         │  │
│  │  usage_events  budget_config   │  │
│  │  sessions     budget_usage     │  │
│  └────────────────────────────────┘  │
│                                      │
│  Budget Guard (allow/warn/degrade/   │
│               degrade/block)         │
└──────────────────────────────────────┘

Two-Tier Architecture

| Tier | Platforms | Token Data | Tracking | |------|-----------|------------|----------| | 1 — Agent | Claude Code, Cursor, Cline, Windsurf | Estimated | Via steering | | 2a — Runtime hooks | OpenCode | Exact | Automatic plugin | | 2b — Gateway | Kiro, Cursor, Windsurf, Claude Code | Exact | Local HTTP proxy |

Full detail in Guides. Install and verify in OpenCode first, then every other agent — follow Install & Verify. The gateway (tokenops-gateway) is a non-invasive local proxy for closed-source agents — point any agent's base URL at http://localhost:8787 and it tracks exact usage without modifying any binary. It speaks both the OpenAI (/v1/chat/completions) and Anthropic (/v1/messages) protocols, so Cursor and Claude Code both work against the same port.

tokenops-gateway                      # starts on http://localhost:8787
curl http://localhost:8787/health     # → {"status":"ok"}

Development

git clone https://github.com/breakingthecloud/tokenops-mcp.git
cd tokenops-mcp
pnpm install
pnpm run dev    # watch mode
pnpm run build  # production

Roadmap

• Phase 1 ✅ MCP server core (track, budget, session, resources)
• Phase 2 ✅ Budget guard + route_llm with OpenRouter
• Phase 3 ✅ Audit reports with savings analysis
• Phase 4 ✅ npm publish + dogfood installs
• Phase 5 ✅ Native runtime hooks for OpenCode (plugin)
• Phase 6 ✅ Local gateway for closed-source agents (Kiro, Cursor, Windsurf) — verified against OpenRouter
• Dogfood 🔜 1-week real-usage tracking across agents

License

Apache 2.0 — see LICENSE.