x207

@x207/mcp

一个用于 x207 的 MCP 服务。x207 是 NEAR 上 x402 Agent 支付的互惠信用结算层。它允许 Claude 等模型读取一个信用圈的信息：规则和成员、某个成员的额度和限额、某个周期的结果、经过合约检查的清算提案、市场以及某个订单。

状态：版本 0.0.1，预发布版。默认情况下，服务只有读取工具：不签名、不发送任何内容，也不持有密钥。八个写入工具仅在 stdio 上提供，只有在你启用它们时才可用，且必须通过下方的防护措施。需要 Node 22.22.2 或更高版本。

六个读取工具

工具	功能	读取内容
x207_circle_overview	查看信用圈及其规则和成员	合约视图 get_circle、get_params；读取 API GET /members（没有读取 API 时使用视图 list_members）
x207_member_inspect	查看某个成员的状态、质押、额度和信用限额	读取 API GET /members/{account} 和 GET /members/{account}/limits（没有读取 API 时使用视图 member 和 limit）
x207_epoch_report	查看某个清算周期（默认当前周期）的阶段、截止时间、清算比例和结算情况	合约视图 get_epoch；读取 API GET /epochs/{n}、GET /epochs/{n}/metrics、GET /epochs/{n}/settlements（没有读取 API 时使用视图 list_positions）
x207_simulate_clearing	检查拟议的清算是否有效，以及它会清算哪些内容	合约视图 simulate_clearing
x207_search_listings	按账户、资产类型和类别筛选市场挂牌	读取 API GET /listings（需要读取 API）
x207_order_status	查看某个服务订单，或按参与方和状态查看订单列表	读取 API GET /orders/{hash} 和 GET /orders（需要读取 API）

六个工具都标记为 readOnlyHint: true。信用金额以最小单位的十进制字符串表示（6 位小数）。工具调用失败时会返回错误结果，并附上简短原因；无法读取的部分答案（例如读取 API 不可用）会在 warnings 中说明，同时返回其余内容。超过 100,000 个字符的结果会被截断，并注明这一点。

配置

所有配置均来自环境变量。没有任何变量会保存密钥。

变量	含义
X207_CIRCLE_CONTRACT	必填。 信用圈合约账户，例如 x207-v013.testnet。
X207_CIRCLE_ID	读取 API 路径中的信用圈 ID。默认为 agents-main。
X207_RPC_URL	NEAR JSON-RPC 端点，使用逗号分隔，并按顺序尝试。默认值：对于 .testnet 合约，依次为 https://rpc.testnet.fastnear.com 和 https://rpc.testnet.near.org；否则使用 @x207/core 的主网端点。端点调用失败或返回 429 时会切换到下一个。
X207_BACKEND_URL	x207 读取 API 的基础 URL，例如 http://127.0.0.1:8080。可选；未设置时，x207_search_listings 和 x207_order_status 会说明缺少什么，其他工具则从合约获取信息。
X207_TIMEOUT_MS	单次 RPC 或读取 API 调用的超时时间。默认为 10000。

在 Claude Desktop 中使用（stdio）

将服务添加到 claude_desktop_config.json（Claude Desktop）或 .cursor/mcp.json（Cursor）中。npx 会在首次运行时获取软件包，因此无需安装：

{
  "mcpServers": {
    "x207": {
      "command": "npx",
      "args": ["-y", "@x207/mcp"],
      "env": {
        "X207_CIRCLE_CONTRACT": "x207-v013.testnet",
        "X207_BACKEND_URL": "http://127.0.0.1:8080"
      }
    }
  }
}

请使用 0.0.2 或更高版本：0.0.1 发布时未包含 x207-mcp 命令。若要在本机保留一份副本，请运行 npm install -g @x207/mcp，并使用 "command": "x207-mcp"，不设置 args。若使用仓库检出版本，请先运行一次 npm run build，然后将 command 指向 node，并设置 "args": ["/path/to/sdk/packages/mcp/dist/cli.js"]。重启 Claude Desktop，然后可以这样提问：“概述一下 x207 信用圈”“检查成员 alice.x207-v013.testnet”或“报告第 1 个周期”。

写入工具（仅限 stdio，默认关闭）

设置 X207_MCP_WRITE=1，并在环境中提供 Agent 的账户和密钥。无论环境设置如何，HTTP 服务都不会提供这些工具。

