MCP

命令 anet mcp 通过标准输入输出提供 Model Context Protocol 服务。它向 MCP 客户端(通常是编码 Agent)提供一组固定的 14 个工具,客户端借此在网络上查找 Agent、发送并跟踪 A2A 任务、应答其他 Agent 发给本节点的任务,以及读取节点的状态。

本页说明该服务器如何运行、在 anet agents wire 未覆盖的客户端中如何配置、如何使用这些工具,以及哪些操作被有意设为不可用。每个工具的参数列于 MCP 工具。

服务器的性质 

anet mcp 不属于守护进程。MCP 客户端在会话期间将其作为子进程启动。该进程把每次工具调用转发给本地守护进程的控制面,方式与命令行界面相同,并在客户端关闭连接时结束。守护进程继续运行,并保管密钥、账本和入站策略。随客户端一同结束的入口,存续时间不会超过客户端所持有的授权。

工具以 A2A 的概念命名。任务通过 list_agents 和 get_agent_card 查找,通过 send_message 启动或继续,并通过 wait_task、get_task 和 list_tasks 跟踪。结果是 A2A Task,按守护进程生成的原样转发。了解 A2A 的客户端无需再对结果的结构做任何额外说明。

没有守护进程应答时,服务器拒绝启动。若客户端连接成功但每次调用都失败,会让模型误以为工具已损坏;连接失败的客户端则会把运维人员引向问题所在的守护进程。消息会指明数据目录和启动节点的命令:

$ anet up

配置客户端 

对于 Claude Code、Codex、Cursor、opencode、Hermes 和 WorkBuddy,条目由 anet agents wire 写入(参见接入编码 Agent)。其他支持 stdio 传输的 MCP 客户端,按下列值配置:

设置	值
命令	`anet` 二进制文件的绝对路径
参数	`mcp`
环境变量	`ANET_DATA_DIR` 设置为该身份的数据目录(默认 `~/.anet`)
工具超时	客户端文档载明相应设置时,建议至少 900 秒,参见等待。Gemini CLI 的 `timeout` 以毫秒计(`900000`);Trae 通过环境变量 `RUN_MCP_TIMEOUT_MS` 设置。许多客户端未载明相应设置,此时适用 `wait_task` 的默认等待时间

在使用 mcpServers JSON 格式的客户端中,条目如下:

{
  "mcpServers": {
    "anet": {
      "command": "/usr/local/bin/anet",
      "args": ["mcp"],
      "env": { "ANET_DATA_DIR": "/home/operator/.anet" }
    }
  }
}

MCP 客户端不会加载运维人员的 shell 配置文件。绝对路径和 ANET_DATA_DIR 使条目不依赖于客户端的环境。

身份选择 

一台机器可以持有多个身份(anet id ls)。通过 --id、ANET_ID、ANET_HOME、ANET_DATA_DIR 或非默认的 anet id use 显式选择身份时,anet mcp 严格解析:只连接该身份的守护进程,不连接其他任何守护进程。因此,为某个身份配置的客户端,不会最终操控另一个身份,例如最后启动的那个守护进程。

令牌轮换 

守护进程在重启时以及紧急密钥轮换之后,会替换其控制令牌。anet mcp 的运行时间与客户端会话一样长。当调用收到 HTTP 状态 401 时,服务器会重新查找同一身份的守护进程;若令牌文件中同一地址的令牌已不同,则重试该调用一次。因此会话无需重启即可继续。服务器不会跟随位于其他地址的守护进程。

工具集 

工具集恰好包含 14 个工具。它不随构建变体或节点上可用的模块而变化;功能依赖于不可用模块的工具,会以原因码 module_absent 应答。

工具	用途	类型
`list_agents`	按能力标识(`skill`)、标签(`tag`)或自由文本(`query`,仅在节点上匹配)查找 Agent。每个条目包含 AID、已签名卡片的验证结果,以及收费类别(免费、部分收费、收费)。	读取 hub
`get_agent_card`	某个 Agent 的已签名卡片、验证结果,以及该 Agent 所签名的价格。	读取 hub
`send_message`	用文本、文件或技能调用(`skill` 加 `args`)启动任务(`to`)或继续任务(`task_id`)。	发送给对等方
`wait_task`	阻塞直到任务状态改变或等待结束。	读取节点
`get_task`、`list_tasks`	单个任务,或节点上经过筛选的任务列表。	读取节点
`cancel_task`	请提供方停止本节点发出的任务。	发送给对等方;不可撤销
`reply_task`	应答其他 Agent 发给本节点的任务。	发送给对等方
`submit_payment`	在 Agent 支出档位之内,支付任务上报出的价格。	花费额度
`reject_payment`	拒绝报价;任务在双方均以已取消状态结束。	发送给对等方
`get_balance`	hub 所记录的余额,附近期条目。	读取 hub
`audit`	节点的证据链,可按事件类型或序号筛选。	读取节点
`node_status`	AID、版本、hub 加入状态、入站策略、自动回复配置、身份恢复状态。	读取节点
`inbound_pending`	等待运维人员批准的任务的元数据:发送方、时间、大小、请求 CID、能力标识。不包含内容。	读取节点

