agentbill-mcp

One spend ceiling for one agent job, exposed as MCP tools. Bound to a task_ref you pass, not to a calendar month.

What it does

Exposes two tools to any MCP-compatible agent host (Claude Code, Cursor, Windsurf, etc.):

• preflight(agent_id, customer_id, estimated_units, ceiling, task_ref, task_ceiling, idempotency_key). Check budget before starting work; answers approved=False with a reason when a ceiling or balance is spent. Pass task_ref with a task_ceiling to give one job a single cross-call budget that every later call in the job consults, and idempotency_key so a retried check cannot reserve the budget twice.
• record_event(agent_id, units, customer_id, metadata). Bill a customer after work completes. Idempotent.

Install

uvx agentbill-mcp

No install needed. uvx runs it directly.

Configure

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "agentbill": {
      "command": "uvx",
      "args": ["agentbill-mcp"],
      "env": {
        "AGENTBILL_API_KEY": "agb_your_key_here"
      }
    }
  }
}

Cursor / Windsurf / other MCP clients

Add to your MCP config:

{
  "agentbill": {
    "command": "uvx",
    "args": ["agentbill-mcp"],
    "env": {
      "AGENTBILL_API_KEY": "agb_your_key_here"
    }
  }
}

Get your API key at agentbill.dev/register.

Usage

Once configured, any agent using this MCP server can:

# Before running a task:
preflight(agent_id="research_agent", customer_id="user_123", estimated_units=5)

# After completing the task:
record_event(agent_id="research_agent", units=5, customer_id="user_123")

The server answers approved=False when the customer has no remaining balance, and the agent host decides what happens next. No code changes needed in your agent.

Environment variables

Links

• Docs: agentbill.dev
• Python SDK: pip install agentbill-sdk
• GitHub: github.com/marketinglior-pixel/agentbill