工具	功能	使用的签名密钥	启用条件
x207_pay_request	获取 URL；如果收到 x207 402 响应，则签署信用凭证并重试请求。卖方的协调方会登记该凭证；此工具不会向链上发送任何内容。	凭证密钥	存在凭证密钥
x207_list_offer	签署一则挂牌信息（Agent 提供什么、寻求什么），并发布到市场簿。	凭证密钥	存在凭证密钥和 X207_BACKEND_URL
x207_make_offer	签署针对某则挂牌的报价或还价（in_reply_to），并发布。	凭证密钥	存在凭证密钥和 X207_BACKEND_URL
x207_accept_offer	在后端预览接受操作，检查 Agent 将支付的金额，签署交易包并提交接受操作。	凭证密钥	存在凭证密钥和 X207_BACKEND_URL
x207_confirm_milestone	为订单的里程碑（confirmed、disputed、delivered、cancelled）签署通知并提交。	凭证密钥	存在凭证密钥和 X207_BACKEND_URL
x207_join	加入圈子并质押 USDT：先通过 join 支付 0.35 NEAR 的存储押金，再调用 ft_transfer_call。	NEAR 密钥	X207_ALLOW_OUTFLOWS=1 且 X207_ALLOW_FULL_ACCESS_KEY=1
x207_settle	支付 Agent 欠付的某个周期的剩余金额（不超过应付金额）：通过 ft_transfer_call 携带 settle 消息。	NEAR 密钥	X207_ALLOW_OUTFLOWS=1 且 X207_ALLOW_FULL_ACCESS_KEY=1
x207_claim	领取 Agent 在某个周期应得的金额，可存入自己的账户或 Intents 余额：通过 claim 携带 1 yoctoNEAR。	NEAR 密钥	X207_ALLOW_FULL_ACCESS_KEY=1

缺少密钥或开关的工具将完全不会列出。凭证密钥是 Agent 的链下 ed25519 密钥（ed25519:<base58>）；它不是 NEAR 访问密钥。NEAR 密钥是 Agent 账户的访问密钥。

变量	含义
X207_MCP_WRITE	设为 1 可启用写入工具。默认：关闭。
X207_AGENT_ACCOUNT	Agent 的 NEAR 账户，是圈子成员。设置 X207_MCP_WRITE=1 时必填。
X207_AGENT_VOUCHER_KEY	凭证私钥。用于签署凭证、挂牌信息、报价、接受操作和通知。
X207_AGENT_NEAR_KEY	Agent 账户的 NEAR 私钥。仅用于签署 x207_join、x207_settle 和 x207_claim 的交易。
X207_MAX_SPEND_SESSION	Agent 在服务器单次运行期间最多可承诺的金额，以信用单位计（6 位小数）。默认值为 1000000（1 个信用单位）。
X207_MAX_PRICE_PER_CALL	单笔付款、报价或里程碑金额的上限。默认值为 100000（0.1 个信用单位）。
X207_ALLOWED_COUNTERPARTIES	Agent 可以交易的账户，以逗号分隔。留空：可与圈子中的任意活跃成员交易。
X207_ALLOW_OUTFLOWS	设为 1 可启用 x207_join 和 x207_settle，这两个工具会将 USDT 从 Agent 转入圈子。默认关闭。
X207_ALLOW_FULL_ACCESS_KEY	设为 1 可允许 NEAR 密钥使用完全访问密钥。默认关闭。
X207_ALLOW_PRIVATE_URLS	设为 1 可让 x207_pay_request 获取此计算机或专用网络中的 URL，供你自行运行的卖方使用。默认关闭。

防护措施

