MCP Tool Hook

工作原理

MCP Tool Hook 基于 AgentRun MCP 代理层运行。代理层位于 MCP 客户端（智能体）和 MCP 服务端之间，作为透明中间层转发所有 MCP 协议请求。启用代理后，工具调用请求不再直接到达 MCP 服务，而是经过代理层中转。代理层在执行 tools/list 和 tools/call 操作的前后，触发已配置的 Hook 事件，将请求或响应转发至外部 Hook 服务（HTTP Webhook）进行处理。

以 POST_CALL_TOOL 事件为例，数据流转过程如下：

1. 智能体发起工具调用请求。

2. AgentRun MCP 代理层接收请求，调用 MCP 服务执行工具操作。

3. MCP 服务返回原始结果。

4. 代理层根据 Hook 配置，将结果通过 HTTP POST 转发至 Hook 服务。

5. Hook 服务对结果进行处理（如脱敏、审计标记），返回修改后的结果。

6. 代理层将最终结果返回给智能体。

其他事件的流转方式类似：PRE_CALL_TOOL 在工具调用前触发，可修改请求参数或拦截调用；PRE_LIST_TOOLS 和 POST_LIST_TOOLS 分别在获取工具列表前后触发，可对工具列表进行预处理或过滤修改。

部署模式

AgentRun 支持两种 MCP Tool Hook 部署模式：

两种模式使用相同的 Hook 配置方式，区别在于 MCP 服务的部署和引用方式。

准备工作

• 已开通 AgentRun 服务。可通过AgentRun 控制台确认。

• 已开通函数计算（FC）服务，用于部署 MCP 服务和 Hook 服务。

• 已安装 Golang 1.23 及以上开发环境。

• 已获取阿里云账号的 UID、AccessKey ID 和 AccessKey Secret。获取方式请参见获取 AccessKey。

• 已准备 MCP 服务代码和 Hook 服务代码。完整示例可从 start-agentrun 仓库获取：

  git clone https://github.com/devsapp/start-agentrun.git
  cd start-agentrun

  项目中包含两个示例目录：mcp_remote（远程 MCP 模式）和 mcp_code（代码打包模式），分别对应两种部署模式的完整示例。以下操作步骤中的相对路径均基于项目根目录 start-agentrun/。

部署函数计算服务时，默认使用中国地域（如 cn-hangzhou）。请根据实际业务需求选择合适的地域。

配置 MCP Tool Hook（mcp_remote 模式）

以下以订单查询服务（orderdesk）和数据脱敏 Hook 服务（userhook）为例，演示 mcp_remote 模式的完整配置流程。

go run .

{
  "order_id": "ORDER-1001",
  "customer_name": "张三",
  "phone": "138****5678",
  "email": "zhangsan@example.com",
  "shipping_address": "浙江省杭州市西湖区文三路 100 号",
  "status": "PAID",
  "amount": 259.8,
  "items": [
    {"sku": "SKU-AX100", "name": "人体工学鼠标", "quantity": 1, "price": 129.9},
    {"sku": "SKU-KB200", "name": "机械键盘键帽", "quantity": 1, "price": 129.9}
  ]
}

{
  "order_id": "ORDER-1001",
  "customer_name": "张*",
  "phone": "138****5678",
  "email": "zh***@example.com",
  "shipping_address": "浙江省杭州市****",
  "status": "PAID",
  "amount": 259.8,
  "items": [
    {"sku": "SKU-AX100", "name": "人体工学鼠标", "quantity": 1, "price": 129.9},
    {"sku": "SKU-KB200", "name": "机械键盘键帽", "quantity": 1, "price": 129.9}
  ],
  "audit_id": "audit_xxxxxxxxxxxxxxxx"
}

{
  "proxyEnabled": true,
  "hooks": [
    {
      "event": "POST_CALL_TOOL",
      "endpoint": "<Hook 服务的 Endpoint 地址>"
    }
  ]
}

配置 MCP Tool Hook（mcp_code 模式）

mcp_code 模式将 MCP 服务代码打包到 AgentRun 运行时中，无需单独部署 MCP 服务，简化部署流程。以下同样以 orderdesk（MCP 服务）和 userhook（Hook 服务）为例。

go run .

示例：订单数据脱敏 Hook 服务

示例程序中的 Hook 服务（userhook）使用 Go 实现，处理 POST_CALL_TOOL 事件。以下是核心脱敏函数，完整代码参见 start-agentrun 仓库。

// maskPhone 对手机号进行掩码处理，保留前 3 位和后 4 位。
func maskPhone(phone string) string {
    runes := []rune(strings.TrimSpace(phone))
    if len(runes) <= 7 {
        return "***"
    }
    return string(runes[:3]) + "****" + string(runes[len(runes)-4:])
}

// maskEmail 对邮箱进行掩码处理，保留前 2 位用户名。
func maskEmail(email string) string {
    parts := strings.SplitN(email, "@", 2)
    if len(parts) != 2 {
        return "***"
    }
    name := []rune(parts[0])
    keep := 1
    if len(name) > 2 {
        keep = 2
    }
    return string(name[:keep]) + "***@" + parts[1]
}

// maskAddress 对地址进行掩码处理，保留前 6 个字符。
func maskAddress(address string) string {
    runes := []rune(strings.TrimSpace(address))
    if len(runes) <= 6 {
        return "***"
    }
    return string(runes[:6]) + "****"
}

// maskName 对姓名进行掩码处理，保留姓氏。
func maskName(name string) string {
    runes := []rune(strings.TrimSpace(name))
    if len(runes) == 0 {
        return "***"
    }
    return string(runes[:1]) + "*"
}

// auditIDFromBytes 根据原始响应生成审计编号（SHA256 哈希前缀）。
func auditIDFromBytes(body []byte) string {
    sum := sha256.Sum256(body)
    return "audit_" + hex.EncodeToString(sum[:])[:16]
}

Hook 服务接收代理层通过 HTTP POST 转发的事件负载，负载中的请求和响应 Body 采用 Base64 编码。Hook 服务解码后对敏感字段进行掩码处理，注入审计标识，再将修改后的结果 Base64 编码返回。

错误处理

Hook 服务异常时，代理层将中断本次 MCP 请求：

常见问题