写在前面
上一篇搭了Spring Boot + AI Agent的CRUD自动生成框架。有读者问：怎么让Agent不只是写代码，而是真正调用公司内部系统？

这就得说MCP协议了。

MCP（Model Context Protocol）是Anthropic在2024年底开源的协议，目的就一个：让AI能标准化地调用任何外部工具。 数据库查询、API调用、文件操作——统统用一套协议搞定。目前已经是AI Agent接入企业系统的实际标准。

这篇文章教你三件事：

MCP协议到底怎么工作的（用Spring Boot实现一个MCP Server）
如何把公司内部API注册为MCP Tool让AI调用
实战：2天搭建一个能查订单、改状态、发通知的智能客服
环境：Spring Boot 3.3.0 + JDK 21 + Maven。MCP协议版本：2024-11-05。

一、先搞清楚MCP解决了什么问题
在没有MCP之前，让AI调用你的内部系统是地狱模式。

你有一个订单查询API、一个库存API、一个通知API。想让AI Agent帮用户"查我的订单状态，如果发货了发个通知"——这需要AI能调用这三个API。

传统做法是每次换一个AI平台就重新写一套适配代码。你用OpenAI的Function Calling写了一遍，换到Claude又得写一遍，换成国产AI又得写一遍。代码散落在各个AI平台的SDK里，维护成本巨高。

MCP的解法是一套标准：你的系统只需要实现一个MCP Server，任何支持MCP协议的AI客户端都能直接调用。 不再和特定AI平台绑定。你的系统作为一个MCP Server暴露Tools（可调用的功能），AI Agent作为MCP Client来调用。

二、搭建MCP Server：15分钟出原型
新建Spring Boot项目，pom.xml加MCP依赖。

注意：截至2026年7月，Spring AI的MCP支持还在快速迭代中，以官方最新文档为准。

xml

org.springframework.boot spring-boot-starter-web org.springframework.ai spring-ai-mcp-server 1.0.0-M3 spring-milestones https://repo.spring.io/milestone 三、定义你的第一个MCP Tool Tool是MCP的核心概念——就是"AI能调用的一个功能"。每个Tool有三个要素：名称（AI用来识别该调哪个）、描述（AI用来理解这个Tool能干什么）、参数Schema（AI用来知道该传什么参数）。

先写一个最简单的订单查询Tool：

java
package com.example.mcpserver.tool;

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;

@Component
public class OrderQueryTool {

@Tool(description = "根据订单ID查询订单详情，包括订单状态、商品列表、收货地址、物流信息")
public OrderInfo queryOrder(
        @ToolParam(description = "订单ID，格式为ORD开头加数字，如ORD12345") String orderId) {
    
    // 实际项目里这里调数据库或远程API
    // 为了演示，用模拟数据
    if (!orderId.startsWith("ORD")) {
        throw new IllegalArgumentException("订单ID格式错误，应为ORD开头");
    }
    
    OrderInfo order = new OrderInfo();
    order.setOrderId(orderId);
    order.setStatus("已发货");
    order.setTotalAmount(299.00);
    order.setTrackingNumber("SF1234567890");
    order.setDeliveryAddress("广东省深圳市南山区科技园");
    order.setItems(List.of(
        new OrderItem("罗技鼠标 G502", 199.00, 1),
        new OrderItem("机械键盘 IKBC C87", 100.00, 1)
    ));
    
    return order;
}

}
关键注解说明：

@Tool 声明这是一个MCP Tool，description是AI用来理解这个Tool功能的
@ToolParam 声明参数，description告诉AI该传什么格式的数据
description的质量直接决定了AI能不能正确调用你的Tool——写详细点没坏处
四、加上业务操作Tool
查询只是第一步。让AI能修改订单状态、发送通知：

java
package com.example.mcpserver.tool;

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;

@Component
public class OrderActionTool {

@Tool(description = "修改订单状态。支持的status值：PAID-已支付, SHIPPED-已发货, DELIVERED-已签收, CANCELLED-已取消。" +
        "注意：已发货和已签收的订单不能取消，已完成订单状态不能回退")
public String updateOrderStatus(
        @ToolParam(description = "订单ID") String orderId,
        @ToolParam(description = "新状态") String status,
        @ToolParam(description = "操作原因，用于审计日志") String reason) {
    
    // 业务规则校验
    String currentStatus = queryCurrentStatus(orderId);
    
    if ("CANCELLED".equals(status) && 
        ("SHIPPED".equals(currentStatus) || "DELIVERED".equals(currentStatus))) {
        return "操作失败：已发货或已签收的订单不能取消。当前状态：" + currentStatus;
    }
    
    // 实际调数据库更新（此处省略）
    // orderRepository.updateStatus(orderId, status, reason);
    
    return "订单" + orderId + "状态已更新为" + status + "，原因：" + reason;
}

@Tool(description = "给订单关联的用户发送通知。type支持：SMS-短信, EMAIL-邮件, APP-应用内推送。" +
        "发送前需要确认用户已允许接收该类通知")
public String sendNotification(
        @ToolParam(description = "订单ID") String orderId,
        @ToolParam(description = "通知类型") String type,
        @ToolParam(description = "通知内容，不超过200字") String content) {
    
    // 检查用户通知偏好
    // 实际调通知服务发送
    return "已通过" + type + "向订单" + orderId + "的用户发送通知：" + content;
}

private String queryCurrentStatus(String orderId) {
    // 实际查数据库
    return "PAID";
}

}
五、配置MCP Server端点
在application.yml中配置MCP Server：

