Paybond MCP Server

@paybond/kit

别让你的 AI Agent 意外花掉 20,000 美元。

无人监督的 Agent 可以预订旅行、调用付费 API 或购买算力，也可能不断循环调用“已获批准”的工具，直到预算耗尽——每笔扣款都成功，却没有任何证据证明工作已经交付。仅靠单笔交易限额无法阻止这种情况。

@paybond/kit 是用于委托式 Agent 支出控制的 TypeScript SDK：在付费工具运行之前，根据限定预算和策略进行授权；然后仅在获得已签名的完成证据后才放款或退款。只需在任何付费工具调用前后加入三行代码：authorize → execute → verify。保留现有运行时。保留现有支付渠道（优先使用 Stripe Connect / x402；也支持 Stripe ACH Direct Debit 和 USDC-on-Base）。你将获得支出授权、证据门控结算、退款、争议处理，以及可移植的签名收据，无需自行构建证据门控放款中间件。

在底层，Kit 会打开托管 Gateway 会话、验证能力令牌、签署意图和证据载荷，并读取租户范围内的 Signal、欺诈、账本、协议和 A2A 数据，同时为常见的 Agent 运行时提供适配器。

文档 · TypeScript 快速入门 · 支持矩阵 · 免费沙盒注册 · Python 软件包

何时使用 Paybond

只要 AI Agent 能够转移资金，而你需要确保支出不超出预算（而不只是进行令牌用量计量），就可以使用 Paybond Kit——适用于 Agent 支付与商务、工具调用支出限额、放款前的结果证据以及可供审计的记录；兼容 OpenAI、Gemini、Claude/Anthropic、Vercel AI SDK、LangGraph、MCP 主机和自定义运行时，并通过租户已在使用的支付渠道结算。

• 在支出需要根据限定预算进行授权、需要证据门控的放款／退款／争议处理，或需要可供审计的收据时，使用 Paybond Kit。
• 对于不会涉及资金转移的简单大模型令牌或用量限额，请使用模型提供商原生的用量或账单控制功能。

从这里开始（约 60 秒启动沙盒）

无需账户，也无需 API 密钥——在本地演练完整的 authorize → execute → evidence 流程，然后打开跟踪面板：

npm install @paybond/kit
npx -p @paybond/kit paybond dev loop --offline
npx -p @paybond/kit paybond dev trace

paybond dev trace 会在 http://127.0.0.1:9477 显示中间件时间线。

若要通过真实的托管沙盒 Gateway 尝试相同流程，请先创建免费的 Free Developer 工作区（如果你还没有 Paybond 账户；无需信用卡），然后：

npx -p @paybond/kit paybond login
npx -p @paybond/kit paybond-init --preset paid-tool-guard --framework provider-agnostic --out paybond-paid-tool-guard.ts
npx -p @paybond/kit paybond agent sandbox smoke \
  --operation travel.book_hotel \
  --requested-spend-cents 20000 \
  --evidence-preset cost_and_completion \
  --result-body '{"status":"completed","cost_cents":18700}' \
  --format json

paybond login 会打开浏览器设备授权步骤；工作区所有者（注册后立即成为所有者的你）批准后，CLI 会将沙盒 PAYBOND_API_KEY 写入 .env.local。

为 MCP 主机启动绑定租户的 MCP 服务（在运行 paybond login 后）：

npx -y -p @paybond/kit paybond-mcp-server

面向编码 Agent 和大模型的完整发现指南位于 https://paybond.ai/llms.txt；编码 Agent 配置还提供了整洁的 Markdown 镜像，地址为 https://paybond.ai/docs/kit/coding-agent-setup.md。

安装

npm install @paybond/kit

@paybond/kit 是适用于 Node.js 运行时的纯 ESM 软件包。在 Node ESM / NodeNext 项目或兼容的打包工具中使用 import。

可选框架集成

核心包足以支持 Harbor 会话、支出限制、策略文件和 paybond agent sandbox smoke。仅当导入框架子路径时，才安装可选的对等依赖：

子路径	对等依赖
@paybond/kit/vercel-ai	ai
@paybond/kit/openai-agents	@openai/agents
@paybond/kit/langgraph	@langchain/core、@langchain/langgraph
@paybond/kit/claude-agents	@anthropic-ai/claude-agent-sdk
@paybond/kit/google-adk	@google/adk
@paybond/kit/mastra	@mastra/core
@paybond/kit/cloudflare-agents	agents、ai
@paybond/kit/mcp、@paybond/kit/agent、@paybond/kit/policy	无 — 无需额外对等依赖

npm install ai @openai/agents @langchain/core @langchain/langgraph @anthropic-ai/claude-agent-sdk @google/adk @mastra/core agents

