Spring AI MCP Server 配置指南

2026-06-15 01:22
3
0

创建时间: 2026-06-11
适用范围: Spring AI 1.0.x ~ 1.1.x
问题背景: MCP Server 端点 404、Tool 未注册、自动配置失效等问题排查总结

一、问题现象

1.1 典型错误

org.springframework.web.servlet.resource.NoResourceFoundException: No static resource mcp.

客户端连接时报错：

[ERROR] [MCP] Failed to connect upstream server...

1.2 启动日志特征

正常情况应包含：
- McpServerAnnotationScannerAutoConfiguration 加载日志
- Tool 注册日志（如 "Registered X MCP tools"）
- 端点路径注册日志

异常情况：
- 完全没有 MCP 相关日志（自动配置静默失效）
- 有自动配置日志但显示 "No tool methods found"（Tool 未注册）
- 启动成功但访问端点 404（端点未正确注册）

二、版本差异与配置要点

2.1 Spring AI 1.0.0（⚠️ 存在已知 Bug）

问题: MCP 自动配置在某些环境下会完全静默失效（GitHub Issue #4055）

依赖配置:

<properties>
    <spring-ai.version>1.0.0</spring-ai.version>
</properties>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
    <version>${spring-ai.version}</version>
</dependency>

注解使用:

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

@Component
public class MyMcpTool {

    @Tool(name = "my_tool", description = "工具描述")
    public String myMethod(
        @ToolParam(description = "参数描述", required = true) String param1) {
        // 实现逻辑
    }
}

application.yml 配置:

spring:
  ai:
    mcp:
      server:
        name: my-mcp-server
        version: 1.0.0
        type: SYNC
        protocol: SSE  # 1.0.0 使用 SSE 协议
        sse-endpoint: /mcp/sse
        sse-message-endpoint: /mcp/message
        annotation-scanner:
          enabled: true  # 必须显式启用
        capabilities:
          tool: true
          resource: false
          prompt: false

⚠️ 已知问题:
1. 自动配置可能在某些条件下静默失效
2. 即使配置正确，也可能出现 Tool 未注册的情况
3. 建议: 升级到 1.0.7+ 或 1.1.x

2.2 Spring AI 1.0.7 / 1.0.8（✅ 修复版）

改进: 修复了自动配置问题（commit: 4b21612）

依赖配置:

<properties>
    <spring-ai.version>1.0.7</spring-ai.version>
</properties>

注解使用: 与 1.0.0 相同，使用 @Tool 和 @ToolParam

配置: 与 1.0.0 相同，但自动配置更稳定

2.3 Spring AI 1.1.6 / 1.1.7（✅ 推荐版本）

重大变化:
1. 注解从 @Tool 改为 @McpTool
2. 参数注解从 @ToolParam 改为 @McpToolParam
3. 包路径从 org.springframework.ai.tool.annotation 改为 org.springaicommunity.mcp.annotation
4. SSE 协议被 STREAMABLE 协议替代
5. 新增 base-url 配置项

依赖配置:

<properties>
    <spring-ai.version>1.1.7</spring-ai.version>
</properties>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
    <version>${spring-ai.version}</version>
</dependency>

✅ 正确的注解使用:

import org.springaicommunity.mcp.annotation.McpTool;
import org.springaicommunity.mcp.annotation.McpToolParam;

@Component
public class MyMcpTool {

    @McpTool(name = "my_tool", description = "工具描述")
    public String myMethod(
        @McpToolParam(description = "参数描述", required = true) String param1) {
        // 实现逻辑
    }
}

❌ 错误的注解使用（会导致编译失败）:

// 错误1: 使用旧注解
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;

// 错误2: import 包路径错误
import org.springframework.ai.tool.annotation.McpTool;  // 这个包不存在！

// 错误3: 混用新旧注解
import org.springaicommunity.mcp.annotation.McpTool;
import org.springframework.ai.tool.annotation.ToolParam;  // 不一致！

application.yml 配置:

spring:
  ai:
    mcp:
      server:
        name: my-mcp-server
        version: 1.0.0
        type: SYNC  # 或 ASYNC
        protocol: STREAMABLE  # ✅ 1.1.x 推荐使用 STREAMABLE
        base-url: /mcp  # ✅ MCP 端点基础路径
        # ❌ 不再使用以下配置（SSE 专用）
        # sse-endpoint: /mcp/sse
        # sse-message-endpoint: /mcp/message
        instructions: "MCP Server 描述信息"
        annotation-scanner:
          enabled: true  # 必须启用
        capabilities:
          tool: true
          resource: false
          prompt: false

三、协议选择

3.1 SSE 协议（已废弃）

适用版本: Spring AI 1.0.x

配置:

protocol: SSE
sse-endpoint: /mcp/sse
sse-message-endpoint: /mcp/message

端点:
- SSE 连接端点: /mcp/sse
- 消息发送端点: /mcp/message

⚠️ 缺点:
- 需要两个端点，配置复杂
- 已被官方标记为废弃
- 在某些环境下可能不稳定