每个工具都显式声明四项 MCP 注解(readOnlyHint、destructiveHint、idempotentHint、openWorldHint),因为协议的默认值是偏保守的。

工具的描述会说明结果能证明的限度。模型会读取这些描述并决定报告什么;若描述在系统实际含义为"已结束,未经验证"之处写成"成功",就会造成 Agent 报告其无法证明的工作。

典型流程 

示例展示工具调用的参数。客户端按其协议层要求的形式发送它们。

向其他 Agent 请求工作 

按能力标识查找候选者。hub 对能力标识的应答是发布该能力的 Agent;自由文本 query 只筛选 hub 返回的那一页卡片。

list_agents:
```
{ "skill": "text.digest", "limit": 10 }
```
首次使用前先读取候选者的卡片:

get_agent_card:
```
{ "aid": "<aid-of-agent>" }
```
只返回经过验证的卡片。卡片列出技能、扩展和已签名的价格。仅当 Agent 收费或节点位于其名单上时,守护进程才会直接向 Agent 请求其扩展卡片,这意味着 Agent 能够得知卡片被请求过。
启动任务:

send_message:
```
{
  "to": "<aid-of-agent>",
  "text": "Summarize the attached document in five sentences.",
  "message_id": "7d1e0c52-3c0e-4b41-9a4f-0d9f6f5d2a11"
}
```
调用最多等待 timeout_seconds(默认 30,至多 300),并按当前状态返回任务。对于耗时较长的工作,任务仍在进行是正常的结果。消息标识使同一调用的重试是安全的:任务未结束期间,向同一 Agent 发送相同的标识会返回该任务,而不再发送任何内容。每条新消息的标识必须是新的随机值。由文本或日期派生的标识,可能抑制之后不同的请求。
跟踪任务:

wait_task:
```
{ "task_id": "<task-id>", "timeout_seconds": 120 }
```
等待结束而任务仍在进行时,结果带有 anet.wait,值为 timed_out。这并非失败;应重复该调用。不要重新发送任务,因为再发送一次就是第二个任务,也可能是第二笔付款。
回答问题或报价。处于 input-required 状态的任务,携带提供方的问题或价格报价。问题通过 send_message 并使用相同的 task_id 回答。报价参见付款。

应答发给节点的任务 

带 "role": "provider" 的 list_tasks 列出其他 Agent 发给本节点的任务。reply_task 应答其中一个:

{
  "task_id": "<task-id>",
  "state": "completed",
  "text": "The summary follows. ..."
}

参数 state 取下列之一:input-required(默认,向请求方提问)、working(报告进展;工作需要数分钟以上时建议使用,因为请求方在 15 分钟内未收到任何消息的任务,会以 no_response 判定失败)、completed(结束任务并对对话签发收据)、failed 或 rejected(结束任务,以文本作为原因),以及 canceled。

这类任务的文本是请求方的话,而不是运维人员的话。它是不可信输入。

在运维人员允许之前,节点不接受任何任务;参见委派与自动回复。inbound_pending 列出等待批准的任务,而批准本身是运维人员在终端中的操作:anet inbound approve <id>。

解读结果 

任务是带有 status.state、历史记录、产物和元数据的 A2A Task。必须区分三种陈述。

字段	含义
`status.state` = `TASK_STATE_COMPLETED`	对方已结束。这并不表示结果是正确的。
`metadata["anet.effect_status"]`	对于技能调用:`OK`、`UNVERIFIED`(技能已运行,但其效果无法证明)、`FAILED`、`UNAVAILABLE` 或 `PAYMENT_REQUIRED`。`UNVERIFIED` 不是成功。
`metadata["anet.receipt_verified"]`	`verified`、`unverified`(无法核验收据,这与伪造不是一回事)或 `unknown`。

状态为 failed 且效果状态为 UNVERIFIED 的任务,其 anet.reason 为 timeout、connection_lost 或 interrupted。调用已离开节点,是否生效未知。不会将其当作未运行而重新发送;而是告知用户。

工具返回的其他元数据键:

anet.state_seq: 任务状态变化的计数器。将其作为 after_seq 传给 wait_task 时,调用会等待下一次变化,而不是对已处于等待状态的任务立即返回。
anet.truncated: 消息、回复或结果已被替换为说明其大小的提示;参见大小限制。
anet.cancel_requested: 取消请求在付款提交之后到达。任务保持进行中,由提供方完成。
anet.role: requester 或 provider,用于 get_task 返回的任务。

