spendctl MCP

An official MCP server providing a sandbox environment for the spendctl spend-policy control plane. It allows AI agents to test budget enforcement, payment refusals, human approvals, and receipt generation using mock funds and APIs without requiring installation or real credentials.

Visit spendctl

Endpoint and access

No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.

Vendor evidenceStreamable HTTPNo sign-inEndpoint checked 2026-11-01Operated by spendctl

MCP endpoint (Streamable HTTP)

https://mcp.spendctl.dev/mcp

Vendor documentation

What you can do with it

Test spend policy enforcement with mock budgets
Simulate payment refusals and approval workflows
Generate mock receipts for agent transactions
Validate agent spending limits without real funds

Source and maintenance

Vendor evidenceRegistry 0.1.0

mcp-registry: dev.spendctl/spendctl@0.1.0 Project website

Protocol and capabilities

Server: spendctl-sandbox 0.1.0
MCP protocol: 2025-06-18
Tools: 6 advertised
Resources: Not advertised
Resource templates: Not advertised
Prompts: Not advertised

Server-advertised capabilities

{
  "tools": {
    "listChanged": true
  }
}

Server-provided instructions

Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.

spendctl sandbox: a login-free, isolated spendctl sidecar for trying spend policies for AI agents that pay for APIs (x402, MPP). Start with sandbox_create; it returns the sandbox_id every other tool needs, the policy and the two mock paid endpoints. Then sandbox_pay fetches a paid endpoint through the sidecar, which pays, refuses or holds the payment for approval. check_budget, list_receipts and get_policy read the sandbox state; approve decides a held payment, after which sandbox_pay with the approvalId completes it. Nothing is real: throwaway wallet, mock facilitator, no outbound network. A sandbox expires after 2 hours without calls (24 hours at most) and allows 200 governed payments. Docs: https://spendctl.dev/docs/sandbox/

Tools

6 advertised

sandbox_create — Create a spendctl sandbox

Advertised by the server during the last successful anonymous check.

Creates an isolated spendctl sandbox and returns its sandbox_id. Call it first: every other tool needs the sandbox_id, and one sandbox serves a whole conversation (create another only to try a different preset). The sandbox is a real spendctl sidecar with a throwaway wallet, a mock x402 facilitator and two mock paid APIs; no real money moves and nothing outside the sandbox is reachable. Returns the sandbox_id, the agent's policy (budgets, allowed hosts, approval rule) and the paid endpoints with their prices. Limits: 5 sandboxes per minute per client; a sandbox expires after 2 hours without calls (24 hours at most). Example: preset "strict" to see refusals, "approvals" to see a payment held for a human.

sandbox_create input schema

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "preset": {
      "enum": [
        "default",
        "strict",
        "approvals"
      ],
      "type": "string",
      "default": "default",
      "description": "Policy preset. default: comfortable caps, both endpoints allowed; strict: $0.015 per request and $0.03 per day, weather only, so the search API and a fourth weather call are refused; approvals: payments at or above $0.015 wait for approve"
    }
  }
}

sandbox_create annotations

{
  "title": "Create a spendctl sandbox",
  "readOnlyHint": false,
  "openWorldHint": false,
  "idempotentHint": false,
  "destructiveHint": false
}

sandbox_pay — Fetch a paid sandbox URL

Advertised by the server during the last successful anonymous check.

Fetches one of the sandbox's paid endpoints (HTTP 402, x402) through the spendctl sidecar, which applies the sandbox agent's budget, allowlist and approval policy, pays with the throwaway wallet if allowed, and returns the response. Use it for every paid call in the sandbox: with dryRun to see the decision without paying, with approvalId to complete a payment that was held and then approved. The endpoints are https://weather.sandbox.spendctl.dev/weather?city=<name> ($0.01) and https://search.sandbox.spendctl.dev/search?q=<query> ($0.02), as listed by sandbox_create and documented at https://spendctl.dev/docs/sandbox/; any other host is refused. Returns a one-line summary (HTTP status, amount paid, decision, receipt id) followed by the response body, or the refusal with its reason, or an approval id when the payment is waiting for a human. Only sandbox hosts exist and no real funds are involved; the request is always a GET and responses are clipped at 20,000 characters. Example: url https://weather.sandbox.spendctl.dev/weather?city=Kyoto

