Spring注解集成Claude API调用业务接口实战

MCP协议目前仍在快速演进，其中Streamable-HTTP是最近才定稿的传输协议，相比SSE更适合云原生无状态部署场景。另外需要注意的是，Spring AI的注解API在各个里程碑版本之间可能会有调整，遇到问题时，首先确认使用的版本与文档是否对应。

去年年底，团队里有同事提出一个需求：如何让Claude直接查询我们系统的订单状态？当时的第一反应，自然是走Function Calling这条路——把接口描述塞进Prompt，让模型按格式返回参数，然后在业务层拦截调用。折腾了两天，流程虽然跑通了，但代码实在不够优雅：换一个模型就得重新适配一套格式，换到Cursor又要再折腾一遍。

后来接触到MCP，只用了五分钟就把同一个接口接入了Claude Desktop，在Cursor里也能直接使用，核心代码仅仅是增加了三个注解。这其中的差异和具体实现，正是本文要详细拆解的内容。

MCP与Function Calling的本质区别

这两项技术经常被混为一谈，但它们本质上解决的是不同层面的问题。

Function Calling是Prompt级别的能力。你在单次请求中告诉模型“目前有这些函数可用，参数格式如下”，由模型决定是否调用，并返回一个结构化的调用指令。随后，你的代码去执行这个指令，再将结果塞回给模型。整个过程紧密绑定在一次模型请求的生命周期内，工具描述随着Prompt流动。这意味着，更换模型通常需要重写一遍格式，更换AI客户端也需要重新适配一套接口。

MCP（Model Context Protocol）则是协议级别的能力。你的服务可以独立部署为一个MCP Server，任何支持MCP协议的客户端——无论是Claude Desktop、Cursor，还是自己编写的Agent——都能自动发现并调用其中定义的工具。它不依赖于具体模型，实现了“一次开发，到处复用”。

Anthropic在2024年11月开源了MCP规范，目前Claude、ChatGPT、VS Code Copilot、Cursor、Gemini等主流AI工具均已支持，公开的MCP Server数量已超过5000个。可以将其理解为AI工具调用的“USB-C接口”：过去每种设备都需要特定的线缆，而现在有了统一的标准。

Function Calling vs MCP 架构对比示意图

MCP协议定义了三种核心原语：Tool（AI可以执行的有副作用操作）、Resource（AI可以读取的幂等只读数据）以及Prompt（预置的提示词模板）。Spring AI为这三者都提供了对应的注解支持。

环境准备：引入依赖

从Spring AI 1.0.0-M6版本开始，提供了MCP Server的Starters。你需要根据选择的传输协议引入对应的依赖（协议选型后续会详细说明）：

    org.springframework.ai
    spring-ai-starter-mcp-server-webmvc

    org.springframework.ai
    spring-ai-starter-mcp-server-webflux

    org.springframework.ai
    spring-ai-starter-mcp-server

推荐使用BOM进行版本管理，以避免潜在的依赖冲突：

    
        
            org.springframework.ai
            spring-ai-bom
            1.0.0-M7
            pom
            import
        
    

前置环境要求为Ja va 17+和Spring Boot 3.2+。

@McpTool：将现有方法暴露为AI工具

在任何Spring Bean的方法上添加@McpTool注解，Spring AI便会自动将其扫描并注册为MCP Tool，同时自动生成JSON Schema，无需手动编写。

来看一个实际例子，将订单查询接口暴露出去：

import org.springframework.ai.mcp.spring.annotation.McpTool;
import org.springframework.ai.mcp.spring.annotation.McpToolParam;
import org.springframework.stereotype.Component;

@Component
public class OrderMcpTools {
    private final OrderService orderService;

    public OrderMcpTools(OrderService orderService) {
        this.orderService = orderService;
    }

    @McpTool(
        name = "queryOrder",
        description = "根据订单号查询订单状态和详情，支持查询最近 90 天内的订单。" +
                      "返回字段包括：订单状态、实付金额、下单时间、收货地址、物流单号。"
    )
    public OrderDetail queryOrder(
        @McpToolParam(description = "订单号，格式为 ORD-XXXXXXXXXX，10 位数字后缀", required = true)
        String orderId,
        @McpToolParam(description = "是否返回商品明细列表，默认 false，true 时额外返回每个商品的名称和数量")
        boolean includeItems
    ) {
        // 直接复用现有业务逻辑，无需修改
        return orderService.getOrderDetail(orderId, includeItems);
    }

    @McpTool(
        name = "listRecentOrders",
        description = "查询用户最近的订单列表，返回最多 20 条，按下单时间倒序排列"
    )
    public List listRecentOrders(
        @McpToolParam(description = "用户 ID，Long 类型", required = true) Long userId,
        @McpToolParam(description = "查询天数范围，1-90 之间，默认 30") int days
    ) {
        return orderService.listRecentOrders(userId, days);
    }
}

description的写法至关重要——这是模型决定“是否调用此工具”以及“如何填充参数”的主要依据，而非写给开发者的注释。像“订单号，格式为 ORD-XXXXXXXXXX，10 位数字后缀”这样的描述，就比简单的“the order ID”包含更多有效信息，能帮助模型更准确地推断参数。

在application.yml中开启注解扫描：

spring:
  ai:
    mcp:
      server:
        type: SYNC          # SYNC 同步 / ASYNC 响应式
        protocol: SSE       # 传输协议
        annotation-scanner:
          enabled: true

正常启动Spring Boot应用后，MCP Server便已就绪。

Spring AI MCP Server 内部架构图