3.2 STREAMABLE 协议（✅ 推荐）

适用版本: Spring AI 1.1.x

配置:

protocol: STREAMABLE
base-url: /mcp

端点: 统一的 /mcp 端点

✅ 优点:
- 配置简单，只需一个 base-url
- 官方推荐，替代 SSE
- 支持 HTTP POST/GET 和可选的 SSE 流式响应
- 更稳定

3.3 协议对比

特性 SSE STREAMABLE
端点数量 2个 1个
配置复杂度 高 低
官方状态 已废弃 推荐
适用版本 1.0.x 1.1.x
稳定性 一般 好

四、常见问题与解决方案

4.1 问题：端点 404 - NoResourceFoundException

可能原因:
1. 协议配置错误（SSE 协议访问 /mcp 而不是 /mcp/sse）
2. 自动配置未生效
3. 手动定义的 Bean 冲突

解决方案:

方案1: 升级到 1.1.7 + 使用 STREAMABLE 协议

protocol: STREAMABLE
base-url: /mcp

方案2: 检查是否有冲突的 Bean 定义

❌ 错误做法（会导致自动配置失效）:

@Configuration
public class McpConfig {
    @Bean
    public ToolCallbackProvider toolCallbackProvider() {
        return MethodToolCallbackProvider.builder()
                .toolObjects(listMcpTool, todoMcpTool)
                .build();
    }

    @Bean
    public McpSchema.ServerCapabilities.Builder capabilitiesBuilder() {
        return McpSchema.ServerCapabilities.builder().tools(true);
    }
}

✅ 正确做法: 删除上述配置类，完全依赖自动配置

4.2 问题：编译失败 - 找不到 McpTool / McpToolParam

错误信息:

[ERROR] 找不到符号
  符号:   类 McpTool
  位置: 程序包 org.springframework.ai.tool.annotation

原因: import 包路径错误

解决方案:

✅ Spring AI 1.1.x 正确的 import:

import org.springaicommunity.mcp.annotation.McpTool;
import org.springaicommunity.mcp.annotation.McpToolParam;

❌ 错误的 import（这个包不存在）:

import org.springframework.ai.tool.annotation.McpTool;

✅ Spring AI 1.0.x 正确的 import:

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

4.3 问题：Tool 未注册 - "No tool methods found"

启动日志:

No tool methods found in the provided tool objects: []

可能原因:
1. 注解使用错误（混用新旧注解）
2. 类没有添加 @Component 注解
3. 包扫描路径不包含 MCP Tool 类
4. 重复的 import 导致混淆

解决方案:

检查清单:
- [ ] 确认使用正确版本的注解（1.0.x 用 @Tool，1.1.x 用 @McpTool）
- [ ] 确认 import 包路径正确
- [ ] 确认类上有 @Component 注解
- [ ] 清理重复的 import 语句
- [ ] 确认 annotation-scanner.enabled: true

示例:

package com.todoflow.mcp.tool;  // 确保在扫描路径内

import org.springaicommunity.mcp.annotation.McpTool;
import org.springaicommunity.mcp.annotation.McpToolParam;
import org.springframework.stereotype.Component;

@Component  // ✅ 必须添加
public class MyMcpTool {

    @McpTool(name = "my_tool", description = "描述")
    public String myMethod(
        @McpToolParam(description = "参数", required = true) String param) {
        return "result";
    }
}

4.4 问题：自动配置静默失效

特征: 启动日志中完全没有 MCP 相关内容

原因: 
- Spring AI 1.0.0 的已知 Bug（Issue #4055）
- 某些环境下自动配置类未被正确加载

解决方案:

方案1: 升级到 1.0.7+ 或 1.1.x

方案2: 显式启用自动配置（临时方案）

spring:
  ai:
    mcp:
      server:
        annotation-scanner:
          enabled: true

方案3: 添加调试日志查看自动配置状态

debug: true  # 仅用于调试

五、完整配置示例

5.1 Spring AI 1.1.7 + STREAMABLE（✅ 推荐）

pom.xml:

<properties>
    <spring-ai.version>1.1.7</spring-ai.version>
</properties>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
    <version>${spring-ai.version}</version>
</dependency>

application.yml:

server:
  port: 8080
  servlet:
    context-path: /todoflow

spring:
  ai:
    mcp:
      server:
        name: todoflow-mcp-server
        version: 1.0.0
        type: SYNC
        protocol: STREAMABLE
        base-url: /mcp
        instructions: "TodoFlow MCP Server - 提供清单、待办、计划等功能"
        annotation-scanner:
          enabled: true
        capabilities:
          tool: true
          resource: false
          prompt: false

MCP Tool 示例:

package com.todoflow.mcp.tool;

import org.springaicommunity.mcp.annotation.McpTool;
import org.springaicommunity.mcp.annotation.McpToolParam;
import org.springframework.stereotype.Component;

@Slf4j
@Component
public class ListMcpTool {

