◈24|MCP 工具接入(上):搞懂协议,把 Client 跑通

24|MCP 工具接入(上):搞懂协议,把 Client 跑通

你好,我是Robert。

智能客服现在能聊天、能引用知识库、能走工作流分类。但它只能“说”,不能“做”。

用户问“我的订单12345到哪了”,客服只能回答“请联系人工客服查询”,因为它没有能力去查订单系统。用户问“帮我提交一个换货申请”,客服只能说“好的,请您拨打客服热线”,因为它没有能力操作工单系统。

能说不能做, 是智能客服从“能用”到“好用”的最后一道墙。

这两讲拆掉这道墙。通过MCP协议,让Agent能调用外部工具,查订单、查库存、提交工单。这一讲搞懂协议,把Client跑通。下一讲开发真实的MCP Server。

为什么不直接调API

你可能会想:让Agent直接调订单系统的REST API不就行了?

可以,但只有一个系统的时候。智能客服要对接的系统不止一个,订单系统、库存系统、工单系统、物流系统,每个系统的API格式都不一样:

订单系统:POST /orders/query,JSON,Bearer Token
物流系统:GET  /tracking?waybillNo=SF123,XML,签名验证
工单系统:GraphQL,OAuth2
库存系统:gRPC,proto 文件

让Hify直接对接每个系统,就要为每个系统写一套适配代码,处理不同的参数格式、认证方式、返回结构。接一个系统写一套,接十个系统写十套,每次系统升级都要改Hify的代码。

更麻烦的是,LLM怎么知道有哪些工具可用?你得手动写进Prompt,“你可以查订单,API是这个,参数是那个”。每接一个新系统,就要改Prompt。

这个问题不是Hify独有的,所有AI应用都面临。Anthropic在2024年底提出了MCP协议来解决这个问题。

MCP是什么

我们继续问Claude Code:

MCP 协议是什么?它解决什么问题?

和直接调 REST API 有什么区别?

用智能客服的场景帮我解释,重点说清楚为什么需要标准化协议。

Claude Code解释得很直白: MCP是工具的标准化描述和调用协议。工具提供方按MCP标准暴露自己的能力,调用方通过统一方式发现和调用这些工具,不需要关心每个系统的API细节。

三个核心概念:

  • MCP Server:工具提供方。一个Server可以提供多个工具。比如订单服务MCP Server提供 query_order 和 cancel_order 两个工具。Server自己声明自己能干什么、需要什么参数。

  • MCP Client:工具调用方,就是Hify。负责发现Server有哪些工具( tools/list)、调用具体工具( tools/call)、处理返回结果。

  • Tool Schema:每个工具的标准描述,包括名称、说明、参数类型等。LLM通过schema知道有哪些工具可用,决定什么时候调哪个。

{
  "name": "query_order",
  "description": "根据用户ID和订单号查询订单状态,当用户询问订单、物流、快递相关问题时使用",
  "inputSchema": {
    "type": "object",
    "properties": {
      "userId":  {"type": "string", "description": "用户ID"},
      "orderId": {"type": "string", "description": "订单号,不知道时传空字符串"}
    },
    "required": ["userId"]
  }
}

和直接调API的核心区别:直接调API,你要去适配对方;用MCP,对方按标准描述自己,你用统一方式调用。Hify不需要知道订单系统用什么格式,只需要知道有一个 query_order 工具,需要什么参数。

Claude Code用一句话总结了MCP的价值: MCP之前,M个AI平台 × N个工具 = M×N套适配代码。MCP之后,工具开发者只写一个Server,任何支持MCP的平台都能接 = M+N。这和USB解决的问题一样。

业界真实案例

MCP不是新概念,业界已经有很多真实在用的MCP Server。我们一起看一个和智能客服直接相关的例子:Stripe。

Stripe官方发布了Stripe MCP Server,提供了一系列工具:

stripe_retrieve_payment_intent    根据支付ID查询支付详情
stripe_create_refund              发起退款
stripe_list_customers             查询客户列表
stripe_retrieve_invoice           查询账单详情
stripe_cancel_subscription        取消订阅

这意味着什么? 任何接入了Stripe MCP Server的AI应用,都能让Agent直接查支付记录、发起退款,不需要写一行对接Stripe API的代码,不需要处理Stripe的认证和参数格式,只需要在配置里加一个Server地址。

用户问“我上周的那笔支付是多少钱”,Agent调 stripe_retrieve_payment_intent,拿到数据,直接回答。Stripe升级了接口,改MCP Server就行,Hify不用动。

