Paybond MCP Server

An MCP host hands your agent tools that can charge real money. A per-transaction cap does not help much: twelve $399 tool calls under a $500 cap still clear $4,788, because each approval has no memory of the last — and a cleared charge is not proof the work happened.

Paybond ships a tenant-bound MCP server that closes that gap. It binds delegated spend to a signed intent, releases or refunds against submitted completion evidence, and returns a receipt finance can replay — while preserving the same tenant boundary as the SDKs and APIs. Use it for internal agent runtimes and orchestration systems that prefer MCP over custom HTTP wrappers.

First-class adapter surface.MCP hosts are a supported framework integration path alongside in-process adapters — seeAgent middleware,Coding-agent setup, and theKit support matrix.

For coding-agent setup, including Codex and generic stdio MCP snippets usingnpx -y -p @paybond/kit paybond-mcp-server, start withCoding-agent setup.

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

The server is stdio-first by default — most desktop hosts launch it as a local child process. Hosts that need a network URL instead can use the hosted Streamable HTTP endpoint or self-host the same HTTP transport; seeRemote HTTP (Streamable HTTP)below.

import { createPaybondMcpToolSurface } from "@paybond/mcp";

- Equivalent subpath on the core package: @paybond/kit/mcp — use @paybond/kit when you need multiple adapters in one app.
- For stdio MCP hosts, launch npx -y -p @paybond/kit paybond-mcp-server — see Coding-agent setup in the docs.
- Python: paybond agent demo mcp smoke requires the optional mcp extra. Use pip install "paybond-kit[mcp]", pipx install 'paybond-kit[mcp]', or pipx inject paybond-kit mcp (when base paybond-kit is already installed).
- Smoke: paybond agent demo mcp smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --format json (in-process MCP).

Always required. For sandbox setup, use one of the login CLIs first:

npx -p @paybond/kit paybond login paybond-kit-login npx -p @paybond/kit paybond login paybond-kit-login

The CLIs writePAYBOND_API_KEYto.env.local; the packaged MCP servers load.env.localby default whenPAYBOND_API_KEYis not already present. SetPAYBOND_ENV_FILEfor a different local secrets file, or passPAYBOND_API_KEYin the MCP host launch environment. Production keys are created in Console and stored in deployment secret managers.

Restricted MCP keys (recommended for hosts)

For Cursor, Claude Desktop, Codex, and other MCP hosts, prefer arestrictedkey (paybond_rk_) over a standard service-account key (paybond_sk_). Restricted keys carry an explicit MCP scope grant;tools/listandtools/callexpose only the tools those scopes unlock, and the gateway enforces the same scopes on the underlying routes. Standard keys keep role-based RBAC and optionalPAYBOND_MCP_TOOL_POLICYfor local dev.

Create one from Console (Machine access → API keys → Restricted MCP key) or the CLI:

paybond keys create \ --name cursor-discovery \ --role analyst \ --kind restricted \ --preset mcp-readonly \ --label cursor-discovery paybond keys create \ --name cursor-discovery \ --role analyst \ --kind restricted \ --preset mcp-readonly \ --label cursor-discovery

Presets (settlement / live-money write is never included — add--scope mcp.settlement:writeonly when you intentionally need fund/confirm):

paybond mcp scopes list paybond mcp scopes list --format json paybond mcp scopes list paybond mcp scopes list --format json

Whenmcp installdetects a restricted key in the env file, it omitsPAYBOND_MCP_TOOL_POLICYfrom the generated host config — scopes come from the key. Pairing--tool-policy/--tool-allowlistwith a restricted key is rejected.

export PAYBOND_PRINCIPAL_PATH="/v1/auth/principal" export PAYBOND_MCP_MAX_RETRIES="3" export PAYBOND_MCP_EVIDENCE_POLICY="strict" export PAYBOND_ENV_FILE=".env.local" export PAYBOND_PRINCIPAL_PATH="/v1/auth/principal" export PAYBOND_MCP_MAX_RETRIES="3" export PAYBOND_MCP_EVIDENCE_POLICY="strict" export PAYBOND_ENV_FILE=".env.local"