yaml
spring:
ai:
mcp:
server:
name: “智能客服系统”
version: “1.0.0”
protocol-version: “2024-11-05”
enabled: true
transport: SSE # Server-Sent Events方式，支持流式响应
sse-endpoint: /mcp/sse
sse-message-endpoint: /mcp/messages
启动项目后，MCP Server会自动暴露这些端点。AI客户端就可以通过它们发现并调用你注册的所有Tools。

六、验证：用MCP Inspector测试你的Tool
Spring AI提供的MCP Inspector（调试工具）可以直接在浏览器测试Tool是否正确注册：

java
// 启动类加个健康检查端点
@RestController
@RequestMapping(“/health”)
public class HealthController {

@GetMapping("/tools")
public Map<String, Object> listTools() {
    // 返回已注册的Tool列表，方便调试
    return Map.of(
        "tools", List.of(
            Map.of("name", "queryOrder", "description", "查询订单详情"),
            Map.of("name", "updateOrderStatus", "description", "修改订单状态"),
            Map.of("name", "sendNotification", "description", "发送用户通知")
        ),
        "mcpServer", "运行中",
        "endpoint", "/mcp/sse"
    );
}

}
启动后访问 http://localhost:8080/health/tools 能看到已注册的三个Tool，确认MCP Server正常工作。

七、接入AI Agent：让AI调用你的Tool
MCP Server搭好后，任何支持MCP协议的AI客户端都能连上来。以Claude Desktop为例，在它的MCP配置里加一行：

json
{
“mcpServers”: {
“智能客服”: {
“url”: “http://your-server:8080/mcp/sse”
}
}
}
配置完成后，你打开Claude Desktop，它就能看到你的工具了。对话测试：

用户：帮我查一下订单ORD12345的状态
Claude：[自动调用你MCP Server上的queryOrder Tool]
返回：订单ORD12345，状态：已发货，物流单号：SF1234567890

用户：发货了是吧，那帮我发个短信通知用户
Claude：[自动调用sendNotification Tool]
已通过SMS向订单ORD12345的用户发送通知
八、踩坑记录
坑1：Tool描述写得不够详细，AI不会调。

如果你的@Tool description只写了"查询订单"，AI不知道什么场景该调它、传什么参数。详细的描述应该告诉AI：这个Tool干什么用、什么场景下该用、参数格式是什么、返回值包含哪些字段。

坑2：参数校验要在Tool内部做。

AI可能传各种奇怪的参数进来。空字符串、乱七八糟的ID格式、不存在的订单号——必须在你自己的Tool代码里做充分的参数校验和错误返回。

坑3：敏感操作需要确认机制。

像"取消订单""退款"这种操作，不应让AI自动执行。在Tool的实现里加一个确认步骤——比如让AI先展示操作的详细信息，得到用户确认后再执行。

java
@Tool(description = “发起退款操作。注意：这是一个敏感操作，执行前必须在对话中向用户确认退款金额和原因”)
public String refund(@ToolParam String orderId, @ToolParam Double amount, @ToolParam String reason) {
// AI会在调用前先向用户确认，因为description里写了
log.warn(“退款操作：orderId={}, amount={}, reason={}”, orderId, amount, reason);
// 实际调用退款服务
return “退款申请已提交，预计3-5个工作日到账”;
}
九、总结
搞完这三步，你就有了一套可复用的MCP能力。

第一步，用Spring AI MCP把公司内部API包装成标准Tool。第二步，任何支持MCP的AI客户端都能直接调用，不再绑定特定平台。第三步，安全操作加确认机制，敏感数据不出内网。

后续可以扩展的方向：数据库直连Tool（让AI自己拼SQL？不，用预定义的查询方法和参数化调用）、权限集成（接入SSO，Tool内部读取当前用户权限决定返回哪些数据）、多Agent协作（一个Agent负责查订单，另一个负责客服话术，用MCP串联）。

如果这篇对你有用，点赞收藏支持一下。