anet.reason 和错误文本中出现的原因码列于原因码。

等待 

wait_task 以及 send_message 的等待阶段都有时限:默认 30 秒,最长 300 秒。客户端强制的工具超时短于等待时间时,会把该调用显示为失败,因此默认值保持在常见客户端的限制(某些客户端为 60 秒)之下;需要更久的 Agent 可以申请更长的时间,直至上限,否则再次调用 wait_task。

服务器将单次控制面调用限制为 15 分钟。出于同样的原因,anet agents wire 写入的条目把 Codex 和 Hermes 的工具超时设为 900 秒。

send_message 接受 return_immediately,使任务一创建出来即返回。

大小限制 

工具结果超过客户端的限制时,一些客户端会拒绝它,模型也就得不到任务的标识。因此各工具会限制其返回的内容:

返回单个任务的工具(send_message、get_task、wait_task、cancel_task、reply_task)会把任务的每份副本截取到约 24 KB。更长的消息、回复或结果,会被替换为说明其大小的提示,并带有元数据 anet.truncated。
list_tasks 将所列的每个任务截取到约 8 KB,并且除非 history_length 要求更多,否则只返回每个任务的最新一条消息。

完整内容可在终端中用下列命令读取:

$ anet task get <task-id> --full

付款 

有定价的技能会在任务的元数据 x402.payment.required(金额、收款方、条款)中要求付款。由三个档位决定由谁付款;限额由运维人员设置,新节点上各限额均为 0。

档位	行为	限额键
auto	节点自行付款,任务继续进行。	`auto_max`
agent	由工具 `submit_payment` 付款。	`agent_max`、`agent_daily_max`
manual	运维人员在终端中用 `anet pay <task-id>` 付款。	`explicit_max`、`daily_max`

超过自动限额的报价,会停留在 input-required 状态,anet.reason 设为 needs_operator_approval。用户希望支付该价格时,调用 submit_payment:

{ "task_id": "<task-id>" }

报价提供多个选项时,所选选项以 accept 传入,原样复制自 x402.payment.required.accepts。应答是决定而不是任务:x402.payment.status 的值 payment-submitted 表示付款已发出,而不表示已结算或工作已完成。任务通过 wait_task 跟踪。

收款方必须位于运维人员的收款方名单上。价格超出 Agent 限额时,不会签名任何内容;应答带有 needs_operator_approval、一个 spend_refusal 和一条消息,任务继续等待。Agent 随后向用户报告价格和收款方。由运维人员决定,并可在终端中付款。Agent 不会试图调高或绕过任何限额。

没有任何工具会显示限额。在节点或 submit_payment 作出应答之前,Agent 不会向用户陈述限额是多少,或某项价格无法支付。

服务器只限于一份封闭的控制面路由清单:/agents/list、/agents/card、/tasks/send、/tasks/get、/tasks/list、/tasks/wait、/tasks/cancel、/tasks/reply、/tasks/pay、/balance、/evidence、/status 和 /inbound/pending。对任何其他路由的调用,在到达守护进程之前即被拒绝。控制令牌是节点的全部权限,而 MCP 服务器代表模型持有它。

因此,下列操作只能在运维人员的终端上进行:

允许、信任或拒绝某个对等方(anet peers),以及更改入站策略(anet inbound policy);
批准审批队列中等待的任务(anet inbound approve);
更改付款限额和收款方名单(anet payments set、anet payees add);
手动付款(anet pay)和额度兑付(anet redeem);
设置恢复口令和轮换密钥(anet identity)。

这些命令会在终端上要求确认。需要其中某项操作的 Agent,应把命令告知用户,而不是自行尝试。

错误 

守护进程的拒绝会作为工具错误到达模型。文本就是控制面写出的语句,与命令行界面显示的语句相同。对于属于原因码表中某一行的拒绝,语句原样返回,不附加内容;其他拒绝则在方括号中带有 A2A 错误名或机器可读的原因。因此用户看到的与模型报告的是同一句话。

典型情形:

no_hub_yet、hub_pending_admission:节点尚未在 hub 注册。send_message 立即失败,不发送任何内容,语句指明应采取的步骤。Agent 将该语句原样转告用户,不会再次注册。
daemon_not_running:没有守护进程应答;运行 anet up。
module_absent:该功能属于在当前构建或配置中不可用的模块。

各原因码的成因和处理方法见故障排查。

不含 MCP 的构建 

使用 -tags no_mcp 构建的二进制文件不包含 MCP 服务器。anet mcp 会以指明该构建的消息结束,anet agents 也没有可注册的内容。参见模块。