MCP Agent Runtime 可靠性基线

给本地或远程 broad-agent MCP 建立一套可复现的可靠性基线：短同步 RPC、Job Manager、背压、有界 I/O、stdio 生命周期、密钥边界、结构化日志和验收检查。

#howto #growing #ai #mcp #architecture #ops

[!info] related notes

前置笔记:

相关 MOC:

相关资源:

MCP Agent Runtime 可靠性基线

目标

把“能通过 MCP 调命令/文件”的桥接服务，收敛成一个可长期运行、可观察、可重建的 Agent Tool Runtime。

成功状态不是“偶尔能调用”，而是：

短工具调用的延迟可预测；
长任务不会占住单次 RPC；
队列不会无界预取；
文件和日志结果有显式预算；
stdio 生命周期正确；
secret 不进入 argv、Git 或普通日志；
出错后能区分 Tunnel、MCP、shell 与 hosted stream；
新机器可以从 source of truth 重建。

当前 broad-agent 经验基线

[!important] 以下数值来自 2026-10-01 GCP / WSL / Oracle2 实践，是当前环境的工程基线，不是 MCP 协议规范。

tunnel-client            0.0.15

sync command:
  default timeout        20s
  hard max               30s

control plane:
  max_inflight_requests  1

MCP server:
  max_concurrent_requests 4

long task:
  persistent Job API

shell output:
  stdout                 <= 64 KiB
  stderr                 <= 64 KiB

recursive filesystem:
  explicit time budget
  scan budget
  result budget
  heavy-dir exclusions

stdio:
  initialized notification shim enabled

1. 把同步命令变短

同步 shell 只承担：

pwd
git status
git diff
小范围 grep
小测试
快速诊断命令

超过 hard max 的请求应立即拒绝，并明确提示改用 Job，而不是悄悄把 timeout 放大。

参见 [private note]。

2. 提供持久化 Job API

至少实现：

job_start
job_status
job_output
job_cancel
job_list

要求：

Job 状态落盘；
日志落盘；
独立进程组；
cancel 能清理整个进程组；
output 有 offset/limit；
MCP server 重启后仍能读取已有 Job 状态。

参见 mcp-persistent-job-manager。

3. 建立控制面背压

Broad Agent 当前建议：

control_plane:
  max_inflight_requests: 1

mcp:
  max_concurrent_requests: 4

不要把这一组值机械复制到所有 Server。

例如纯知识检索 MCP 的请求通常短而独立，可以使用更高并发。Thought Forest 当前实践是：

inflight   = 4
concurrent = 8

原则是：参数服从工具耗时分布，而不是追求配置统一。

4. 给所有文件工具加预算

至少覆盖：

read；
recursive search；
directory tree；
related-items；
大日志读取。

参见 mcp-bounded-tool-io。

5. 正确完成 stdio 初始化

Tunnel 启动或重建 stdio child 后，应保证：

initialize
→ notifications/initialized
→ tools/list / tools/call

当前 tunnel-client profile 开启：

stdio_send_initialized_notification: true

用于避免重连后出现“server not initialized”类生命周期错误。

6. Secret 不进入 argv

错误模式：

cmd.exe /c "set CONTROL_PLANE_API_KEY=... && tunnel-client ..."

这可能让 secret 出现在进程参数列表。

可接受模式包括：

ACL 限制的 secret file；
systemd EnvironmentFile；
OS credential store；
安全的环境注入。

共同约束：

no argv
no Git
no Markdown
no ordinary logs

不同 OS 不需要使用同一种注入技术。

7. 结构化可观测性

至少记录：

tool_start
tool_end
tool_fail
request/tool id
tool name
duration_ms
error class
result size / truncation state（按需）

默认不要记录 raw args，因为 shell command、文件内容或 prompt 可能包含凭据或敏感数据。

日志的目标是能区分：

Tunnel deadline
MCP tool timeout
shell timeout
filesystem budget
stdio lifecycle
hosted ChatGPT stream

而不是只有一句“工具卡了”。

8. Source of Truth 与重建

线上热修不是最终状态。

可靠部署至少需要：

pinned tunnel-client version
profile template
server source
service definition
reconcile/install script
smoke test
README / baseline

现场运行状态和 IaC 模板漂移时，以验证过的 canonical source 为后续重建依据。

9. Smoke Test

至少验证：

tools/list 返回预期工具。
短同步命令成功。
请求超过同步 hard max 会快速拒绝。
job_start → status → output → completed 完整闭环。
filesystem search 能触发/报告 budget。
health / ready 正常。
secret 不出现在 argv。
服务重启后没有 not initialized。
当前生命周期没有新增 deadline / stdio / file-closed 错误。

10. 不要机械复制的部分

Disk guard

磁盘保护应基于真实磁盘压力证据添加，不属于每个 MCP host 的强制组件。

Job Manager

Broad shell agent 需要；纯短查询知识 MCP 不一定需要。

并发值

1/4 与 4/8 都是当前部署经验，不是普遍最优值。

验收表

维度	验收
同步调用	默认短、硬上限明确
长任务	Job 化，不占长 RPC
Queue	有 backpressure
Filesystem	时间/扫描/数量预算
Output	byte/entry 上限 + truncation
stdio	初始化生命周期完整
Secret	不进 argv / Git / 普通日志
Observability	能定位是哪一层超时
Recovery	server/service 可重启
Reproducibility	source-of-truth 可重建

学习检查

哪些内容属于“可靠性 contract”，哪些只是当前环境参数？
为什么纯知识查询 MCP 不一定需要 Job Manager？
为什么 secret policy 应统一目标而不是统一注入实现？
Smoke Test 为什么必须包含“超限请求被快速拒绝”？
为什么现场热修完成后还必须更新 IaC/source of truth？