Claude Code说了一个重点: 给Agent接一个新的MCP Server,不需要改Agent代码,Agent自动发现新工具。这是标准化协议最核心的价值。也就是工具和平台解耦。

对智能客服来说这个价值最大。客服要对接的系统最多,订单、库存、工单、物流,每个都可以有MCP Server,接入只需要配置Server地址。

Function Calling是什么

知道了MCP是什么,下一个问题:LLM怎么知道要调哪个工具?

Function Calling 是什么?
LLM 怎么知道有哪些工具可用?
怎么决定什么时候调工具、调哪个、传什么参数?
一次用户对话如果需要调工具,完整的交互流程是什么样的?

Claude Code的解释很清楚: LLM本质上只能输入文本、输出文本。Function Calling是一种约定,LLM的输出文本里,有时候不是给用户看的回答,而是一个结构化的“我要调这个函数、传这些参数”的指令。LLM自己不执行任何函数,它只是“说”它想调什么。

LLM怎么知道有哪些工具:工具定义随每次请求一起发过去。不是持久记忆,是每次都告知。

{
  "messages": [{"role": "user", "content": "我昨天下的订单还没到"}],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "query_order",
        "description": "查询订单状态,当用户询问订单、物流、快递相关问题时使用",
        "parameters": { ... }
      }
    }
  ]
}

LLM怎么决定调哪个工具:靠 description 字段。LLM读到“我昨天下的订单还没到”,判断这是订单问题, query_order 的description说“用户询问订单相关问题时使用”,场景匹配,调它。description写得好不好,直接决定LLM选工具的准确率。这是MCP工具开发里最重要的地方。

完整时序一次用户对话涉及两次LLM调用。

第一次LLM调用,LLM判断需要调工具,返回的不是回答,而是工具调用指令:

{
  "finish_reason": "tool_calls",
  "message": {
    "tool_calls": [{
      "id": "call_abc123",
      "function": {
        "name": "query_order",
        "arguments": "{\"userId\": \"u001\", \"orderId\": \"12345\"}"
      }
    }]
  }
}

Hify拿到指令,通过MCP Client调订单服务,拿到真实数据,把结果追加进对话历史:

{"role": "tool", "tool_call_id": "call_abc123",
 "content": "{\"status\":\"运输中\",\"trackingNo\":\"SF1234567\",\"estimatedDate\":\"明天\"}"}

第二次LLM调用,LLM基于工具结果生成最终回答, finish_reason 变成 stop,这次是真正给用户的回答。

如果用户问的是不需要查数据的问题(你们的退货政策是什么),LLM第一次调用直接返回 finish_reason=stop,没有工具调用,没有第二次LLM调用。LLM自己判断要不要调工具,不是硬编码逻辑。

Claude Code还说了一个重要的边界:循环次数由LLM决定,不是固定的。理论上LLM可以连续调多个工具(先查订单再查物流),Agent框架一般设置最大轮次(比如10次)防止死循环。

MCP Client选型

Java 生态有哪些 MCP Client 的 SDK?

帮我调研主流选项,从成熟度、文档质量、和 Spring 生态兼容性几个维度对比。

最后给出建议,Hify 应该选哪个。

Claude Code先把hify-mcp模块和主pom.xml都读了,基于现有代码给建议。Java 17、Spring Boot 3.2.3,hify-mcp目前只有骨架还没实现。

调研结果有三个实质选项:

Claude Code的建议: 用官方Java SDK,不用Spring AI MCP。

理由很清楚:Spring AI MCP的设计,假设是你用Spring AI的整套抽象层——ChatClient、ChatModel、工具回调体系全部Spring AI化。Hify已经有自己的一套: ProviderAdapter 适配各LLM、 LlmHttpClient 做HTTP通信、 ChatServiceImpl 管对话流程。

引入Spring AI MCP意味着:引入整个 spring-ai-bom、工具调用结果要适配 ToolCallback 接口和现有 ProviderAdapter 产生摩擦、Spring AI 1.1 → 2.0 API变化剧烈升级成本高。两套抽象互相摩擦,不值得。

官方Java SDK只做一件事:实现MCP协议的序列化/反序列化和请求响应。不绑定任何AI框架,剩下的连接管理、异常处理、工具结果转换全按Hify现有风格写。

<!-- hify-mcp/pom.xml -->
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp</artifactId>
    <version>1.1.1</version>
</dependency>

