Agent Run:MCP Tool Hook

How it works

MCP Tool Hook runs on the AgentRun MCP proxy layer, which sits transparently between the MCP client (agent) and MCP server. When enabled, tool call requests pass through the proxy instead of going directly to the MCP service. The proxy triggers configured Hook events before and after tools/list and tools/call operations, forwarding the request or response to an external Hook service (HTTP webhook) for processing.

Take the POST_CALL_TOOL event as an example. The data flow is as follows:

1. The agent sends a tool call request.

2. The AgentRun MCP proxy receives the request and calls the MCP service to execute the tool operation.

3. The MCP service returns the raw result.

4. The proxy forwards the result to the Hook service via an HTTP POST request based on the Hook configuration.

5. The Hook service processes the result (for example, by masking sensitive data or adding audit tags) and returns the modified result.

6. The proxy returns the final result to the agent.

Other events follow a similar flow. PRE_CALL_TOOL triggers before the tool call and can modify request parameters or block the call. PRE_LIST_TOOLS and POST_LIST_TOOLS trigger before and after fetching the tool list, allowing you to preprocess or filter the tool list.

Deployment modes

AgentRun supports two MCP Tool Hook deployment modes:

Both modes use the same Hook configuration method. The difference lies in how the MCP service is deployed and referenced.

Preparations

• You have activated the AgentRun service. Confirm this in the AgentRun console.

• You have activated Function Compute (FC) to deploy the MCP service and Hook service.

• You have installed a Golang 1.23 or later development environment.

• You have obtained your Alibaba Cloud account UID, AccessKey ID, and AccessKey secret. For instructions, see Obtain an AccessKey.

• You have prepared the MCP service code and Hook service code. Obtain a complete example from the start-agentrun repository:

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

  The project includes two example directories: mcp_remote (remote MCP mode) and mcp_code (code-packaged mode), each providing a complete example for its respective deployment mode. All relative paths in the following steps are based on the project root directory start-agentrun/.

When deploying Function Compute services, the default region is on the Alibaba Cloud International Website (for example, ap-southeast-1). Choose a region that fits your business needs.

Configure MCP Tool Hook (mcp_remote mode)

The following example uses an order query service (orderdesk) and a data masking Hook service (userhook) to demonstrate how to configure mcp_remote mode.

go run .

{
  "order_id": "ORDER-1001",
  "customer_name": "Zhang San",
  "phone": "138****5678",
  "email": "zhangsan@example.com",
  "shipping_address": "No. 100 Wensan Road, Xihu District, Hangzhou City, Zhejiang Province",
  "status": "PAID",
  "amount": 259.8,
  "items": [
    {"sku": "SKU-AX100", "name": "Ergonomic Mouse", "quantity": 1, "price": 129.9},
    {"sku": "SKU-KB200", "name": "Mechanical Keyboard Keycaps", "quantity": 1, "price": 129.9}
  ]
}

{
  "order_id": "ORDER-1001",
  "customer_name": "Zhang*",
  "phone": "138****5678",
  "email": "zh***@example.com",
  "shipping_address": "Zhejiang Province, Hangzhou City, ****",
  "status": "PAID",
  "amount": 259.8,
  "items": [
    {"sku": "SKU-AX100", "name": "Ergonomic Mouse", "quantity": 1, "price": 129.9},
    {"sku": "SKU-KB200", "name": "Mechanical Keyboard Keycaps", "quantity": 1, "price": 129.9}
  ],
  "audit_id": "audit_xxxxxxxxxxxxxxxx"
}

{
  "proxyEnabled": true,
  "hooks": [
    {
      "event": "POST_CALL_TOOL",
      "endpoint": "<Endpoint address of the Hook service>"
    }
  ]
}

Configure MCP Tool Hook (mcp_code mode)

In mcp_code mode, the MCP service code is bundled into the AgentRun runtime, so you do not need to deploy a standalone MCP service. The following example also uses orderdesk (MCP service) and userhook (Hook service).

go run .

Example: Order data masking Hook service

The Hook service in the example (userhook) is implemented in Go and handles the POST_CALL_TOOL event. Below are the core masking functions. For the complete code, see the start-agentrun repository.

// maskPhone masks a phone number, keeping the first 3 and last 4 digits.
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 masks an email address, keeping the first 1–2 characters of the username.
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 masks an address, keeping the first 6 characters.
func maskAddress(address string) string {
    runes := []rune(strings.TrimSpace(address))
    if len(runes) <= 6 {
        return "***"
    }
    return string(runes[:6]) + "****"
}

// maskName masks a name, keeping only the surname (first character).
func maskName(name string) string {
    runes := []rune(strings.TrimSpace(name))
    if len(runes) == 0 {
        return "***"
    }
    return string(runes[:1]) + "*"
}

// auditIDFromBytes generates an audit ID from the raw response (SHA256 hash prefix).
func auditIDFromBytes(body []byte) string {
    sum := sha256.Sum256(body)
    return "audit_" + hex.EncodeToString(sum[:])[:16]
}

The Hook service receives the event payload from the proxy via HTTP POST. The request and response bodies in the payload are Base64-encoded. The Hook service decodes them, masks sensitive fields, injects an audit identifier, and returns the modified result as a Base64-encoded string.

Error handling

If the Hook service fails, the proxy interrupts the current MCP request:

FAQ