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_validate_completion_evidence

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.

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

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. 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.
4. Call paybond_validate_completion_evidence with the completion preset and payload you plan to submit.
5. 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 + 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)

The MCP server exposes a resource template for agent-to-agent handoff of signed action receipts:

Item	Value
URI template	paybond://receipt/{receipt_id}
MIME type	application/json
Source	Tenant-bound GET /protocol/v2/agent-receipts/{receipt_id}

TypeScript stdio server handlers:

• resources/templates/list — publishes the paybond://receipt/{receipt_id} template
• resources/read — fetches and returns the signed paybond.agent_receipt_v1 JSON

Python FastMCP registers the same template via @server.resource("paybond://receipt/{receipt_id}").

Hosts can pass a receipt URI between agents without embedding the full JSON in prompts. Always verify signatures before trusting receipt contents.

Related

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