Spend controls for MCP hosts

MCP hosts (Claude Desktop, Codex, Cursor, custom orchestrators) launch Paybond as a stdio MCP server. The server exposes a tenant-bound tool surface: verify capabilities, authorize spend through Paybond before side-effecting work, and submit evidence — same tenant boundary as the SDKs.

Adapter reference: /docs/kit/mcp-server.

• stdio MCP server

  paybond-mcp-server exposes tenant-bound tools for Claude Desktop, Codex, Cursor, and custom hosts.

• Authorize before paid tools

  paybond_authorize_agent_spend verifies Harbor spend before side-effecting host tools.

• Evidence submit

  paybond_submit_spend_evidence binds completion digests — strict policy by default.

• Same tenant boundary

  MCP tools use the same authenticated session as Kit SDKs — never trust host-supplied tenant ids alone.

Why Paybond (not just MCP host approvals)?

MCP host approvals do not enforce a spend limit, a per-operation permission check (capability token), or a signed completion receipt tied to a spend agreement (intent).

How it works

3-minute quickstart

Smoke the Harbor MCP contract — no MCP host required for this check:

paybond login
paybond agent sandbox smoke \
  --operation paid-tool \
  --requested-spend-cents 100 \
  --evidence-preset cost_and_completion \
  --result-body '{"status":"ok","cost_cents":100}' \
  --format table

paybond login
paybond agent sandbox smoke \
  --operation paid-tool \
  --requested-spend-cents 100 \
  --evidence-preset cost_and_completion \
  --result-body '{"status":"ok","cost_cents":100}' \
  --format table

For MCP-native sandbox tools inside a running host, call paybond_bootstrap_sandbox_guardrail before the paid tool and paybond_submit_sandbox_guardrail_evidence after.

When the smoke succeeds you should see:

• ✓ Spend approved
• ✓ Tool completed
• ✓ Evidence verified (cost_and_completion)

What success looks like

Launch the server

npx -y -p @paybond/kit paybond-mcp-server

npx -y -p @paybond/kit paybond-mcp-server

Required: PAYBOND_API_KEY (from paybond login → .env.local). For MCP hosts in production, create a restricted MCP key (paybond_rk_*) in Console under Machine access → API keys (or paybond keys create --kind restricted --preset mcp-readonly) so the credential itself limits which tools the host can see. Interactive hosts (Cursor/Claude/VS Code) can instead complete MCP OAuth consent and present a short-lived paybond_oat_* bearer — manage sessions and the per-environment MCP toggle under Machine access → MCP access. Standard paybond_sk_* keys still work with optional PAYBOND_MCP_TOOL_POLICY for local development.

Optional policy hot-reload:

export PAYBOND_POLICY_FILE="./paybond.policy.yaml"
export PAYBOND_POLICY_RELOAD="watch"

export PAYBOND_POLICY_FILE="./paybond.policy.yaml"
export PAYBOND_POLICY_RELOAD="watch"

Inspect the scope catalog offline: paybond mcp scopes list.

Wire host config

{
  "mcpServers": {
    "paybond": {
      "command": "npx",
      "args": ["-y", "-p", "@paybond/kit", "paybond-mcp-server"],
      "env": {
        "PAYBOND_ENV_FILE": ".env.local"
      }
    }
  }
}

Full coding-agent setup: /docs/kit/coding-agent-setup.

Production MCP flow

1. paybond_create_spend_intent or paybond_fund_intent → intent_id and capability_token
2. paybond_authorize_agent_spend before the paid or side-effecting tool
3. Execute vendor work
4. paybond_submit_spend_evidence with completion payload

PAYBOND_MCP_EVIDENCE_POLICY defaults to strict — evidence submit tools refuse calls until validation succeeds for the preset and payload.

Scaffold a paid-tool guard

npx -p @paybond/kit paybond-init \
  --preset paid-tool-guard \
  --framework provider-agnostic \
  --out paybond-paid-tool-guard.ts

npx -p @paybond/kit paybond-init \
  --preset paid-tool-guard \
  --framework provider-agnostic \
  --out paybond-paid-tool-guard.ts

For multi-tool agents in application code, graduate to agent middleware.

Production checklist

Works with

Ready to test?

Related guides

• Claude Agent SDK spend controls — in-process MCP custom tools
• Agent-agnostic spend controls — custom orchestrators
• Agent policy-as-code — PAYBOND_POLICY_FILE hot-reload

Developer reference: /docs/kit/mcp-server.