    @McpTool(name = "list_my_lists", description = "获取当前用户的所有清单列表")
    public String listMyLists(
            @McpToolParam(description = "列表类型", required = false) String type) {
        Long userId = UserContextHolder.getCurrentUserId();
        log.info("MCP调用: list_my_lists, userId={}, type={}", userId, type);
        // 实现逻辑
        return result;
    }
}

访问端点: http://localhost:8080/todoflow/mcp

5.2 Spring AI 1.0.7 + SSE

pom.xml:

<properties>
    <spring-ai.version>1.0.7</spring-ai.version>
</properties>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
    <version>${spring-ai.version}</version>
</dependency>

application.yml:

spring:
  ai:
    mcp:
      server:
        name: todoflow-mcp-server
        version: 1.0.0
        type: SYNC
        protocol: SSE
        sse-endpoint: /mcp/sse
        sse-message-endpoint: /mcp/message
        annotation-scanner:
          enabled: true
        capabilities:
          tool: true
          resource: false
          prompt: false

MCP Tool 示例:

package com.todoflow.mcp.tool;

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

@Slf4j
@Component
public class ListMcpTool {

    @Tool(name = "list_my_lists", description = "获取当前用户的所有清单列表")
    public String listMyLists(
            @ToolParam(description = "列表类型", required = false) String type) {
        Long userId = UserContextHolder.getCurrentUserId();
        log.info("MCP调用: list_my_lists, userId={}, type={}", userId, type);
        // 实现逻辑
        return result;
    }
}

访问端点: 
- SSE 连接: http://localhost:8080/todoflow/mcp/sse
- 消息发送: http://localhost:8080/todoflow/mcp/message

六、版本升级检查清单

6.1 从 1.0.x 升级到 1.1.x

  • [ ] 修改 pom.xml 中的 spring-ai.version
  • [ ] 全局替换注解：
  • @Tool → @McpTool
  • @ToolParam → @McpToolParam
  • [ ] 全局替换 import：
  • org.springframework.ai.tool.annotation.Tool → org.springaicommunity.mcp.annotation.McpTool
  • org.springframework.ai.tool.annotation.ToolParam → org.springaicommunity.mcp.annotation.McpToolParam
  • [ ] 修改 application.yml：
  • protocol: SSE → protocol: STREAMABLE
  • 删除 sse-endpoint 和 sse-message-endpoint
  • 添加 base-url: /mcp
  • [ ] 删除手动定义的 MCP 配置类（如 McpConfig.java）
  • [ ] 清理重复的 import 语句
  • [ ] 重新编译并测试

6.2 编译后验证

运行以下命令检查 Tool 是否注册：

mvn clean compile

启动服务后检查日志：
- 应包含 "Registered X MCP tools" 或类似日志
- 不应包含 "No tool methods found"

6.3 端点测试

使用 curl 测试端点：

curl -X POST http://localhost:8080/todoflow/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

应返回 Tool 列表而不是 404 错误。

七、调试技巧

7.1 启用自动配置日志

debug: true
logging:
  level:
    org.springframework.ai: DEBUG
    org.springaicommunity.mcp: DEBUG

7.2 检查 Bean 注册情况

在启动类中添加：

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        var context = SpringApplication.run(Application.class, args);

        // 查看所有 MCP Tool Bean
        String[] toolBeans = context.getBeanNamesForAnnotation(McpTool.class);
        System.out.println("MCP Tool Beans: " + Arrays.toString(toolBeans));
    }
}

7.3 检查端点注册情况

启动后访问：

http://localhost:8080/todoflow/actuator/mappings

查看 /mcp 路径是否被正确注册。

八、总结

8.1 版本选择建议

版本 推荐度 说明
1.0.0 ❌ 不推荐 存在自动配置 Bug
1.0.7/1.0.8 ⚠️ 可用 修复了 Bug，但使用旧注解
1.1.6/1.1.7 ✅ 强烈推荐 最新稳定版，使用新注解和 STREAMABLE 协议

8.2 关键配置项

配置项 1.0.x 1.1.x
注解 @Tool / @ToolParam @McpTool / @McpToolParam
import 包 org.springframework.ai.tool.annotation org.springaicommunity.mcp.annotation
协议 SSE STREAMABLE（推荐）
端点配置 sse-endpoint + sse-message-endpoint base-url
自动配置 可能失效 稳定

8.3 常见陷阱

  1. ⚠️ 混用新旧注解：导致编译失败或 Tool 未注册
  2. ⚠️ import 包路径错误：McpTool 不在 org.springframework.ai.tool.annotation 包下
  3. ⚠️ 手动定义 Bean 冲突：覆盖自动配置导致 Tool 未注册
  4. ⚠️ 协议与端点不匹配：SSE 协议访问 /mcp 而不是 /mcp/sse
  5. ⚠️ 重复的 import：导致注解扫描器混淆

九、参考资料

文档维护: 本应根据 Spring AI 官方文档更新，最后验证版本：1.1.7（2026-05-23 发布）

全部评论

copyright @ 2018~2024 cyxCoder（www.cyxcoder.cn）

粤ICP备2024315764号