sandbox_pay input schema

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "sandbox_id",
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "Absolute URL of a sandbox endpoint, e.g. https://weather.sandbox.spendctl.dev/weather?city=Kyoto"
    },
    "dryRun": {
      "type": "boolean",
      "description": "true: only report what spendctl would decide; never pay"
    },
    "approvalId": {
      "type": "string",
      "description": "The approval id from an earlier sandbox_pay result, after approve accepted it, to complete that held payment"
    },
    "sandbox_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{32}$",
      "description": "The sandbox_id returned by sandbox_create (32 hex characters)"
    },
    "idempotencyKey": {
      "type": "string",
      "description": "Reuse the same key when retrying a call so the sandbox is never charged twice, e.g. \"kyoto-1\""
    }
  }
}

sandbox_pay annotations

{
  "title": "Fetch a paid sandbox URL",
  "readOnlyHint": false,
  "openWorldHint": false,
  "idempotentHint": false,
  "destructiveHint": false
}

check_budget — Check remaining budget

Advertised by the server during the last successful anonymous check.

Advertised read-only

Shows the sandbox agent's spending limits, what has been spent in each window and what is left. Use it before a paid call when the remaining budget matters, or after a refusal to see which limit was hit. Returns the agent name and mode, the per-request limit, the approval threshold, what happens when a budget is exceeded, the allowed hosts and one line per window (hourly, daily: spent, limit, remaining). Read-only; changes nothing.

check_budget input schema

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "sandbox_id"
  ],
  "properties": {
    "sandbox_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{32}$",
      "description": "The sandbox_id returned by sandbox_create (32 hex characters)"
    }
  }
}

check_budget annotations

{
  "title": "Check remaining budget",
  "readOnlyHint": true,
  "openWorldHint": false
}

list_receipts — List receipts

Advertised by the server during the last successful anonymous check.

Advertised read-only

Lists the sandbox agent's most recent payment attempts, newest first: paid (amount and mock transaction hash), refused (reason codes) and waiting for approval. Use it to report what happened so far or to find a receipt id; after a hold, the approval id is in the sandbox_pay result. Returns up to `limit` lines, one per attempt, with time, receipt id, method, URL, amount and status, or "No payments yet." Read-only.

list_receipts input schema

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "sandbox_id"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 10,
      "maximum": 100,
      "minimum": 1,
      "description": "How many attempts to return, newest first (1 to 100, default 10)"
    },
    "sandbox_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{32}$",
      "description": "The sandbox_id returned by sandbox_create (32 hex characters)"
    }
  }
}

list_receipts annotations

{
  "title": "List receipts",
  "readOnlyHint": true,
  "openWorldHint": false
}

get_policy — Show the sandbox policy

Advertised by the server during the last successful anonymous check.

Advertised read-only

Returns the sandbox's spendctl.yaml as text: the preset name and the agent's budgets, allowed hosts and approval rules. Use it to explain why a payment was refused or held, or to show what a spendctl policy file looks like. Read-only; the sandbox policy cannot be changed, create a sandbox with another preset instead.

get_policy input schema

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "sandbox_id"
  ],
  "properties": {
    "sandbox_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{32}$",
      "description": "The sandbox_id returned by sandbox_create (32 hex characters)"
    }
  }
}

get_policy annotations

{
  "title": "Show the sandbox policy",
  "readOnlyHint": true,
  "openWorldHint": false
}

approve — Approve or deny a held sandbox payment

Advertised by the server during the last successful anonymous check.

Approves or denies a payment that sandbox_pay reported as waiting for approval, as the human approver would with `spendctl approve`. Use it only with an approval id from this sandbox; in the real product a human decides, in the sandbox the model plays that role. Returns the approval id and its new status (approved or denied). An approved payment completes when sandbox_pay is called again with the same approvalId; a denied one stays refused. Deciding the same approval twice keeps the first decision.

