mcp tokens budget agents context 

Token Gate

Token and context budget for AI agents. Track spend, estimate the cost of a read, and catch the burn before it happens.

Version

v0.1.3

License

MIT

Platforms

Node 18 or newer, Any MCP client

Interfaces

CLI, MCP

View on GitHubnpm packageMCP server

Overview

Agents discover their budget is gone after it is gone. A single file dump can cost more than an entire task was worth. Token Gate makes spend visible and measurable, and warns before the expensive read.

Setup

npm install -g token-gate-mcp

Add the server to your MCP client.

{
  "mcpServers": {
    "token-gate": {
      "command": "token-gate-mcp",
      "args": []
    }
  }
}

Usage

  • context.log record a token spend event by kind: read, tool, model, write, other.
  • context.report the session totals, spend by kind, budget, and remaining.
  • context.estimate estimate the token cost of reading a file and compare it with a cheaper alternative such as a graph query.
  • context.limit set or read the session budget.
  • context.check a boolean the agent can gate on: within budget or over budget.

Estimates assume roughly four characters per token.

Typical agent instructions:

  • “How much of the budget have we spent?”
  • “Should I read this file or ask the graph instead?”
  • “Stop before we go over budget.”

Gains

  • Budget discipline enforced by a gate the agent can act on.
  • Expensive reads flagged before they happen, with a cheaper path.
  • Spend visible by kind, so waste is attributable.
  • The token savings of the HEIDES graph become measurable per session.

Repository