《Agent Runtime 工程化》第六章 MCP 与 Provider 抽象

MCP 解决'外部能力如何标准化连接'。Runtime 解决'这些能力如何被安全、可控、可恢复地使用'。这条边界要先想清楚。

6.2 tools/list 与 tools/call 的工程含义

MCP Tools 规范里，Client 通过 tools/list 发现工具，通过 tools/call 调用工具。工具通常包含名称、描述和输入 schema。工具列表可以为空，也可以随时间变化；当工具列表变化时，Server 可以通知 Client。

对 runtime 来说，这意味着工具注册从'启动时写死'变成'运行时发现'。随之而来的问题比接通协议本身更重要：

MCP 规范也强调工具安全：工具可能代表任意代码执行能力，Host 应让用户能理解和授权工具调用。写 runtime 时，不能把这句话当成文档里的礼貌提醒。只要一个 MCP Server 能读写本地文件或访问企业系统，它就进入了真实安全边界。

6.3 把 MCP 工具接入 Tool Registry

一个稳妥做法是：不要让模型直接面对'裸 MCP 工具'。Runtime 应把 MCP 工具包装成本地统一的 ToolDefinition，再交给前面第四章的工具治理管线。

type McpServerTrust = "trusted_local" | "team_audited" | "third_party" | "unknown";

function fromMcpTool(server: McpServerInfo, tool: McpTool): ToolDefinition {
  return {
    name: `mcp.${server.id}.${tool.name}`,
    title: tool.title ?? tool.name,
    description: tool.description ?? "",
    version: `mcp:${server.version ?? "dynamic"}`,
    inputSchema: tool.inputSchema,
    riskLevel: classifyMcpRisk(server, tool),
    sideEffects: inferMcpSideEffects(server, tool),
    resources: [{ kind: "mcp", scope: server.id }],
    timeoutMs: server.defaultTimeoutMs ?? 30_000,
    outputPolicy: {
      maxCharsForModel: 12_000,
      summarizeWhenLarge: true,
      redactSecrets: true,
    },
    async execute(input, ctx) {
      return ctx.mcp.callTool(server.id, tool.name, input);
    },
  };
}

命名空间非常重要。不要让两个 Server 的 search 工具互相覆盖。建议把本地名称写成 mcp.<serverId>.<toolName>，给模型展示时可以用更友好的 title，但 trace 和 policy 中保留完整名字。

也不要直接相信工具描述里的'read only''safe'。风险等级应由本地策略决定，至少参考五类信号：

• Server 信任等级；
• 工具名称和描述；
• 输入 schema 中是否出现 path、command、url、query、mutation 等字段；
• Server 连接方式是本地还是远程；
• 用户或组织策略给这个 Server 的授权范围。

MCP 的好处是工具发现标准化了，不是安全自动解决了。工具越容易接入，runtime 越要有统一治理。

6.4 工具列表刷新与上下文暴露

动态工具发现带来一个新问题：什么时候把哪些工具暴露给模型？

如果把所有 MCP 工具都塞进模型上下文，token 会浪费，误调用概率也会上升。一个企业环境里可能有几十个 MCP Server、几百个工具。模型不需要每一步都知道所有能力。

建议做两级工具集：

type ToolExposure = {
  allDiscovered: ToolDefinition[];
  enabledForRun: ToolDefinition[];
  exposedThisStep: ToolDefinition[];
};

allDiscovered 是当前连接发现的全部工具。enabledForRun 是当前用户、workspace 和 policy 允许使用的工具。exposedThisStep 是本轮模型真正看到的工具，应该由当前任务意图、工具相关性和上下文预算决定。

刷新策略可以这样设计：

工具列表本身也要进入 trace。否则任务失败时，你不知道模型当时到底看见了哪些 MCP 工具。

6.5 Provider Adapter 统一模型调用

模型供应商的工具调用接口并不完全一致。不同 provider 对 message、tool schema、stream event、usage、finish reason、并行 tool calls、strict schema、response continuation 的支持都有差异。Runtime 应有自己的 provider adapter。

interface ModelProvider {
  name: string;
  capabilities: ModelCapabilities;
  generate(input: ModelRequest): AsyncIterable<ModelEvent>;
}

type ModelRequest = {
  messages: RuntimeMessage[];
  tools: RuntimeToolSchema[];
  toolChoice?: "auto" | "none" | { name: string };
  maxOutputTokens?: number;
  signal: AbortSignal;
};

type ModelEvent =
  | { type: "text_delta"; text: string }
  | { type: "tool_call_delta"; callId: string; name?: string; inputDelta?: string }
  | { type: "tool_call_done"; call: ToolCall }
  | { type: "usage"; usage: TokenUsage }
  | { type: "done"; finishReason: string };

这个接口的目标不是假装所有模型一样。相反，它要把差异显式化：

type ModelCapabilities = {
  toolCalling: boolean;
  strictToolSchema: boolean;
  parallelToolCalls: boolean;
  streaming: boolean;
  responseContinuation: boolean;
  maxContextTokens: number;
};

Provider Adapter 把 provider 原生事件转成 runtime 事件，同时把 provider 特性保留在 metadata 中。这样做有两个好处：主循环不用关心每个 SDK 的字段名；eval 和 trace 又能看到影响行为的 provider 差异。