approve input schema

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "sandbox_id",
    "approvalId"
  ],
  "properties": {
    "note": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional reason recorded with the decision, up to 200 characters"
    },
    "decision": {
      "enum": [
        "approve",
        "deny"
      ],
      "type": "string",
      "default": "approve",
      "description": "approve releases the held payment; deny refuses it for good"
    },
    "approvalId": {
      "type": "string",
      "description": "The approval id returned by sandbox_pay in its \"waiting for approval\" result (Approval id: ...)"
    },
    "sandbox_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{32}$",
      "description": "The sandbox_id returned by sandbox_create (32 hex characters)"
    }
  }
}

approve annotations

{
  "title": "Approve or deny a held sandbox payment",
  "readOnlyHint": false,
  "openWorldHint": false,
  "idempotentHint": true,
  "destructiveHint": false
}

Prompts

Not advertised

No prompt definitions available.

Resources

Not advertised

No resource definitions available.

30-day availability

Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.

Successful checks: 1 of 1 (100%)
Average latency: 188 ms
95th percentile latency: 188 ms

Maintenance history

Public check and source-refresh events. Editorial and ownership records remain private.

Nov 1, 2026, 8:22 AM UTC · probe · passed · 188 ms · metadata changed · 6 tool(s)

Connect from your client

Each snippet registers the same endpoint; pick the client you use.

This server is operated by the named third party. Listing and endpoint checks are not an endorsement or a security audit. Review the operator's permissions, terms, and data handling before connecting. How listings are checked and corrected.

Claude Code

Run this once in a terminal. It registers the remote server. Use --scope project to write .mcp.json for the repo.

Claude Code configuration

claude mcp add --transport http spendctl-mcp https://mcp.spendctl.dev/mcp

Codex

Run this once. Codex stores MCP servers in ~/.codex/config.toml (or .codex/config.toml in a trusted project).

Codex configuration

codex mcp add spendctl-mcp --url https://mcp.spendctl.dev/mcp

Cursor

Merge this server into .cursor/mcp.json in your project, then enable spendctl-mcp in your MCP settings.

Cursor configuration

{
  "mcpServers": {
    "spendctl-mcp": {
      "url": "https://mcp.spendctl.dev/mcp"
    }
  }
}

Cline

Merge this into cline_mcp_settings.json (Cline → MCP Servers → Configure).

Cline configuration

{
  "mcpServers": {
    "spendctl-mcp": {
      "type": "streamableHttp",
      "url": "https://mcp.spendctl.dev/mcp",
      "disabled": false
    }
  }
}

VS Code

Merge this server into .vscode/mcp.json. Use MCP: List Servers to start spendctl-mcp and inspect its tools.

VS Code configuration

{
  "servers": {
    "spendctl-mcp": {
      "type": "http",
      "url": "https://mcp.spendctl.dev/mcp"
    }
  }
}

Gemini CLI

Run this once. It writes .gemini/settings.json in the current project; pass --scope user for ~/.gemini/settings.json.

Gemini CLI configuration

gemini mcp add --transport http spendctl-mcp https://mcp.spendctl.dev/mcp

Claude Desktop

Merge this into claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), then restart Claude Desktop.

Claude Desktop configuration

{
  "mcpServers": {
    "spendctl-mcp": {
      "url": "https://mcp.spendctl.dev/mcp"
    }
  }
}

Windsurf

Merge this into ~/.codeium/windsurf/mcp_config.json, then refresh MCP in Cascade. Windsurf remote servers use serverUrl, not url.

Windsurf configuration

{
  "mcpServers": {
    "spendctl-mcp": {
      "serverUrl": "https://mcp.spendctl.dev/mcp"
    }
  }
}

Let your agent find its tools

Find servers like spendctl MCP from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.

Connect Koskamo Explore workflows

See all 511

Do you run spendctl MCP?

Prove ownership with a DNS record, a well-known file, or your Official MCP Registry entry, and your edits publish immediately. Proofs are re-checked weekly; admins can still hide or remove a listing.

Claim this listing

spendctl MCP

Endpoint and access

What you can do with it

Source and maintenance

Protocol and capabilities

Server-provided instructions

Tools

Prompts

Resources

30-day availability

Maintenance history

Connect from your client

Claude Code

Codex

Cursor

Cline

VS Code

Gemini CLI

Claude Desktop

Windsurf

Let your agent find its tools

Other payments servers

Do you run spendctl MCP?