inference-mcp

@bsvkey/inference-mcp

一个 MCP 服务，让任何 Agent 都能通过托管网关 inference.bsvkey.com 购买 Claude 和 Grok 推理服务，按 Token 计量并以 BSV 结算。零依赖（Node ≥ 18，使用全局 fetch）。这是一个轻量级 HTTP 客户端——它不会持有你的密钥或运行模型；每次调用都通过网关计费。

工具：list_models、infer、channel_balance、open_channel、x402_infer、xrp_infer。

两种支付方式：预付通道（infer，充值一次，按 Token 扣费），或通过 x402 按次支付（x402_infer——无需通道；Agent 使用自己的密钥，以 BSV 支付每个请求）。x402_infer 需要已充值的 WIF（wif 参数或 BSVKEY_WIF），以及可选的 @bsvkey/x402-bsv-client 和 @bsv/sdk 软件包（与本软件包一同安装）。

按次使用 XRP 支付，使用 xrp_infer：该工具会获取以 XRP 计价的报价（根据 XRP Ledger 自有的 XRP/RLUSD 市场定价），为准确金额签署一笔 XRP Payment；网关会在广播前验证该交易，等待验证完成（数秒），然后返回答案、结算交易和已签名回执。它需要已充值的 XRP 种子（xrpSeed 参数或 BSVKEY_XRP_SEED；可在 xrp.bsvkey.com/wallet 创建）以及可选的 xrpl 软件包（与本软件包一同安装；需要 Node 20.19+ 或 22.12+）。账户会保留 1 XRP 储备金，无法用于支出。

可验证的计量。 每次 infer 调用都会返回已签名的用量回执；安装可选软件包后，该工具会自动离线验证回执：结果包含 receiptVerified 和 meterVerified（值为 true、false + receiptCheck，或 null）。它会恢复经纪方密钥（从 GET /v1/receipt-key 固定）；将回执绑定到你调用的通道（根据你的 API 密钥，而非回执自行声明的内容）；检查序列号单调递增（无重放或间隙），且累计总额不超过充值金额；根据公布的费率重新计算费用（绝不会多收）；并根据固定的 bsvkey-meter/1 分词器，从消息和补全内容的确切字节重新计算 Token 数量。因此，通道支付已上链，计量和费用都可审计，无需相信经纪方的说法。

无人值守客户端需要了解以下四点：

• 验证失败时拒绝通过。 如果固定密钥的端点无法访问，receiptVerified 会是 null（未知），绝不会是 true——密钥固定端点不可用会让检查结果变为未知，而非可信。
• 提供你的充值金额。 设置 BSVKEY_FUNDED_SATS（或传入 fundedSats），值为你在链上充值的金额。回执中的 fundedSats 只是经纪方的声明；提供你自己的金额后，若回执声称的金额不同，就会被拒绝，并且累计总额会依据你实际支付的金额进行检查。
• 在重启后保留状态。 默认情况下，序列连续性只保存在内存中（在此进程看到第一张回执之前发生的重放无法被发现）。设置 BSVKEY_RECEIPT_STATE 为文件路径，即可持久保存每个通道的 seq/累计总额，从而在重启后检测重放。
• 回执就是账本。 GET /v1/channels/:id 余额端点可能比已签名回执延迟约 20 秒；应以回执为准，并将该端点视为缓存。

规范：https://inference.bsvkey.com/usage-receipts.md

快速开始

1. 充值通道一次：访问 https://inference.bsvkey.com（使用 BRC-100 钱包，或在页面中加载密钥）。复制返回的密钥：channelId:channelSecret。
2. 将 MCP 服务添加到你的 Agent 宿主（见下文），并将该密钥设为 BSVKEY_API_KEY。
3. 让你的 Agent 执行推理——它会调用 infer 并按 Token 付费。

list_models 和 open_channel 无需密钥即可使用；infer 和 channel_balance 需要已充值的通道密钥。

安装

已在 npm 上发布，名称为 @bsvkey/inference-mcp。

Claude Code

claude mcp add bsvkey-inference \
  --env BSVKEY_API_KEY=channelId:channelSecret \
  -- npx -y @bsvkey/inference-mcp

Claude Desktop / Codex / any MCP host (JSON 配置)

{
  "mcpServers": {
    "bsvkey-inference": {
      "command": "npx",
      "args": ["-y", "@bsvkey/inference-mcp"],
      "env": { "BSVKEY_API_KEY": "channelId:channelSecret" }
    }
  }
}

没有 npm？直接获取单文件服务（https://inference.bsvkey.com/mcp/server.js），并使用 "command": "node", "args": ["server.js"]。

配置（环境变量）

