Claude Agent SDK
The Claude Agent SDK takes MCP servers, and spendctl ships one: npx spendctl mcp. It is a thin client of the sidecar you run. It holds no key and cannot approve anything; it gives the agent five tools.
| Tool | What it does |
|---|---|
pay |
Fetches a URL that may cost money, through the sidecar’s policy |
check_budget |
Limits, spend per window, what is left |
list_receipts |
Recent attempts: paid, refused, waiting |
await_approval |
Waits for a human’s decision on a held call without paying again |
withdraw_approval |
Takes a held call back when the task no longer needs it |
Before you start
Section titled “Before you start”Run the sidecar and, for a first try, the mock sellers (Quickstart):
npx spendctl initnpx spendctl mock # terminal 1npx spendctl start # terminal 2MCP clients time out a tool call long before a human answers, so set approvals.hold: false in spendctl.yaml: pay then returns the approval id at once.
npm install @anthropic-ai/claude-agent-sdkThe agent
Section titled “The agent”import { query } from "@anthropic-ai/claude-agent-sdk";
const prompt = "Check my remaining budget, then get the weather for Tokyo and Osaka from http://localhost:4021/weather?city=<city>. " + "If spendctl refuses or asks for approval, tell me why instead of retrying.";
for await (const message of query({ prompt, options: { mcpServers: { spendctl: { type: "stdio", command: "npx", args: ["spendctl", "mcp"], env: { SPENDCTL_AGENT: "researcher", SPENDCTL_URL: "http://127.0.0.1:8402" }, }, }, allowedTools: ["mcp__spendctl__pay", "mcp__spendctl__check_budget", "mcp__spendctl__list_receipts"], },})) { if (message.type === "result" && message.subtype === "success") console.log(message.result);}This example allows three of the five tools, so the agent reports an approval instead of waiting for it. Add mcp__spendctl__await_approval and mcp__spendctl__withdraw_approval to allowedTools to let it wait for the decision and then complete the payment with pay and the approvalId.
Claude Code
Section titled “Claude Code”The same server, one command:
claude mcp add spendctl -e SPENDCTL_AGENT=researcher -- npx spendctl mcpOr install the plugin, which adds a skill that tells the agent how to handle budgets, refusals and approvals:
claude plugin marketplace add miraistudio/spendctl-sdkclaude plugin install spendctl@spendctlTo try the tools with nothing running on your machine, connect the hosted sandbox instead.
- What
paychecks before anything is signed: Budgets for AI agents. - How a held payment is decided: Approvals.