精简的 npm 封装包（@paybond/vercel-ai、@paybond/langgraph、@paybond/openai-agents、@paybond/claude-agents、@paybond/google-adk、@paybond/mastra、@paybond/cloudflare-agents、@paybond/agent、@paybond/mcp）会重新导出相同的子路径，方便在 npm 上发现 — 请安装与你的框架匹配的封装包，而不是安装上方列出的全部对等依赖。

开源与供应链

@paybond/kit 以开源软件形式发布，采用 Apache 2.0 许可证。已发布的 npm 包在 LICENSE 中包含完整的许可证文本。标记版本的发布会使用 npm publish --provenance，因此 npm 的 来源证明 选项卡会将此 tarball 链接到构建它的确切 GitHub Actions 运行记录和提交。请参阅包来源证明与验证，以确认构建或获取发布版本的 SBOM。

要求

• Node.js 22+
• paybond_sk_sandbox_... 或 paybond_sk_live_... 服务帐户 API 密钥
• 用于创建意图或提交证据：由你的应用持有的 32 字节 Ed25519 签名种子

创建用于本地开发的沙盒密钥：

npx -p @paybond/kit paybond login

paybond login 会将沙盒 PAYBOND_API_KEY 写入 .env.local，文件模式为 0600；必要时会将默认的 .env.local 目标添加到 .gitignore，并且除非传入 --force，否则不会覆盖现有密钥。在 Git 仓库中的自定义环境文件路径必须已被忽略。Live 生产密钥由 Console 中的租户管理员创建，并存储在部署密钥管理器中。

CLI

此包附带 paybond CLI（paybond、paybond-init、paybond-kit-login、paybond-mcp-server）。

从内置模板搭建起始项目：

npx -p @paybond/kit paybond init --template travel-agent
npm install
npm run smoke

无需应用代码即可进行端到端沙盒冒烟测试（绑定 + 执行 + 证据）：

npx -p @paybond/kit paybond agent sandbox smoke \
  --policy-file paybond.policy.yaml \
  --result-body '{"status":"completed","cost_cents":18700}' \
  --format json

使用 --policy-file 时，Kit 会从工具的 evidence_preset 发送 completion_preset，并省略 evidence_schema 和 template_id（Gateway 会拒绝冲突的引导字段）。需要 @paybond/kit 0.11.11+。

agent sandbox smoke 只需要 @paybond/kit。框架演示命令（例如 agent demo vercel-ai smoke）会按需加载其可选对等依赖。

离线本地开发循环和跟踪仪表板：

npx -p @paybond/kit paybond dev loop --offline
npx -p @paybond/kit paybond dev trace

首个护栏脚手架

当你有一个付费工具，并希望在沙盒中使用 Paybond 护栏时，请使用此功能：

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

生成的集成会从环境中打开 Paybond，在 PAYBOND_API_KEY 尚未设置时加载 .env.local，引导创建沙盒护栏意图，包装你的付费工具处理程序，并提交沙盒证据。它不会生成付费工具的实现。Free Developer 仅支持沙盒；Live 结算通道从付费生产计划开始提供。

租户隔离

每个会话都绑定到由网关认证的服务帐户内省所回显的租户领域。

• 常规 SDK 用法中不要手动传入租户 ID。
• 每个租户/服务帐户构造一个 Paybond 会话。
• 将 Harbor 返回的任何租户或意图回显不匹配视为严重级别为零的缺陷。

快速开始

import { Paybond } from "@paybond/kit";

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`missing ${name}`);
  }
  return value;
}

const paybond = await Paybond.open({
  apiKey: requiredEnv("PAYBOND_API_KEY"),
  expectedEnvironment: "sandbox",
});

try {
  console.log("tenant realm:", paybond.harbor.tenantId);
} finally {
  await paybond.aclose();
}

Agent 支出控制

当 Agent 工作流需要委托式支出防护、工具调用预算检查、付费 API 或供应商操作审批、证据、释放／退款逻辑、争议处理或可供审计的收据时，请使用 Paybond Kit。

import { Paybond } from "@paybond/kit";

const paybond = await Paybond.open({
  apiKey: process.env.PAYBOND_API_KEY!,
  expectedEnvironment: "sandbox",
});

const guardrail = await paybond.guardrails.bootstrapSandbox({
  operation: "travel.book_hotel",
  requestedSpendCents: 20_000,
  currency: "usd",
});

const guard = paybond.spendGuard(guardrail.intent_id, guardrail.capability_token);
const guardedTool = guard.guardTool(
  {
    operation: guardrail.operation,
    requestedSpendCents: guardrail.requested_spend_cents,
  },
  async (input) => bookHotel(input),
);

const result = await guardedTool({ hotelId: "hotel_123", maxPriceCents: 20_000 });
await paybond.guardrails.submitSandboxEvidence({
  intentId: guardrail.intent_id,
  payload: { result, sandbox: true },
});

paybond.harbor 和 paybond.guardrails 客户端由 Paybond.open(...) 创建，并绑定到通过服务账户 API 密钥解析出的租户。生产环境集成可从 paybond.intents.create(...) 读取 capability_token；也可在满足 x402_usdc_base 付款质询后，从 paybond.intents.fund(...) 读取。