PAYBOND_MCP_EVIDENCE_POLICYdefaults tostrict. In strict mode, evidence submit tools refuse calls untilpaybond_validate_completion_evidencesucceeds for the same preset and payload. Setoffonly for local debugging. Harbor predicate and schema validation remain authoritative at submit time.

Optional policy hot-reload for long-lived MCP processes:

export PAYBOND_POLICY_FILE="./paybond.policy.yaml" export PAYBOND_POLICY_RELOAD="watch" # watch | poll | off (default off) export PAYBOND_POLICY_RELOAD_ALLOW_LOOSEN="0" export PAYBOND_POLICY_FILE="./paybond.policy.yaml" export PAYBOND_POLICY_RELOAD="watch" # watch | poll | off (default off) export PAYBOND_POLICY_RELOAD_ALLOW_LOOSEN="0"

WhenPAYBOND_POLICY_FILEis set,paybond_authorize_agent_spendandpaybond_verify_capabilityenforce the policy registry before Harbor verification. Spend caps resolve from the policy file whenrequested_spend_centsis omitted. Reload waits for in-flight MCP tool calls to finish before swapping the registry; failed reloads keep the previous snapshot. Usepollwith tenant overlay policies to refresh effective policy from the Gateway.

npx paybond-mcp-server npx paybond-mcp-server

Stdio remains the default for desktop hosts (Cursor, Claude Desktop, Codex CLI). For hosts that need a network URL instead of a local subprocess — remote agent runtimes, MCP Inspector's HTTP mode, or any orchestrator that cannot launch child processes — Paybond also runs the same tool surface overStreamable HTTP, MCP's current remote transport (a singlePOST /mcpwith a JSON response; no legacy HTTP+SSE).

curl https://mcp.paybond.ai/mcp \ -X POST \ -H "content-type: application/json" \ -H "authorization: Bearer $PAYBOND_API_KEY" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' curl https://mcp.paybond.ai/mcp \ -X POST \ -H "content-type: application/json" \ -H "authorization: Bearer $PAYBOND_API_KEY" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

{ "url": "https://mcp.paybond.ai/mcp", "headers": { "Authorization": "Bearer paybond_rk_sandbox_..." } } { "url": "https://mcp.paybond.ai/mcp", "headers": { "Authorization": "Bearer paybond_rk_sandbox_..." } }

# TypeScript npx paybond-kit mcp serve --transport http # Python (requires the optional \mcp\ extra: pip install "paybond-kit[mcp]") paybond-kit mcp serve --transport http # TypeScript npx paybond-kit mcp serve --transport http # Python (requires the optional \mcp\ extra: pip install "paybond-kit[mcp]") paybond-kit mcp serve --transport http

The Python CLI binds toone tenantfor the life of the process: setPAYBOND_API_KEYin the process environment and every incoming Bearer token is checked against that single key (a shared-secret gate on network access, not a way to serve multiple tenants from one process). The TypeScript CLI is multi-tenant like the hosted endpoint — it derives tenant scope per request from whatever key the caller presents. Both accept the samePAYBOND_MCP_HTTP_environment variables:

export PAYBOND_MCP_HTTP_ADDR="0.0.0.0:8080" # default export PAYBOND_MCP_HTTP_ALLOWED_ORIGINS="https://example.com" # comma-separated; only enforced when a client sends an Origin header export PAYBOND_MCP_HTTP_MAX_BODY_BYTES="1048576" # 1 MiB default export PAYBOND_MCP_HTTP_RATE_LIMIT_PER_MINUTE="120" # per authenticated API key export PAYBOND_MCP_HTTP_RATE_LIMIT_UNAUTH_PER_MINUTE="30" # per source IP, slows credential scanning export PAYBOND_MCP_HTTP_ADDR="0.0.0.0:8080" # default export PAYBOND_MCP_HTTP_ALLOWED_ORIGINS="https://example.com" # comma-separated; only enforced when a client sends an Origin header export PAYBOND_MCP_HTTP_MAX_BODY_BYTES="1048576" # 1 MiB default export PAYBOND_MCP_HTTP_RATE_LIMIT_PER_MINUTE="120" # per authenticated API key export PAYBOND_MCP_HTTP_RATE_LIMIT_UNAUTH_PER_MINUTE="30" # per source IP, slows credential scanning

