Paybond MCP Server

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

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

TypeScriptPython

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.
• 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).

Required environment

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

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"

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"

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

TypeScript

npx paybond-mcp-server

Tool categories

Read-only discovery and compliance (allowed under --tool-policy readonly):

• paybond_get_principal
• paybond_list_intents
• paybond_get_intent
• paybond_list_audit_exports
• paybond_get_audit_export
• paybond_get_reputation_receipt
• paybond_get_portfolio_summary
• paybond_get_signed_portfolio_artifact
• paybond_get_fraud_assessment
• paybond_get_fraud_metrics
• paybond_get_a2a_agent_card
• paybond_list_a2a_task_contracts
• paybond_get_a2a_task_contract
• paybond_verify_agent_mandate_v1
• paybond_verify_agent_recognition_proof_v1
• paybond_get_settlement_receipt_v1
• paybond_verify_protocol_receipt_v1
• paybond_get_agent_receipt_v1
• paybond_verify_agent_receipt_v1
• paybond_validate_completion_evidence
• paybond_get_budget_remaining
• paybond_explain_policy

Spend and mutation tools (default --tool-policy spend-write; live-money tools such as paybond_fund_intent and paybond_confirm_settlement stay blocked unless explicitly allowlisted):

• paybond_verify_capability
• paybond_authorize_agent_spend
• paybond_bootstrap_sandbox_guardrail
• paybond_submit_sandbox_guardrail_evidence
• paybond_import_agent_mandate_v1
• paybond_create_intent
• paybond_create_spend_intent
• paybond_fund_intent
• paybond_submit_evidence
• paybond_submit_spend_evidence
• paybond_confirm_settlement

Install with a readonly surface for coding agents that only need tenant discovery, intent inspection, Signal/fraud reads, or compliance export job status:

paybond mcp install --host generic --scope project --tool-policy readonly

Local audit bundle verification (paybond audit exports verify <path> or paybond.audit.exports.verify(...)) is SDK/CLI only. MCP hosts cannot verify downloaded ZIP paths on disk. Compliance bundles that include agent_receipts may also contain PEF companion files (*.pef.json) alongside each signed receipt.

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.

paybond_get_budget_remaining and paybond_explain_policy call the side-effect-free gateway route POST /v1/spend/preflight. They evaluate the same spend-control policy as authorize without creating decisions, reservations, or approval requests. Use them before paybond_authorize_agent_spend when an agent needs remaining budget or a human-readable allow / approval_required / deny explanation. Matching CLI commands: paybond spend budget-remaining and paybond spend explain-policy.

paybond_verify_protocol_receipt_v1 is a read-only offline verify of a signed protocol-v2 authorization or settlement receipt (POST /protocol/v2/receipts/verify). Pass the full receipt object (not a receipt_id). Use paybond_verify_agent_mandate_v1 for mandate envelopes and paybond_verify_capability / paybond_authorize_agent_spend for Harbor capability gates. Fetch a settlement receipt first with paybond_get_settlement_receipt_v1 when you only have an intent UUID.

paybond_get_agent_receipt_v1 fetches a signed paybond.agent_receipt_v1 by receipt_id (tenant-bound GET /protocol/v2/agent-receipts/{receipt_id}). paybond_verify_agent_receipt_v1 runs the same offline operational-tier signature check as resources/read on paybond://receipt/{receipt_id}; pass optional validity_tier=primary|attested when you need a stronger bar. Continuity-chain, inclusion proofs, owner disclosure, and ACTA/PEF/SCITT adapters remain Kit TypeScript/Python and CLI/Gateway auditor surfaces—not MCP’s full job.

paybond_get_principal returns the tenant-bound service-account principal for the configured PAYBOND_API_KEY (tenant_id, subject, roles) via a read-only gateway GET. Use it when you need to confirm auth identity; call early as a prerequisite before Harbor escrow, Signal reads, or other tenant-scoped tools when tenant identity is unknown. Not required before every later call once tenant_id is already known. Do not use it when you need Harbor intent escrow detail—use paybond_get_intent instead when you have an intent_id. Do not use it for A2A discovery—use paybond_get_a2a_agent_card instead.

paybond_get_portfolio_summary returns a tenant-scoped Signal aggregate (counts, average score, volume, operators under review). Omit score_version to use the gateway default (1.0). Prefer paybond_get_signed_portfolio_artifact when you need a portable signed operator list for partner or verifier sharing, and paybond_get_reputation_receipt for one operator.

paybond_get_signed_portfolio_artifact returns a tenant-scoped signed Signal portfolio snapshot (operator list plus Ed25519 signing material) for offline verifier checks or partner sharing. Omit score_version to use the gateway default (1.0). Prefer paybond_get_portfolio_summary for unsigned aggregates, paybond_get_reputation_receipt for one operator, and paybond_get_fraud_assessment for fraud review posture.

paybond_get_fraud_metrics returns tenant-wide fraud backtesting metrics for a rolling window (24h default, or 7d / 30d). Unsupported windows fail with HTTP 400. Use paybond_get_fraud_assessment when you need one operator's fraud posture instead of tenant aggregates.

paybond_get_reputation_receipt fetches the signed Signal reputation receipt for one operator DID (GET /reputation/{operator_did}). Omit score_version to use the gateway default (1.0). Returns null when no receipt exists. Prefer paybond_get_portfolio_summary for tenant aggregates, paybond_get_signed_portfolio_artifact for a portable signed operator list, and paybond_get_fraud_assessment for fraud review posture.

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

1. Call paybond_create_spend_intent to create the signed spend intent.
2. If the intent is not funded immediately, call paybond_fund_intent.
3. Optionally call paybond_get_budget_remaining or paybond_explain_policy for a read-only preflight of remaining budget and policy outcome.
4. 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.
5. Call paybond_validate_completion_evidence with the completion preset and payload you plan to submit.
6. 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

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

Bundled smoke command

Validate the MCP authorize and evidence path without launching a stdio subprocess or an LLM:

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

The smoke uses in-process PaybondMCPServer.callTool() (TypeScript) or build_mcp_server().call_tool() (Python): sandbox bind, paybond_authorize_agent_spend, mock side-effect completion, and paybond_submit_sandbox_guardrail_evidence. Python requires the optional mcp extra (pip install "paybond-kit[mcp]").

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"
  }
}

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_..."
  }
}

Agent receipt resources (MCP)

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

Item	Value
URI template	paybond://receipt/{receipt_id}
MIME type	application/json
Source	Tenant-bound GET /protocol/v2/agent-receipts/{receipt_id}
Verify on read	Operational-tier signature check (schema, digest, Gateway Ed25519)

TypeScript and Python stdio servers:

• resources/templates/list — publishes the paybond://receipt/{receipt_id} template
• resources/read — fetches the signed paybond.agent_receipt_v1 JSON and verifies at the operational tier 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 by receipt_id
• paybond_verify_agent_receipt_v1 — offline verify of a receipt object; optional validity_tier (operational default, or primary / 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 are Kit TypeScript/Python, CLI, and Gateway auditor 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.

Related

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