软件包包含的内容

核心 SDK：

• Paybond.open(...)：仅通过 API 密钥创建、由租户派生的托管会话
• HarborClient：用于能力验证、创建意图、通过 x402 充值、提交证据和读取账本
• 从一个服务账户 API 密钥开启的 Paybond 会话上的 paybond.signal 和 paybond.fraud
• PaybondIntents 辅助工具：用于创建由主体签名的意图、通过 x402 充值、提交由收款方签名的证据，以及确认结算
• PaybondSpendGuard、authorizeSpend 和 guardTool：用于提供以支出命名、围绕能力验证的封装
• 与运行时无关的别名及框架别名：paybondAgentToolSpendGuard、paybondRuntimeNeutralToolSpendGuard、paybondLangGraphToolSpendGuard 和 paybondMCPToolSpendGuard
• paybondRuntimeToolCallAdapter：适用于提供工具调用对象及由应用负责执行器的 Agent SDK 和自定义运行时

Agent 中间件（@paybond/kit/agent）和框架子路径（vercel-ai、openai-agents、langgraph、claude-agents、mcp、policy）：

• PaybondAgentRun、工具注册表、拦截器和策略文件绑定
• 带可选对等依赖项的框架适配器（见上表）
• paybond init、paybond agent run bind、paybond agent tool execute 和 paybond agent sandbox smoke

网关和信任辅助工具：

• GatewaySignalClient 和 ServiceAccountSignalSession：用于租户范围内的 Signal 读取和签名投资组合数据
• GatewayFraudClient 和 ServiceAccountFraudSession：用于租户范围内的欺诈评估、审核队列、审核事件、指标和释放门控配置
• 协议 v2 辅助工具：用于授权验证、防重放识别证明验证、收据读取和 A2A 发现
• paybond login：用于沙盒设备审批和在本地设置 .env.local API 密钥
• paybond-mcp-server：用于向任何兼容 MCP 的宿主提供绑定租户的 MCP 工具
• paybond-init：用于生成 Paybond 防护集成辅助工具

面向 Agent 的接口与模型提供商无关。Paybond 验证工具操作和租户范围，而不验证工具调用来自 OpenAI、Anthropic、Gemini、本地模型还是其他运行时。

allowedTools 的值是你自己的工具或操作名称，而非 Paybond 自有目录。Harbor 会针对你创建意图时选择的名称执行字符串匹配。

创建意图时的 settlementRail 是由主体签名的结算通道请求。Stripe 目的地和 x402 接收地址由租户在服务端配置，并且绝不会由 SDK 调用方提供。

协议 v2 接口以信任为先：签名授权、识别证明和收据可跨受支持的结算适配器使用，而不会将任何单一通道视为产品边界。

网关支持的协议辅助工具在网关返回 JSON 错误信封时会抛出 ProtocolHttpError，其中包含已解析的 errorCode 和 errorMessage 字段。受识别验证门控的流程会明确显示 unregistered_key、revoked_key、mandate_agent_key_mismatch 和 protocol_binding_mismatch。

不包含的内容

• 不包含运营方级别的结算或控制台工作流
• 不捆绑大模型或模型运行时——请自备 Agent 框架，并在需要时安装可选的对等依赖项
• 不提供特定于模型提供商的 MCP 封装；MCP 服务与宿主无关，可适用于任何兼容 MCP 的运行时

文档

• Agent 和 LLM 发现指南：https://paybond.ai/llms.txt
• 编码 Agent 设置（Markdown 镜像）：https://paybond.ai/docs/kit/coding-agent-setup.md
• 长篇文档：https://paybond.ai/docs/kit
• Agent 快速入门：https://paybond.ai/docs/kit/quickstart-agent
• 一条命令设置防护措施：https://paybond.ai/docs/kit/one-command-guardrails
• TypeScript 快速入门：https://paybond.ai/docs/kit/quickstart-typescript
• TypeScript SDK 参考：https://paybond.ai/docs/kit/sdk-reference-typescript
• 支持矩阵（语言、框架、轨道）：https://paybond.ai/docs/kit/support-matrix
• 软件包来源和验证：https://paybond.ai/docs/kit/package-provenance
• MCP 服务指南：https://paybond.ai/docs/kit/mcp-server
• Agent 运行时教程：https://paybond.ai/docs/kit/agent-runtime-tutorial
• TypeScript 示例项目：https://paybond.ai/docs/kit/examples-typescript
• 免费开发者沙盒注册：https://paybond.ai/signup

发布验证

对于从源代码检出版本开展工作的维护者，发布验证位于此软件包目录中：

npm run verify:release

此操作会运行测试、执行干净构建、检查打包后的 tarball 是否包含多余文件，并针对打包后的软件包编译一个临时使用者应用。