# Preferred (scopes on the key) paybond keys create --name cursor --role analyst --kind restricted --preset mcp-readonly paybond mcp install --host generic --scope project # Local standard-key override (dev only) paybond mcp install --host generic --scope project --tool-policy readonly # Preferred (scopes on the key) paybond keys create --name cursor --role analyst --kind restricted --preset mcp-readonly paybond mcp install --host generic --scope project # Local standard-key override (dev only) paybond mcp install --host generic --scope project --tool-policy readonly

paybond agent demo mcp smoke \ --operation paid-tool \ --requested-spend-cents 100 \ --evidence-preset cost_and_completion \ --format json paybond agent demo mcp smoke \ --operation paid-tool \ --requested-spend-cents 100 \ --evidence-preset cost_and_completion \ --format json

The smoke uses in-processPaybondMCPServer.callTool()(TypeScript) orbuild_mcp_server().call_tool()(Python): sandbox bind,paybond_authorize_agent_spend, mock side-effect completion, andpaybond_submit_sandbox_guardrail_evidence. Python requires the optionalmcpextra (pip install "paybond-kit[mcp]").

- The server is bound toone tenantderived from the configured service-account API key.
- Donotpass tenant IDs manually through tool arguments for normal flows.
- Gateway-backed state-changing tools require the right proof material and fail closed when proofs are missing, stale, replayed, or mismatched.
- Signed Harbor request bodies remain the caller's responsibility. The MCP server does not manage long-lived signing keys on behalf of the model.
- The hosted HTTP endpoint (https://mcp.paybond.ai/mcp) accepts:

- Restricted keys(paybond_rk_) — preferred for agents and automation; scopes on the key are the permission model.

- Standard keys(paybond_sk_) — full role entitlements; use only when you intentionally want an unrestricted machine credential.
- MCP OAuth access tokens(paybond_oat_) — user-scoped grants from the Console consent flow for interactive hosts (Cursor, Claude, VS Code). Short-lived; refresh withpaybond_ort_viaPOST /v1/oauth/token.

Check which credential a host config will actually use:

paybond doctor --mcp --host claude paybond doctor --mcp --host claude

--mcpfails when the config resolves to an unrestrictedpaybond_sk_key (the gateway cannot cap its MCP surface) and again when that key is not even narrowed byPAYBOND_MCP_TOOL_POLICY. Pass--config <path>to grade an on-disk host config instead of the onepaybond mcp installwould generate.

Tenant admins manage the per-environment MCP kill switch, active OAuth sessions, and custom redirect URIs underConsole → Machine access → MCP access. Disabling MCP blocks new grants and rejects existingpaybond_oat_bearers for that environment.

Example local stdio entry using the default.env.localwritten bypaybond login:

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

Advanced direct-key entry for hosts that cannot read env files:

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

MCP’s ARS role isagent-to-agent receipt handoffvia the resource URIpaybond://receipt/{receipt_id}—hosts pass the URI between agents without embedding full JSON in prompts.

- resources/templates/list— publishes thepaybond://receipt/{receipt_id}template
- resources/read— fetches the signedpaybond.agent_receipt_v1JSON and verifies at theoperationaltier before returning; verification failure returns a clear error (contents are not handed off unsigned)

Readonly tools (same surface as settlement-receipt tools):

- paybond_get_agent_receipt_v1— fetch byreceipt_id
- paybond_verify_agent_receipt_v1— offline verify of a receipt object; optionalvalidity_tier(operationaldefault, orprimary/attested)

Validity tiers beyond a quick handoff check, continuity-chain audits, Merkle inclusion / tree-head proofs, confidential owner disclosure, and ACTA / PEF / SCITT export adapters areKit TypeScript/Python, CLI, and Gatewayauditor surfaces—not MCP’s full job. Use Kit client libraries for those flows.

Compliance audit exports that include agent receipts may also ship PEF companions (*.pef.json) beside each signed receipt JSON.

- Coding-agent setup
- One-command guardrails
- Authentication & tenant binding
- Agent integrations
- V2 protocol trust