MCP tool Hooks

让生命周期事件调用已连接的 MCP 工具，设置类型保留的参数模板并理解失败开放行为。

This page has not been translated into English yet. The original Chinese version is shown below.

mcp_tool handler 可以直接调用已连接 MCP server 的工具。它使用与 command Hook 相同的信任审查和输出契约，但不负责启动或重连 server。

先确认连接，再配置处理器

以下是官方结构形式；scanner 和 scan_patch 必须由实际已连接的服务提供：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "mcp_tool",
        "server": "scanner",
        "tool": "scan_patch",
        "input": { "patch": "${tool_input.command}" },
        "timeout": 30,
        "statusMessage": "Scanning edited files"
      }]
    }]
  }
}

server 和 tool 为必填；input 是可选 JSON 参数模板，默认 {}；timeout 为秒，默认 600；statusMessage 是可选进度文案。例中的 30 秒是显式覆盖。

参数模板保留 JSON 类型

${field.nested} 从事件读取点路径。占满整个值时保留原始 JSON 类型，嵌在更长字符串中则转成文本。对象和数组递归展开。

例如事件中 tool_input.count 为数字 3，模板 "count": "${tool_input.count}" 最终得到数字 3，而 "message": "Count: ${tool_input.count}" 得到文本。设计工具参数 Schema 时应按展开后的类型验证。

错误和审批

MCP Hook 同步运行，不额外请求工具审批，也不触发其他 Hooks。只有工具返回受支持的阻断决定才会阻止操作；server 缺失、工具不可用或执行错误本身不阻断。SessionStart 可能早于 MCP 就绪，这也不会阻止会话。

实际超时取 Hook 与 server 超时中较短者；等待 MCP elicitation 回答的时间不计入执行超时。SessionEnd 不支持 MCP tool Hook。

云端协调的适用范围

Work Cloud with local access 的企业 Hooks 是云端协调器上的管理员远程 MCP Hooks。它不等于将本地 command Hook 或插件 Hook 自动搬到云端，也不是完整的 Compliance API 审计记录。策略使用前要在实际执行环境中验证连接、事件和失败行为。