paybondpaybond
Sign in

MCP server

Run the tenant-bound Paybond MCP server for internal agent runtimes and MCP-compatible hosts.

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.

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

Python

pip install "paybond-kit[mcp]"

TypeScript

npm install @paybond/kit

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_ENV_FILE=".env.local"

Run

Python

paybond-mcp-server

TypeScript

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_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

  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. After the guarded work completes, call paybond_submit_spend_evidence.

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_submit_sandbox_guardrail_evidence with the sandbox intent_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"
  }
}

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