Skip to content

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

Run the sidecar and, for a first try, the mock sellers (Quickstart):

Terminal window
npx spendctl init
npx spendctl mock # terminal 1
npx spendctl start # terminal 2

MCP 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.

Terminal window
npm install @anthropic-ai/claude-agent-sdk
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.

The same server, one command:

Terminal window
claude mcp add spendctl -e SPENDCTL_AGENT=researcher -- npx spendctl mcp

Or install the plugin, which adds a skill that tells the agent how to handle budgets, refusals and approvals:

Terminal window
claude plugin marketplace add miraistudio/spendctl-sdk
claude plugin install spendctl@spendctl

To try the tools with nothing running on your machine, connect the hosted sandbox instead.