1. 会话预算。 每张签署的凭证、每笔接受操作将支付的款项、每个确认的里程碑，以及支付的每笔质押金或剩余款项，都会计入 X207_MAX_SPEND_SESSION。无法纳入预算的承诺会在签署前被拒绝；签署后未能完成的承诺会退回。
2. 每次调用的价格。 超过 X207_MAX_PRICE_PER_CALL 的金额会被拒绝。402 中的价格由卖方提供，因此服务端不会信任该价格：检查会在签署凭证前，针对需求运行。
3. 高风险工具默认关闭。 在操作员设置 X207_ALLOW_OUTFLOWS=1 之前，x207_join 和 x207_settle 都保持关闭。
4. 交易对手。 付款、报价、接受操作或里程碑的另一方必须是圈子中的活跃成员（合约视图）；如果设置了 X207_ALLOWED_COUNTERPARTIES 列表，对方还必须在该列表中，且绝不能是 Agent 自身。
5. 网络。 提供给 x207_pay_request 的 URL 来自模型，因此可能来自提示词注入。如果 URL 的主机是本机回环、私有、链路本地（云机器的元数据服务）、运营商级 NAT、多播或未指定地址，或名称为 localhost、*.local 和 *.internal，工具都会拒绝。工具不会跟随重定向（响应会说明重定向的目标），每次调用限时 30 秒，最多读取 1 MiB 的响应。对于运行在你自己机器上的卖方，设置 X207_ALLOW_PRIVATE_URLS=1 可关闭地址检查。
6. 密钥。 密钥仅从环境变量读取。任何结果、错误或日志行都不会包含密钥：服务端会从所有外发文本中清除已配置的密钥，以及任何符合 ed25519 密钥格式的内容。发送交易前，服务端会读取 NEAR 密钥的权限（view_access_key）。函数调用密钥不能附带存款，而加入、质押、结算和领取操作都会附带存款（这是 NEAR 协议规则），因此使用函数调用密钥时，这些工具会拒绝操作且不会发送任何内容。使用完全访问密钥时，只有在设置 X207_ALLOW_FULL_ACCESS_KEY=1 后这些工具才会运行；请使用余额较少的专用 Agent 账户。使用凭证密钥签名的工具不会发送交易，因此完全不需要 NEAR 密钥。

此外：后端会返回套餐条款及其哈希，x207_accept_offer 在哈希与条款不匹配时会拒绝；如果账本返回的商品列表项的哈希与请求的哈希不匹配，x207_make_offer 也会拒绝。

安全上限：Agent 账户的余额就是最大可能损失

函数调用密钥无法附加 NEAR 存款，因此需要发送存款的工具（x207_join、x207_settle、x207_claim）需要 Agent 账户的完全访问密钥。完全访问密钥可以执行账户所能执行的任何操作，上述防护措施都无法限制被盗用或滥用的密钥在此服务端之外执行的操作。因此，请使用专用 Agent 账户，账户中只存放 Agent 可能损失的资金：该账户持有的 NEAR 和 USDT 就是可能损失的上限。会话预算和价格上限可防范行为异常的模型，但无法防范持有密钥的人。若 Agent 只需付款、上架、报价、接受和确认，请不要设置 X207_ALLOW_FULL_ACCESS_KEY，并保持这三个工具关闭：这些工具使用凭证密钥签名，从不需要 NEAR 密钥。

Claude Desktop 与写入工具

{
  "mcpServers": {
    "x207-agent": {
      "command": "x207-mcp",
      "env": {
        "X207_CIRCLE_CONTRACT": "x207-v013.testnet",
        "X207_BACKEND_URL": "http://127.0.0.1:8080",
        "X207_MCP_WRITE": "1",
        "X207_AGENT_ACCOUNT": "agent.x207-v013.testnet",
        "X207_AGENT_VOUCHER_KEY": "ed25519:…",
        "X207_MAX_SPEND_SESSION": "500000",
        "X207_MAX_PRICE_PER_CALL": "50000"
      }
    }
  }
}

不要将密钥放入任何要提交的文件中。然后可以尝试提出以下请求：“以 0.05 credit 列出一项翻译服务”、“向 https://seller.example/api/summarize 付款”或“确认订单 … 的里程碑 1”。

通过 Streamable HTTP 使用

X207_CIRCLE_CONTRACT=x207-v013.testnet X207_BACKEND_URL=http://127.0.0.1:8080 x207-mcp --http --port 3207

端点为 POST http://127.0.0.1:3207/mcp。它是无状态的（没有会话），且仅提供读取工具，因此可以展示给任何已经能够读取合约和读取 API 的人。GET /healthz 返回 200。除非 --host 另有指定，否则它会监听 127.0.0.1；在对外开放之前，请在其前面设置带 TLS 和速率限制的反向代理。使用环回地址时，它只为环回地址的 Host 名称（127.0.0.1、localhost、[::1]）提供服务，因此网页无法通过 DNS 重绑定访问它；在代理后面时，设置 X207_ALLOWED_HOSTS=mcp.example.org（以逗号分隔）即可仅为指定名称提供服务。