变量	默认值	含义
BSVKEY_BASE_URL	https://inference.bsvkey.com/v1	网关基础 URL（如果运行自己的部署，可将其设置为可自托管部署的地址）。
BSVKEY_API_KEY	—	已充值通道的 channelId:channelSecret。可选；也可以在每次调用时通过 apiKey 传入。
BSVKEY_FUNDED_SATS	—	你在链上为通道充值的金额。设置后，将以此金额验证收据，而不是使用由代理签名的 fundedSats。可选；也可在每次调用时传入 fundedSats。
BSVKEY_XRP_SEED	none	用于 xrp_infer 的 XRP 钱包种子。可选；也可以在每次调用时通过 xrpSeed 传入。不会离开此进程。
BSVKEY_RECEIPT_STATE	—	用于持久化每个通道收据连续性（序号 + 总额）的 JSON 文件路径，可跨重启保留。可选；未设置时仅保存在内存中。

错误

工具调用失败时会以一种固定格式返回 isError: true 和文本，因此 Agent 无需解析说明文字，即可根据代码分支处理：

error: <code> (<http status>): <message> [extra=value, ...]

代码	状态	工具	含义	处理方式
no_channel_key		infer、channel_balance	未提供 apiKey，也未设置 BSVKEY_API_KEY	在网站上开通通道（参见 open_channel）
invalid_channel	401 / 404	infer、channel_balance	通道不存在、密钥错误或通道已关闭	开通新通道
insufficient_balance	402	infer	此通道余额不足以覆盖本次调用的最坏情况；附加信息包含 requiredSats 和 balanceSats	在网站上充值，或降低 maxTokens / 关闭 webSearch
invalid_request	400	infer、x402_infer	未知模型或策略、模型提供商未启用，或输入无效	调用 list_models
upstream_failed	502	infer	模型提供商出错	不会扣费；重试或选择其他模型
no_wif		x402_infer	未提供 wif，也未设置 BSVKEY_WIF	传入已充值的密钥
verifier_missing		x402_infer	未安装 @bsvkey/x402-bsv-client / @bsv/sdk	npm i @bsvkey/x402-bsv-client @bsv/sdk
payment_failed	402	x402_infer	支付未结算（例如，密钥对应的地址未充值）；附加信息包含 reason	为该地址充值；不会花费任何资金
upstream_failed	502	x402_infer	支付已结算，但之后提供商出错；附加信息包含 settlementTxid	不会自动退款：请将 txid 发送至 [email protected]
no_xrp_seed		xrp_infer	未提供 xrpSeed，也未设置 BSVKEY_XRP_SEED	传入已充值的 XRP 种子
xrpl_missing		xrp_infer	未安装 xrpl 包	npm i xrpl
node_too_old		xrp_infer	Node 版本低于 20.19 / 22.12，而 xrpl 包需要这些版本	升级 Node（其他工具可在 Node 18+ 上运行）
insufficient_xrp		xrp_infer	钱包尚未激活，或无法支付高于 1 XRP 储备金的报价	为钱包充值；不会花费任何资金
payment_failed	402	xrp_infer	支付在广播前被拒绝或未结算；附加信息包含 reason	除非包含结算交易，否则不会花费任何资金
upstream_failed	502	xrp_infer	支付已结算，但之后提供商出错；附加信息包含结算交易	不会自动退款：请将交易发送至 [email protected]

使用预付通道时，任何错误都不会扣费。成功的 infer 仍可能报告 receiptVerified: false（签名收据验证失败；参见 receiptCheck）或 null（无法验证：缺少验证器，或收据密钥端点不可用）。

思考模型（claude-sonnet-5、claude-opus-5、claude-opus-5-5、 claude-fable-5-1）会将隐藏推理内容计为输出，且这些模型的 maxTokens 至少会提高至 1024。

验证配置是否生效（无需密钥）

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_models","arguments":{}}}' \
  | node server.js

市场列表简介

BSV Inference —— 使用 BSV 结算，按 Token 付费调用 Claude 和 Grok。预先为通道充值一次，即可按 Token 计费，无需订阅、账户或银行卡。兼容 OpenAI，可选实时网络搜索，并支持链上结算。MCP + 可移植的 SKILL.md。

发布（运营方）

• 已在 npm 上架，归属 @bsvkey 组织（所有者：interence）。首次发布版本：v1.0.0。
• 发布更新：在 package.json 中提升 version，然后运行 npm publish --access public（需通过双重验证／安全密钥提示）。
• 规范源代码：https://github.com/BSVKey/inference-mcp
• 若要在技能市场（例如 bopen.ai）上架，请提交 SKILL.md 和此 README。