MCP agent spend controls

Paybond ships a tenant-bound MCP server for internal agent runtimes and orchestration systems that prefer MCP over custom HTTP wrappers. It exposes a supported Paybond tool surface while preserving the same tenant boundary as the SDKs and APIs.

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

For coding-agent setup, including Codex and generic stdio MCP snippets using npx -y -p @paybond/kit paybond-mcp-server, start with Coding-agent setup.

For a first guardrail integration outside MCP, start with the sandbox scaffold:

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

For MCP-native hosts, the matching sandbox tools are paybond_bootstrap_sandbox_guardrail and paybond_submit_sandbox_guardrail_evidence.

The server is intentionally stdio-first. It is designed to run as a local child process launched by an MCP client or host.

Paybond does not assume a specific model provider or agent framework. The only assumption is that your host can launch a stdio MCP server and speak MCP tool calls.

Install

npm install @paybond/mcp

Import from @paybond/mcp

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.

Required environment

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 write PAYBOND_API_KEY to .env.local; the packaged MCP servers load .env.local by default when PAYBOND_API_KEY is not already present. Set PAYBOND_ENV_FILE for a different local secrets file, or pass PAYBOND_API_KEY in the MCP host launch environment. Production keys are created in Console and stored in deployment secret managers.

Optional:

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_POLICY defaults to strict. In strict mode, evidence submit tools refuse calls until paybond_validate_completion_evidence succeeds for the same preset and payload. Set off only 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"

When PAYBOND_POLICY_FILE is set, paybond_authorize_agent_spend and paybond_verify_capability enforce the policy registry before Harbor verification. Spend caps resolve from the policy file when requested_spend_cents is omitted. Reload waits for in-flight MCP tool calls to finish before swapping the registry; failed reloads keep the previous snapshot. Use poll with tenant overlay policies to refresh effective policy from the Gateway.

Run

Python

paybond-mcp-server
paybond-mcp-server

TypeScript

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

Tool categories

Always available:

paybond_get_principal
paybond_verify_capability
paybond_authorize_agent_spend
paybond_bootstrap_sandbox_guardrail
paybond_submit_sandbox_guardrail_evidence
paybond_list_intents
paybond_get_intent
paybond_get_reputation_receipt
paybond_get_portfolio_summary
paybond_get_signed_portfolio_artifact
paybond_get_fraud_assessment
paybond_get_fraud_metrics
paybond_verify_agent_mandate_v1
paybond_verify_agent_recognition_proof_v1
paybond_import_agent_mandate_v1
paybond_get_settlement_receipt_v1
paybond_verify_protocol_receipt_v1
paybond_validate_completion_evidence
paybond_create_intent
paybond_create_spend_intent
paybond_fund_intent
paybond_submit_evidence
paybond_submit_spend_evidence
paybond_confirm_settlement

The spend-named tools are aliases over the same tenant-bound Harbor and Gateway routes. They exist so agent hosts can match user requests like "control agent spend", "add tool-call spend limits", or "authorize paid vendor actions" without guessing from lower-level capability names.

The sandbox guardrail tools are separate developer-only helpers. They call /v1/sandbox/guardrails/..., derive tenant scope from the configured service-account API key, and do not replace the production Harbor create/fund/evidence tools.

Typical spend flow

Call paybond_create_spend_intent to create the signed spend intent.
If the intent is not funded immediately, call paybond_fund_intent.
Use the returned intent_id and capability_token with paybond_authorize_agent_spend before any paid API call, vendor action, settlement step, or other side-effecting tool.
Call paybond_validate_completion_evidence with the completion preset and payload you plan to submit.
After the guarded work completes, call paybond_submit_spend_evidence with the same preset and payload.

If you are writing SDK code instead of exposing MCP tools, use paybond.spendGuard(intentId, capabilityToken) in TypeScript or paybond.spend_guard(intent_id, capability_token) in Python. PaybondCapabilityBinding is only needed for Python framework adapters that require a run-context object.

Sandbox guardrail smoke flow

Call paybond_bootstrap_sandbox_guardrail with an operation and sandbox spend amount.
Use the returned intent_id and capability_token with paybond_authorize_agent_spend before the sample paid tool executes.
Call paybond_validate_completion_evidence when using a completion preset (for example api_response_ok).
Call paybond_submit_sandbox_guardrail_evidence with the sandbox intent_id, completion_preset_id, and evidence payload.

Security model

The server is bound to one tenant derived from the configured service-account API key.
Do not pass 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.
Remote HTTP transport is intentionally out of scope. A remote MCP deployment would need a separate approval and authentication boundary.

Example MCP client config

Example local stdio entry using the default .env.local written by paybond 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_..."
  }
}