Claude Code还提到一个已知问题:SDK的 HttpClientSseClientTransport 有HttpClient资源泄漏的issue,每次build一个新的HttpClient实例,没有正确关闭。规避方式是按调用创建、用完关闭,不长期持有client对象。

// 每次调工具:建连 → 调用 → 关闭,用 try-with-resources
try (McpSyncClient client = buildClient(server.getEndpoint())) {
    client.initialize();
    return client.callTool(new CallToolRequest(toolName, arguments));
}

这个判断方式可以学习:让Claude Code调研的时候,不只要“推荐什么”,也要问“有没有已知问题”。知道坑在哪,比知道怎么用更重要。

动手实现

架构和选型都清楚了,开始实现。两块合并在一节。

MCP Server管理

MCP Server管理和12讲Provider管理是同样的模式——CRUD + 连通性测试 + 启用禁用。04讲已经建了 mcp_server 表,直接实现接口。

在 hify-mcp 模块中实现 MCP Server 管理。参照 12 讲 Provider 管理的模式。

接口列表:
POST   /api/v1/mcp-servers              创建 MCP Server(name、endpoint、enabled)
GET    /api/v1/mcp-servers              分页查询列表
GET    /api/v1/mcp-servers/{id}         查询详情(含工具列表)
PUT    /api/v1/mcp-servers/{id}         更新
DELETE /api/v1/mcp-servers/{id}         逻辑删除
POST   /api/v1/mcp-servers/{id}/test    测试连通性

连通性测试逻辑:
  用 io.modelcontextprotocol.sdk:mcp:1.1.1 的 McpSyncClient
  调 tools/list 接口,成功则把返回的工具列表存入 mcp_tool 表
  (name、description、inputSchema JSON 字段)
  失败返回错误信息

删除时检查:是否有 Agent 绑定了该 Server 的工具,有则拒绝删除

实现 McpClientService:
  callTool(mcpServerId, toolName, arguments) → String
    按调用创建 McpSyncClient,用完关闭(try-with-resources)
    工具调用失败 catch 住,抛 BizException(MCP_TOOL_CALL_FAILED)
    结果取 TextContent,多条用换行拼接

  listTools(mcpServerId) → List<String>
    同样 try-with-resources,失败抛 BizException(MCP_SERVER_NOT_FOUND)

代码放在 hify-mcp 模块,遵循 CLAUDE.md 规范

和12讲Provider管理唯一的区别:连通性测试调 tools/list 而不是 /v1/models。CRUD逻辑、关联校验、启用禁用完全一样。

Agent绑定工具

新建 agent_tool 关联表,支持多工具绑定:

CREATE TABLE agent_tool (
    id        BIGINT   AUTO_INCREMENT PRIMARY KEY,
    agent_id  BIGINT   NOT NULL,
    tool_id   BIGINT   NOT NULL,
    created_at DATETIME NOT NULL,
    UNIQUE KEY uk_agent_tool (agent_id, tool_id)
);

实现接口:
PUT /api/v1/agents/{id}/tools    绑定工具列表(传 toolId 数组,全量替换)

约束:
- 绑定时校验 toolId 是否存在且对应 MCP Server 处于启用状态
- 一个 Agent 最多绑定 10 个工具(防止 tools 参数过长影响 LLM 效果)

接入对话引擎

这是对话引擎的第五次增量开发。

修改 ChatService 的对话逻辑,加入 MCP 工具调用支持。

改动范围:只改 buildMessages 和 LLM 调用这两处。

具体逻辑:
1. 加载 Agent 绑定的工具列表
   从 agent_tool 关联 mcp_tool 表,拿到所有工具的 name、description、inputSchema
2. 工具列表不为空时,把 tool schema 加入第一次 LLM 调用的 tools 参数
3. 第一次 LLM 调用后判断返回:
   finish_reason = "tool_calls":解析 tool_calls,执行第 4 步
   finish_reason = "stop":直接走原有流式推送逻辑
4. 解析 tool_calls,拿工具名和 arguments JSON
   从 mcp_tool 表找到对应的 mcpServerId
   调 McpClientService.callTool(mcpServerId, toolName, arguments)
5. 把工具结果作为 role=tool 的消息追加进对话历史
   对应上 tool_call_id(LLM 第一次返回的那个 id)
6. 发起第二次 LLM 调用(流式),结果推给用户

约束:
- 工具列表为空时,和原有逻辑完全一致,一行不改
- RAG 和工具调用不冲突:system prompt 里既可以有 RAG 检索结果,
  也可以有工具 schema,一个 Agent 可以同时绑知识库和工具