这里有个容易踩的坑：方法的返回值必须是可JSON序列化的。如果OrderDetail中包含LocalDateTime类型的字段，需要确保Jackson配置了时间模块（例如jackson-datatype-jsr310），否则模型收到的将是序列化异常，而非工具执行结果。另一个更隐蔽的问题是Optional类型，Jackson默认不会特殊处理，直接返回T或null会更稳妥。

传输协议选型：STDIO、SSE与Streamable-HTTP

Spring AI MCP Server支持三种传输协议，选型错误可能导致本地可用但生产环境无法运行，或者部署方式不匹配。

STDIO模式最容易出问题：当Claude Desktop使用STDIO协议时，它会将你的Spring Boot应用作为子进程直接启动。这意味着服务不能监听额外的HTTP端口（否则会产生冲突），并且绝对不能在代码中使用System.out.println——标准输出已被MCP协议占用，随意打印日志会污染消息帧，导致工具调用解析失败。解决方案是将所有日志重定向到文件或stderr：

    System.err
    
        %d{HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n
    

生产环境推荐使用SSE：它基于持久的HTTP连接，服务端可以主动推送工具执行进度。多个AI客户端可以同时连接，服务可以像普通的Spring Boot应用一样独立部署，并与现有的REST接口共享同一个端口。

Streamable-HTTP则更适合无状态部署场景：每次请求都是独立的，没有持久连接，在K8s环境中进行横向扩容时，无需考虑连接亲和性问题。如果你的服务部署在带有负载均衡的环境中，可以优先考虑此协议。

配置Claude Desktop连接你的MCP Server

STDIO模式（本地调试最方便）：

找到Claude Desktop的配置文件——macOS在~/Library/Application Support/Claude/claude_desktop_config.json，Windows在%APPDATA%\Claude\claude_desktop_config.json——添加如下配置：

{
  "mcpServers": {
    "order-service": {
      "command": "ja va",
      "args": [
        "-jar",
        "/absolute/path/to/your-mcp-server.jar"
      ]
    }
  }
}

SSE模式（服务已独立部署）：

{
  "mcpServers": {
    "order-service": {
      "url": "http://localhost:8080/sse"
    }
  }
}

如果服务端需要鉴权，可以在请求头中携带Token：

{
  "mcpServers": {
    "order-service": {
      "url": "http://your-server/sse",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

重启Claude Desktop后，工具栏会出现一个锤子图标，点击即可看到所有已注册的MCP Tool名称和描述。此时，直接在对话框中输入“帮我查一下订单 ORD-20260425001 的状态”，Claude会自动识别出需要调用queryOrder工具，填入参数、执行，并将结果转换为自然语言回复。

Claude Desktop 调用 MCP Server 完整时序图

进阶应用：使用@McpResource暴露只读数据

@McpTool适用于“执行操作”的场景（如下单、更新状态），而@McpResource则更适合“读取数据”（如商品详情、配置项）。两者的区别在于语义和使用时机：Resource是幂等且只读的，AI客户端在构建上下文时会主动拉取这些数据，而不是等到需要执行操作时才去调用。

@Component
public class ProductMcpResources {
    @McpResource(
        uri = "product://{productId}/info",
        name = "商品信息",
        description = "根据商品 ID 获取商品基本信息，包括价格、库存状态、分类"
    )
    public String getProductInfo(String productId) {
        Product product = productService.findById(productId);
        // Resource 返回字符串，可以是 JSON 格式或结构化文本
        return objectMapper.writeValueAsString(product);
    }

    @McpResource(
        uri = "config://feature-flags",
        name = "功能开关配置",
        description = "返回当前所有功能开关的状态，供 AI 了解系统当前支持的能力"
    )
    public String getFeatureFlags() {
        return featureFlagService.getAllFlags().toString();
    }
}

在实际使用中，@McpResource在“让AI了解你的系统状态”这一场景下特别有用。例如，先让AI读取功能开关配置，再决定推荐哪些操作，逻辑上比每次调用Tool更为清晰。

常见问题解答

Q：对现有服务进行改造需要改动多少代码？
只需添加依赖、编写一个@Component包装类来调用现有的Service，并在方法上添加注解。无需修改任何现有业务逻辑，原有的REST接口可以照常工作，两套机制可以并存，互不影响。

Q：如何编写有效的description？
描述信息的受众是AI模型，而非开发者。需要说清楚：工具是做什么的、适用于什么场景、参数有哪些限制（格式、范围、枚举值、默认值）。例如，“查询订单”这个描述就远不如“根据订单号查询，仅支持90天内的订单，返回状态和物流信息”来得有效，后者能为模型填充参数提供更充分的依据。

Q：MCP与Spring AI的FunctionCallback是什么关系？
这是两套完全独立的机制。FunctionCallback是你在编写自己的AI应用时，为模型Prompt绑定工具（即Function Calling）的方式；而@McpTool则是将你的服务暴露给外部AI客户端（遵循MCP协议）。两者可以同时使用——例如，你的服务既可以作为一个MCP Server供外部客户端调用，内部也可以使用FunctionCallback来驱动自己的业务AI流程。

Q：STDIO和SSE模式下如何配置日志？
在STDIO模式下，System.out会污染MCP消息流，因此必须将所有日志重定向到文件或stderr，例如将logback.xml中Console Appender的target改为System.err。SSE模式则没有这个限制，按正常方式配置即可。

Q：生产环境需要鉴权吗？
MCP协议本身没有内置鉴权机制，默认情况下任何人都可以调用你的MCP Server。在生产环境中，建议在Spring Security层添加HTTP Bearer Token或API Key验证，然后在客户端的配置文件中的headers字段里携带凭证。

说到底，MCP解决的核心问题是“工具定义与模型解耦”——你只需编写一次，任何支持MCP的AI客户端都能使用，无需随着每个模型的格式差异而反复调整。这个方向无疑是正确的，其生态成熟度也在快速提升。