如需通过 MCP Inspector 试用：

npx @modelcontextprotocol/inspector --cli http://127.0.0.1:3207/mcp --transport http --method tools/list

作为库使用

import { configFromEnv, createX207McpServer } from "@x207/mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = createX207McpServer(configFromEnv(), "stdio"); // "http" gives the read tools only
await server.connect(new StdioServerTransport());

输出示例（真实数据）

针对圈子 x207-v013.testnet 运行（从测试网 RPC 获取合约视图），并使用本地读取 API（backend），该 API 提供了这个圈子的读取模型及其三个演示账户。以下工具结果均为真实数据；较长的字段（签名、订单规范的哈希）已省略，并由保留的键标示。

使用 {"account": "x207-demo-seller.testnet"} 调用 x207_member_inspect：

{
  "account": "x207-demo-seller.testnet",
  "member": {
    "account": "x207-demo-seller.testnet",
    "status": "active",
    "stake": "100000000",
    "limit": "80000000",
    "outstandingDebt": "0",
    "headroom": "80000000",
    "joinedAt": "2026-11-04T04:25:29Z"
  },
  "limits": {
    "items": [
      {
        "epoch": null,
        "oldLimit": "0",
        "newLimit": "80000000",
        "status": "active",
        "reason": "stake",
        "blockHeight": 276145725
      }
    ]
  },
  "source": "read API",
  "warnings": []
}

使用 {"account": "x207-demo-seller.testnet", "limit": 1} 调用 x207_search_listings：

{
  "items": [
    {
      "listingHash": "6eb11d3068ba7e5f84503d9d454242e891fedd676ffd1e03324d4889a304fa41",
      "account": "x207-demo-seller.testnet",
      "offer": {
        "assetType": "near-rpc:access",
        "assetClass": "B",
        "quantity": 1,
        "value": "2000000"
      },
      "want": {
        "assetType": "usdc",
        "assetClass": "A",
        "quantity": 1,
        "value": "2000000"
      },
      "expiresAt": "2026-12-31T00:00:00Z",
      "status": "open"
    }
  ],
  "nextCursor": "eyJhIjoxfQ"
}

使用 x207-demo-buyer.testnet 订单的 hash 调用 x207_order_status：

{
  "orderHash": "332b9bddcc9e17578ba2e55b1fd7d8c0323f7a8225f4ebc03a83b7c0668840a3",
  "buyer": "x207-demo-buyer.testnet",
  "seller": "x207-demo-seller.testnet",
  "status": "open",
  "budget": "30000000",
  "unit": "credit",
  "decimals": 6,
  "milestones": [
    {
      "index": 1,
      "amount": "10000000",
      "dueAt": 1796947200,
      "status": "open"
    },
    {
      "index": 2,
      "amount": "20000000",
      "dueAt": 1797811200,
      "status": "open"
    }
  ]
}

即使没有读取 API，同一服务仍会仅从合约中返回 x207_circle_overview、x207_member_inspect、x207_epoch_report 和 x207_simulate_clearing 的结果：在 x207-v013.testnet 上，x207_circle_overview 返回 member_count 24 和规则（epoch_length 600、手续费 10 和 5 bps、prune_delay_epochs 2）；第 1 个 epoch 的 x207_epoch_report 显示其阶段为 finalized，包含 210 条边和 15 名参与者。

安全

• 读取工具只调用合约视图和发送 GET 请求；其中不存在签名、发送或更改任何内容的代码路径。上文介绍了写入工具，且它们默认关闭。
• 调用前会检查输入：账户 ID、哈希、以整数形式表示的字符串金额、模拟最多 300 条边、每页最多 200 项。
• 路径段会经过编码，因此输入无法访问读取 API 的其他端点。
• 默认情况下，测试网上的圈子会从测试网端点读取数据。

开发

npm run build          # from the repository root of sdk
npx vitest run packages/mcp

测试会通过模拟的 fetch 模拟 NEAR RPC 和读取 API，在本地端口运行 HTTP 传输，并通过标准输入/输出驱动构建好的 x207-mcp（如果尚未构建 dist，该测试会跳过）。

许可证

Apache-2.0