- workflowId 不为空时已经 return,不进入这段逻辑
- 工具调用失败:把错误信息作为 tool 消息返回给 LLM,
  让 LLM 告知用户,不要直接抛异常中断对话
- 不改 Controller 层,不改 SseEmitter 管理逻辑

增量开发三步走:

  • 先跑不绑工具的Agent,确认原有逻辑没坏(RAG、工作流都测)

  • 再跑绑了工具的Agent,问需要调工具的问题,确认Function Calling触发

  • 问不需要调工具的问题,确认LLM正确判断不调,没有发起多余的工具调用

验收

用一个模拟的MCP Server跑通。目的是验证Hify的MCP Client和对话引擎逻辑正确,不验证真实业务。真实Server下一讲做。

# 添加模拟 MCP Server
curl -X POST http://localhost:8080/api/v1/mcp-servers \
  -H "Content-Type: application/json" \
  -d '{"name": "订单服务(模拟)", "endpoint": "http://localhost:9001/mcp"}'

# 测试连通性,自动拉取工具列表
curl -X POST http://localhost:8080/api/v1/mcp-servers/1/test
# 返回:连通成功,发现工具 query_order(userId, orderId)

# 给智能客服绑定工具
curl -X PUT http://localhost:8080/api/v1/agents/1/tools \
  -H "Content-Type: application/json" \
  -d '{"toolIds": [1]}'

# 场景一:需要调工具的问题
curl -N -X POST http://localhost:8080/api/v1/chat/sessions/2/messages \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"content": "我的订单12345到哪了"}'
# 后端日志:
# [MCP] finish_reason=tool_calls,调用 query_order(userId=u001, orderId=12345)
# [MCP] 工具返回:运输中,SF1234567,预计明天到
# [MCP] 第二次 LLM 调用,finish_reason=stop
# 用户收到:"您的订单12345已发货,顺丰快递在途中,预计明天送达。"

# 场景二:不需要调工具的问题
curl -N -X POST http://localhost:8080/api/v1/chat/sessions/3/messages \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"content": "你们的退换货政策是什么"}'
# 后端日志:finish_reason=stop,没有工具调用
# 走 RAG 引用知识库回答

# 场景三:不绑工具的 Agent 不受影响
curl -N -X POST http://localhost:8080/api/v1/chat/sessions/4/messages \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"content": "你好"}'
# 日志里没有任何 MCP 相关输出

下面是我们实现的在MCP工具的管理:

总结

这一讲搞懂了MCP,把Client跑通了。

从需求出发:Agent要能做事,就需要调外部系统。直接调API维护成本高,MCP用标准化协议解决,工具提供方描述自己,调用方统一调用,M×N变成M+N。

Function Calling是核心机制:第一次LLM调用判断要不要调工具、调哪个,Hify执行工具调用,第二次LLM调用基于结果生成回答。 description 写得好不好,直接决定LLM选工具的准确率。

选型上,Spring AI MCP太重,Hify已有自己的LLM调用体系,引进去只会产生两套抽象互相摩擦。官方Java SDK刚好够用,只做协议层,连接管理和错误处理按Hify现有风格写。

对话引擎这是第五次增量开发。从16讲到现在——基础链路、上下文、RAG、工作流、MCP工具——每次都是同样的三步走,每次都没破坏已有功能。 增量开发是一种习惯,不是方法论。

下一讲做真实的MCP Server,不是模拟返回,而是真正查数据库,从业务场景推导到代码实现。

思考题

  1. 当前的工具调用是同步的,用户要等工具执行完才能看到回复。如果工具很慢(查一个复杂报表要10秒),用户体验会很差。怎么给用户一个“正在查询订单信息…”的中间状态提示?让Claude Code帮你设计方案。

  2. 如果LLM在一次回复中需要调用多个工具(比如先查订单状态再查物流信息),当前的实现支持吗?Claude Code在解释Function Calling时提到了parallel tool calls,看一下OpenAI文档,理解多工具调用的消息结构,让Claude Code帮你实现。

  3. 工具调用有安全风险,如果LLM被提示词注入攻击,可能会调用不该调的工具(比如用户伪造消息让客服帮别人查订单)。怎么在Hify层面做工具调用的权限控制?

期待你的分享!如果今天的课程让你有所收获,也欢迎转发给有需要的朋友,邀请他来一起学习,我们下节课再见!