# Claude Agent SDK

> Connect the spendctl MCP server to the Claude Agent SDK so an agent can pay for x402 and MPP APIs within a budget, with approvals held for a human. The same server works in Claude Code.

Source: https://spendctl.dev/docs/claude-agent-sdk/ (spendctl documentation; index of all pages at https://spendctl.dev/llms.txt)

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

Run the sidecar and, for a first try, the mock sellers ([Quickstart](https://spendctl.dev/docs/quickstart/)):

```bash
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.

```bash
npm install @anthropic-ai/claude-agent-sdk
```

## The agent

```ts
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

The same server, one command:

```bash
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:

```bash
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](https://spendctl.dev/docs/sandbox/) instead.

## Next

- What `pay` checks before anything is signed: [Budgets for AI agents](https://spendctl.dev/docs/agent-budgets/).
- How a held payment is decided: [Approvals](https://spendctl.dev/docs/approvals/).