6.6 不要用降级绕过安全

模型调用失败时，runtime 可以重试或降级；但要分清失败类型。

有一条底线：安全策略拒绝，不能通过换 provider 绕过去。比如某个模型因为 policy 不允许执行网络工具，runtime 不应自动换一个没有这个限制的模型继续执行。同样，用户拒绝了 MCP 工具调用，恢复执行时也不能因为 provider 重试而重新发起同一个高风险调用。

降级是为了提高可用性，不是为了绕开边界。

6.7 限流、重试与幂等

Provider 调用和 MCP 工具调用都可能失败，但重试策略不同。

模型请求通常是无外部副作用的，可以在网络错误或 5xx 时短重试。MCP 工具调用不一定幂等。一个 read_project_file 可以重试；一个 create_issue、send_message、charge_customer 不能自动重试。

建议统一使用重试上下文：

type RetryContext = {
  operation: "model_generate" | "mcp_tool_call" | "local_tool_call";
  idempotency: "idempotent" | "conditional" | "non_idempotent";
  attempt: number;
  maxAttempts: number;
  lastErrorCode?: string;
};

function shouldRetry(ctx: RetryContext) {
  if (ctx.idempotency === "non_idempotent") return false;
  if (ctx.attempt >= ctx.maxAttempts) return false;
  return ["RATE_LIMIT", "TRANSIENT_NETWORK", "SERVER_ERROR"].includes(ctx.lastErrorCode ?? "");
}

这段逻辑会在第八章继续展开。现在先记住：MCP 接入后，工具是否可重放必须成为工具定义和 trace 的一部分。

6.8 Mock Provider 是 eval 的地基

不要等接好真实模型后才测试 Agent Loop。Provider Adapter 的价值之一，是让你可以用 mock provider 做确定性测试。

一个 mock provider 可以按脚本返回 tool call：

class ScriptedProvider implements ModelProvider {
  name = "scripted";
  capabilities = {
    toolCalling: true,
    strictToolSchema: true,
    parallelToolCalls: false,
    streaming: false,
    responseContinuation: false,
    maxContextTokens: 64_000,
  };

  constructor(private script: ModelResponse[]) {}

  async *generate(): AsyncIterable<ModelEvent> {
    const next = this.script.shift();
    if (!next) throw new Error("Script exhausted");
    if (next.kind === "tool_calls") {
      for (const call of next.calls) {
        yield { type: "tool_call_done", call };
      }
    } else {
      yield { type: "text_delta", text: next.text };
    }
    yield { type: "done", finishReason: "stop" };
  }
}

用 mock provider 可以稳定覆盖：非法工具名、非法参数、重复错误、并行 tool calls、无工具 final answer、上下文超限后的重建。等这些路径稳定了，再接真实模型。

6.9 本章的实现路径

第一步，把本地 ModelProvider 接口稳定下来，支持流式事件、usage、finish reason、capabilities 和 AbortSignal。

第二步，实现一个真实 provider adapter，再实现一个 scripted mock provider。所有 runtime 单元测试优先跑 mock provider。

第三步，用 MCP TypeScript SDK 写一个本地 MCP Server，提供 read_project_file 和 search_project_text 两个只读工具。

第四步，把 MCP 工具包装进本地 ToolDefinition，加命名空间、风险分类、输出策略和超时。

第五步，加入工具列表刷新机制。每次发现、变更、断开都写入 trace。

第六步，准备限流、上下文超限、schema 不支持、MCP Server 断开四类失败用例，验证 runtime 能降级或停止。

6.10 验收标准

完成本章后，你的 Agent 应能动态接入和移除 MCP 工具；MCP 工具仍然经过本地 Tool Registry 和 Permission Gate；模型供应商替换不影响主循环；schema 改变不会把 runtime 弄崩；mock provider 能复现核心 tool call 路径。

建议验收用例：

到这里，Agent Runtime 已经能接入生态，但控制权仍在自己手里。这一点很重要。协议和供应商负责提供能力，runtime 负责把能力变成可治理的工程系统。

系列文章目录

• 《Agent Runtime 工程化》完整目录
• 《Agent Runtime 工程化》第一章 Agent Runtime 全景
• 《Agent Runtime 工程化》第二章 TypeScript / Node Runtime 基础
• 《Agent Runtime 工程化》第三章 最小 Agent Loop
• 《Agent Runtime 工程化》第四章 工具系统设计
• 《Agent Runtime 工程化》第五章 上下文工程
• 《Agent Runtime 工程化》第六章 MCP 与 Provider 抽象
• 《Agent Runtime 工程化》第七章 权限与安全边界
• 《Agent Runtime 工程化》第八章 Checkpoint、Resume、Rollback
• 《Agent Runtime 工程化》第九章 可观测与 Trace
• 《Agent Runtime 工程化》第十章 Eval Harness 与 CI 回归
• 《Agent Runtime 工程化》第十一章 Agent Runtime 进阶学习路线
• 《Agent Runtime 工程化》第十二章 hermes-agent 产品级实战
• 《Agent Runtime 工程化》附录