組み込み方

ゲートウェイ URL（言語を問わない）

curl -H "X-Spendctl-Agent: researcher" "http://127.0.0.1:8402/https://api.example.com/report?id=42"

宛先を X-Spendctl-Target ヘッダで渡し、http://127.0.0.1:8402/ に送る形でも構いません。レスポンスには x-spendctl-attempt、x-spendctl-decision、x-spendctl-amount が付きます。

`wrapFetch`（TypeScript / JavaScript）

import { wrapFetch, readRefusal, AgentClient } from "@spendctl/client";

const pay = wrapFetch({ agent: "researcher" });
const res = await pay("https://api.example.com/report");
const refusal = await readRefusal(res);   // 支払い済み・無料なら undefined
const budget = await new AgentClient({ agent: "researcher" }).budget();

Python（`spendctl-sdk`）

pip install "spendctl-sdk[httpx]"   # または [requests]。パッケージ自体に依存はありません

from spendctl_sdk import httpx_client, read_refusal, AgentClient

with httpx_client(agent="researcher") as http:      # 既定で SPENDCTL_URL / SPENDCTL_AGENT を読みます
    res = http.get("https://api.example.com/report")
    refusal = read_refusal(res)                     # 支払い済み・無料なら None
budget = AgentClient(agent="researcher").budget()

requests には requests_session(agent=...)、HTTP ライブラリなしなら pay(url, agent=...) が使えます。import 名は spendctl_sdk です。ソースと API 全体は github.com/miraistudio/spendctl-sdk にあります。

MCP

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

ツールは pay（費用がかかるかもしれない URL を取得）、check_budget、list_receipts の3つです。MCP サーバーは薄いクライアントで、鍵も承認権限も持ちません。

Claude Code / Cursor のプラグイン

公開の SDK リポジトリはプラグインのマーケットプレイスでもあります。spendctl は上の MCP サーバーを包んだもので（インストール時にエージェント名とサイドカー URL を聞きます）、予算・拒否・承認の扱い方をエージェントに教えるスキルが付きます。spendctl-sandbox は代わりにサンドボックスにつなぐもので、手元で動かすものはありません。

claude plugin marketplace add miraistudio/spendctl-sdk
claude plugin install spendctl@spendctl            # 手元のサイドカーに対して
claude plugin install spendctl-sandbox@spendctl    # ホスト版サンドボックス、インストール不要

Cursor では https://github.com/miraistudio/spendctl-sdk をマーケットプレイスとして取り込み（Dashboard → Plugins & MCPs → Add Marketplace → Import from Repo）、どちらかをインストールします。spendctl プラグインは変数 SPENDCTL_AGENT と SPENDCTL_URL を受け取ります。どちらも Apache-2.0 です: github.com/miraistudio/spendctl-sdk/tree/main/plugins。

HTTP_PROXY

spendctl run --agent researcher -- python agent.py

プロキシの認証情報にエージェント名を入れた HTTP_PROXY を設定して起動します。管理対象になるのは平文の http:// だけで、https:// は中身を見ずにトンネルします。有料の HTTPS API にはゲートウェイ URL を使ってください。

フレームワークのサンプル

Claude Agent SDK：mcpServers で MCP サーバーを渡す
OpenAI Agents SDK：wrapFetch を使う関数ツール
LangGraph：wrapFetch の上に tool() と createReactAgent

この3つの動くサンプルは、公開のクライアント SDK リポジトリ github.com/miraistudio/spendctl-sdk に置く予定です。

エージェント間の連鎖

spendctl は W3C baggage の spend.root、spend.parent、spend.depth を読み、上流に引き継ぎます。あなたのエージェント自体が有料サービスなら、受け取った baggage を外向きの呼び出しに引き継いでください（OpenTelemetry を使っていれば自動です）。spendctl trace <attempt-id> で木構造を表示できます。