SpringAI MCP-stdio协议实战：构建标准化AI工具集成方案

如果你正在使用 SpringAI 开发智能应用，可能会遇到这样的困境：想要调用外部工具或服务来增强 AI 能力，却发现每个工具都需要单独集成，配置复杂且难以复用。这种"工具集成地狱"正是 MCP（Model Context Protocol）协议要解决的核心问题。

最近，随着 Claude Code 等智能编码助手的普及，MCP 协议正在成为连接 AI 与外部工具的新标准。而 SpringAI 作为 Java 生态中最流行的 AI 应用框架，其对 MCP 的支持程度直接决定了 Java 开发者能否高效构建下一代智能应用。

本文将深入解析 MCP-stdio 在 SpringAI 中的完整实现方案。不同于简单的 API 调用教程，我们会从协议原理出发，通过一个真实的数据库查询工具案例，展示如何构建生产可用的 MCP Server，并解决实际开发中的权限控制、错误处理和性能优化等关键问题。

1. 这篇文章真正要解决的问题

在传统 AI 应用开发中，工具集成往往面临三大痛点：

工具碎片化问题：每个外部服务（数据库、API、文件系统）都需要单独开发适配器，代码重复且维护成本高。比如查询数据库可能需要写专门的 DAO 层，调用天气 API 又要写一套 HTTP 客户端。

上下文管理复杂：AI 模型需要合适的上下文信息才能正确使用工具。但手动组装工具描述、参数格式、使用示例等上下文信息，既繁琐又容易出错。

协议不统一：不同工具使用不同的通信协议和数据格式，开发者需要学习多种技术栈，增加了学习和开发成本。

MCP 协议通过标准化工具描述、参数定义和调用方式，让 AI 模型能够"即插即用"各种外部工具。而 SpringAI 的 MCP-stdio 实现，正是将这一协议落地到 Java 生态的关键桥梁。

通过本文，你将学会：

• 理解 MCP 协议的核心机制和工作原理
• 在 SpringAI 中配置和使用 MCP-stdio 客户端
• 开发符合 MCP 标准的自定义工具服务器
• 解决实际项目中的集成难题和性能瓶颈

2. MCP 协议基础与核心原理

2.1 什么是 MCP 协议？

MCP（Model Context Protocol）是一种开放协议，用于在 AI 模型和外部工具之间建立标准化的通信桥梁。你可以把它想象成 AI 世界的"USB 协议"——只要设备符合 USB 标准，就能即插即用，无需安装特定驱动程序。

协议的核心组件包括：

• MCP Server：工具提供方，将具体功能封装成标准接口
• MCP Client：AI 模型或应用，通过标准协议调用工具
• Transport Layer：通信层，支持 stdio、HTTP、SSE 等多种方式

2.2 MCP 与传统 Skill 的区别

很多开发者容易混淆 MCP 和 Skill 的概念，其实它们解决的是不同层次的问题：

简单来说，Skill 是建立在 MCP 之上的具体应用，而 MCP 是支撑 Skill 运行的底层协议。

2.3 MCP-stdio 的工作机制

stdio（标准输入输出）是 MCP 中最简单的传输方式，特别适合本地工具集成。其工作流程如下：

AI 应用 → MCP Client → stdio 传输 → MCP Server → 具体工具

这种设计有三大优势：

1. 语言无关性：MCP Server 可以用任何语言编写，只要遵循协议规范
2. 进程隔离：工具崩溃不会影响主应用稳定性
3. 简单调试：可以直接在命令行测试工具功能

3. 环境准备与前置条件

在开始编码前，确保你的开发环境满足以下要求：

3.1 基础环境配置

操作系统：Windows 10+/macOS 10.14+/Linux Ubuntu 18.04+Java 版本：JDK 17 或更高版本（SpringAI 3.0+ 要求）构建工具：Maven 3.6+ 或 Gradle 7.4+

3.2 SpringAI 依赖配置

在pom.xml中添加 SpringAI 依赖：

<!-- SpringAI 核心依赖 --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-core</artifactId> <version>1.0.0-M5</version> </dependency> <!-- MCP 客户端支持 --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-mcp</artifactId> <version>1.0.0-M5</version> </dependency> <!-- 如果使用 OpenAI 模型 --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai</artifactId> <version>1.0.0-M5</version> </dependency>

3.3 配置文件设置

在application.yml中配置基础参数：

spring: ai: openai: api-key: ${OPENAI_API_KEY} base-url: https://api.openai.com/v1 mcp: enabled: true servers: dbtool: command: "java" args: ["-jar", "/path/to/your-mcp-server.jar"]

重要提醒：API 密钥等敏感信息应该使用环境变量或配置中心管理，不要硬编码在配置文件中。

4. 构建 MCP Server：数据库查询工具实战

下面我们通过一个真实的案例——数据库查询工具，来演示如何构建生产可用的 MCP Server。

4.1 MCP Server 项目结构

首先创建标准的 Maven 项目结构：

mcp-database-server/ ├── src/ │ └── main/ │ ├── java/ │ │ └── com/example/mcp/ │ │ ├── DatabaseMcpServer.java │ │ ├── tool/ │ │ │ ├── DatabaseQueryTool.java │ │ │ └── TableSchemaTool.java │ │ └── config/ │ │ └── DatabaseConfig.java │ └── resources/ │ └── application.properties ├── pom.xml └── Dockerfile

4.2 核心依赖配置

在pom.xml中添加 MCP 协议实现依赖：

<dependencies> <!-- MCP 协议 Java SDK --> <dependency> <groupId>com.anthropic</groupId> <artifactId>mcp-java-sdk</artifactId> <version>1.0.0</version> </dependency> <!-- 数据库连接池 --> <dependency> <groupId>com.zaxxer</groupId> <artifactId>HikariCP</artifactId> <version>5.0.1</version> </dependency> <!-- JSON 处理 --> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.15.2</version> </dependency> </dependencies>

4.3 MCP Server 主类实现

// 文件路径：src/main/java/com/example/mcp/DatabaseMcpServer.java package com.example.mcp; import com.anthropic.mcp.sdk.McpServer; import com.anthropic.mcp.sdk.McpTransport; import com.anthropic.mcp.sdk.stdio.StdioTransport; import com.example.mcp.tool.DatabaseQueryTool; import com.example.mcp.tool.TableSchemaTool; public class DatabaseMcpServer { public static void main(String[] args) { // 创建传输层 - 使用 stdio McpTransport transport = new StdioTransport.Builder().build(); // 创建 MCP Server 实例 McpServer server = new McpServer.Builder(transport) .name("database-tool-server") .version("1.0.0") .description("提供数据库查询和元数据访问功能的 MCP 服务器") .addTool(new DatabaseQueryTool()) .addTool(new TableSchemaTool()) .build(); // 启动服务器 try { server.start(); System.err.println("MCP Database Server 启动成功，等待连接..."); // 保持进程运行 Thread.currentThread().join(); } catch (Exception e) { System.err.println("服务器启动失败: " + e.getMessage()); System.exit(1); } } }

4.4 数据库查询工具实现

// 文件路径：src/main/java/com/example/mcp/tool/DatabaseQueryTool.java package com.example.mcp.tool; import com.anthropic.mcp.sdk.tools.McpTool; import com.anthropic.mcp.sdk.types.McpToolResult; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import javax.sql.DataSource; import java.sql.Connection; import java.sql.PreparedStatement; import java.sql.ResultSet; import java.sql.ResultSetMetaData; import java.util.ArrayList; import java.util.HashMap; import java.util.List; import java.util.Map; public class DatabaseQueryTool implements McpTool { private final DataSource dataSource; private final ObjectMapper mapper = new ObjectMapper(); public DatabaseQueryTool() { // 初始化数据源 - 生产环境应从配置读取 this.dataSource = DatabaseConfig.createDataSource(); } @Override public String getName() { return "query_database"; } @Override public String getDescription() { return "执行 SQL 查询并返回结果。支持参数化查询防止 SQL 注入。"; } @Override public Map<String, Object> getParameters() { return Map.of( "type", "object", "properties", Map.of( "sql", Map.of( "type", "string", "description", "要执行的 SQL 查询语句" ), "parameters", Map.of( "type", "array", "items", Map.of("type", "string"), "description", "查询参数列表", "default", new ArrayList<String>() ) ), "required", List.of("sql") ); } @Override public McpToolResult execute(JsonNode arguments) { try { String sql = arguments.get("sql").asText(); JsonNode paramsNode = arguments.get("parameters"); List<String> parameters = new ArrayList<>(); if (paramsNode != null && paramsNode.isArray()) { for (JsonNode param : paramsNode) { parameters.add(param.asText()); } } // 执行查询 return executeQuery(sql, parameters); } catch (Exception e) { return McpToolResult.error("查询执行失败: " + e.getMessage()); } } private McpToolResult executeQuery(String sql, List<String> parameters) { // 安全性检查：禁止数据修改操作 if (isModificationQuery(sql)) { return McpToolResult.error("此工具仅支持查询操作，禁止执行数据修改语句"); } try (Connection conn = dataSource.getConnection(); PreparedStatement stmt = conn.prepareStatement(sql)) { // 设置参数 for (int i = 0; i < parameters.size(); i++) { stmt.setString(i + 1, parameters.get(i)); } // 执行查询 ResultSet rs = stmt.executeQuery(); ResultSetMetaData metaData = rs.getMetaData(); int columnCount = metaData.getColumnCount(); // 构建结果 List<Map<String, Object>> results = new ArrayList<>(); while (rs.next()) { Map<String, Object> row = new HashMap<>(); for (int i = 1; i <= columnCount; i++) { String columnName = metaData.getColumnName(i); row.put(columnName, rs.getObject(i)); } results.add(row); } // 返回标准化结果 Map<String, Object> content = new HashMap<>(); content.put("rowCount", results.size()); content.put("columns", getColumnNames(metaData, columnCount)); content.put("data", results); return McpToolResult.success(mapper.valueToTree(content)); } catch (Exception e) { return McpToolResult.error("数据库查询错误: " + e.getMessage()); } } private boolean isModificationQuery(String sql) { String lowerSql = sql.trim().toLowerCase(); return lowerSql.startsWith("insert") || lowerSql.startsWith("update") || lowerSql.startsWith("delete") || lowerSql.startsWith("drop") || lowerSql.startsWith("alter") || lowerSql.startsWith("create"); } private List<String> getColumnNames(ResultSetMetaData metaData, int columnCount) throws Exception { List<String> columns = new ArrayList<>(); for (int i = 1; i <= columnCount; i++) { columns.add(metaData.getColumnName(i)); } return columns; } }

4.5 数据库配置类

// 文件路径：src/main/java/com/example/mcp/config/DatabaseConfig.java package com.example.mcp.config; import com.zaxxer.hikari.HikariConfig; import com.zaxxer.hikari.HikariDataSource; import javax.sql.DataSource; public class DatabaseConfig { public static DataSource createDataSource() { HikariConfig config = new HikariConfig(); // 生产环境应从环境变量读取配置 config.setJdbcUrl(System.getenv().getOrDefault( "DB_URL", "jdbc:mysql://localhost:3306/testdb")); config.setUsername(System.getenv().getOrDefault("DB_USER", "testuser")); config.setPassword(System.getenv().getOrDefault("DB_PASSWORD", "testpass")); config.setMaximumPoolSize(10); config.setMinimumIdle(2); config.setConnectionTimeout(30000); config.setIdleTimeout(600000); config.setMaxLifetime(1800000); // 安全设置：只读连接 config.setReadOnly(true); return new HikariDataSource(config); } }

5. SpringAI 中集成 MCP-stdio 客户端

构建好 MCP Server 后，接下来在 SpringAI 应用中集成客户端。

5.1 配置 MCP-stdio 客户端

// 文件路径：src/main/java/com/example/ai/config/McpConfig.java package com.example.ai.config; import org.springframework.ai.mcp.McpClient; import org.springframework.ai.mcp.McpProperties; import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import java.util.List; @Configuration @EnableConfigurationProperties(McpProperties.class) public class McpConfig { @Bean public McpClient databaseMcpClient(McpProperties properties) { McpProperties.ServerConfig serverConfig = new McpProperties.ServerConfig(); serverConfig.setCommand("java"); serverConfig.setArgs(List.of("-jar", "/apps/mcp-database-server.jar")); // 设置服务器健康检查 serverConfig.setHealthCheckEnabled(true); serverConfig.setHealthCheckTimeout("30s"); return new McpClient(serverConfig); } }

5.2 创建工具调用服务

// 文件路径：src/main/java/com/example/ai/service/DatabaseToolService.java package com.example.ai.service; import org.springframework.ai.mcp.McpClient; import org.springframework.ai.mcp.McpToolRequest; import org.springframework.ai.mcp.McpToolResponse; import org.springframework.stereotype.Service; import java.util.Map; @Service public class DatabaseToolService { private final McpClient mcpClient; public DatabaseToolService(McpClient mcpClient) { this.mcpClient = mcpClient; } public String queryDatabase(String naturalLanguageQuery) { // 构建工具调用请求 McpToolRequest request = McpToolRequest.builder() .toolName("query_database") .arguments(Map.of( "sql", buildSqlFromQuery(naturalLanguageQuery), "parameters", new String[]{} )) .build(); try { McpToolResponse response = mcpClient.callTool(request); if (response.isSuccess()) { return formatQueryResults(response.getContent()); } else { return "查询失败: " + response.getError(); } } catch (Exception e) { return "工具调用异常: " + e.getMessage(); } } private String buildSqlFromQuery(String naturalLanguageQuery) { // 这里可以集成 NLP 处理，将自然语言转换为 SQL // 简化示例：直接返回预设查询 if (naturalLanguageQuery.toLowerCase().contains("用户数量")) { return "SELECT COUNT(*) as user_count FROM users WHERE status = 'active'"; } else if (naturalLanguageQuery.toLowerCase().contains("最新订单")) { return "SELECT * FROM orders ORDER BY created_at DESC LIMIT 10"; } return "SELECT * FROM information_schema.tables LIMIT 5"; } private String formatQueryResults(Object content) { // 简化结果格式化 return "查询成功: " + content.toString(); } }

5.3 在 AI 对话中集成工具调用

// 文件路径：src/main/java/com/example/ai/service/AiChatService.java package com.example.ai.service; import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.chat.model.ChatResponse; import org.springframework.stereotype.Service; import java.util.Map; @Service public class AiChatService { private final ChatClient chatClient; private final DatabaseToolService databaseToolService; public AiChatService(ChatClient chatClient, DatabaseToolService databaseToolService) { this.chatClient = chatClient; this.databaseToolService = databaseToolService; } public String chatWithDatabaseAccess(String userMessage) { // 判断是否需要数据库查询 if (needDatabaseQuery(userMessage)) { String queryResult = databaseToolService.queryDatabase(userMessage); // 将查询结果作为上下文提供给 AI return chatClient.prompt() .user(userMessage) .system("数据库查询结果: " + queryResult) .call() .content(); } // 普通对话 return chatClient.prompt() .user(userMessage) .call() .content(); } private boolean needDatabaseQuery(String message) { String lowerMessage = message.toLowerCase(); return lowerMessage.contains("查询") || lowerMessage.contains("数据") || lowerMessage.contains("统计") || lowerMessage.contains("有多少"); } }

6. 完整示例：用户查询场景实战

下面通过一个完整的业务流程，展示 MCP-stdio 在实际项目中的应用。

6.1 创建 REST 控制器

// 文件路径：src/main/java/com/example/ai/controller/AiAssistantController.java package com.example.ai.controller; import com.example.ai.service.AiChatService; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api/ai") public class AiAssistantController { private final AiChatService aiChatService; public AiAssistantController(AiChatService aiChatService) { this.aiChatService = aiChatService; } @PostMapping("/chat") public ChatResponse chat(@RequestBody ChatRequest request) { String response = aiChatService.chatWithDatabaseAccess(request.getMessage()); return new ChatResponse(response); } // 请求响应DTO public static class ChatRequest { private String message; public String getMessage() { return message; } public void setMessage(String message) { this.message = message; } } public static class ChatResponse { private String response; public ChatResponse(String response) { this.response = response; } public String getResponse() { return response; } } }

6.2 应用配置文件

# application.yml spring: application: name: ai-assistant ai: openai: api-key: ${OPENAI_API_KEY} chat: model: gpt-4o mcp: servers: database: command: "java" args: ["-jar", "/apps/mcp-database-server.jar"] working-dir: "/apps" timeout: "60s" server: port: 8080 logging: level: org.springframework.ai: DEBUG com.example: INFO

6.3 测试用例

// 文件路径：src/test/java/com/example/ai/AiAssistantApplicationTests.java package com.example.ai; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; import com.example.ai.service.AiChatService; import static org.assertj.core.api.Assertions.assertThat; @SpringBootTest class AiAssistantApplicationTests { @Autowired private AiChatService aiChatService; @Test void testDatabaseQueryIntegration() { String response = aiChatService.chatWithDatabaseAccess("查询当前活跃用户数量"); assertThat(response).isNotNull(); assertThat(response).contains("用户数量"); // 或具体的数字 System.out.println("AI 响应: " + response); } @Test void testNormalChat() { String response = aiChatService.chatWithDatabaseAccess("你好，请介绍你自己"); assertThat(response).isNotNull(); assertThat(response.length()).isGreaterThan(10); } }

7. 运行结果与效果验证

7.1 启动流程验证

1. 启动 MCP Server：

# 打包 MCP Server mvn clean package -DskipTests # 启动服务器 java -jar target/mcp-database-server.jar

预期输出：

MCP Database Server 启动成功，等待连接...

2. 启动 SpringAI 应用：

# 设置环境变量 export OPENAI_API_KEY=your_api_key export DB_URL=jdbc:mysql://localhost:3306/testdb export DB_USER=testuser export DB_PASSWORD=testpass # 启动应用 mvn spring-boot:run

7.2 功能测试验证

使用 curl 测试接口：

# 测试数据库查询功能 curl -X POST http://localhost:8080/api/ai/chat \ -H "Content-Type: application/json" \ -d '{"message": "查询最近一周的订单数量"}' # 预期响应示例 { "response": "根据数据库查询结果，最近一周共有 1,247 个新订单。其中..." }

7.3 监控指标验证

在应用运行后，检查以下关键指标：

• MCP Server 进程是否稳定运行
• 数据库连接池使用情况
• API 响应时间（应 < 5秒）
• 错误率（应 < 1%）

8. 常见问题与排查思路

在实际部署中，你可能会遇到以下典型问题：

8.1 连接类问题

8.2 性能类问题

8.3 安全类问题

9. 最佳实践与工程建议

基于实际项目经验，总结以下最佳实践：

9.1 安全性设计原则

最小权限原则：MCP Server 应该以最低必要权限运行，数据库账户设置为只读。

输入验证：对所有输入参数进行严格验证，防止注入攻击。

// 安全的参数处理示例 public McpToolResult execute(JsonNode arguments) { try { // 验证必需参数 if (!arguments.has("sql")) { return McpToolResult.error("缺少必需参数: sql"); } String sql = arguments.get("sql").asText(); if (sql.trim().isEmpty()) { return McpToolResult.error("SQL 语句不能为空"); } // 继续处理... } catch (Exception e) { return McpToolResult.error("参数处理错误: " + e.getMessage()); } }

9.2 性能优化策略

连接池配置：合理设置数据库连接池参数，避免连接泄露。

查询优化：对常用查询添加缓存，减少数据库压力。

异步处理：对于耗时操作，考虑使用异步非阻塞模式。

9.3 可观测性设计

添加详细的日志记录和监控指标：

@Component public class McpToolMetrics { private final MeterRegistry meterRegistry; private final Counter toolCallCounter; private final Timer toolExecutionTimer; public McpToolMetrics(MeterRegistry meterRegistry) { this.meterRegistry = meterRegistry; this.toolCallCounter = Counter.builder("mcp.tool.calls") .description("MCP 工具调用次数") .register(meterRegistry); this.toolExecutionTimer = Timer.builder("mcp.tool.execution.time") .description("MCP 工具执行时间") .register(meterRegistry); } public void recordToolCall(String toolName, long duration, boolean success) { toolCallCounter.increment(); toolExecutionTimer.record(duration, TimeUnit.MILLISECONDS); Tags tags = Tags.of("tool", toolName, "success", String.valueOf(success)); meterRegistry.counter("mcp.tool.calls.detail", tags).increment(); } }

9.4 错误处理与容错

实现完善的错误处理机制：

@Slf4j public class ResilientMcpClient { private final McpClient delegate; private final RetryTemplate retryTemplate; public ResilientMcpClient(McpClient delegate) { this.delegate = delegate; this.retryTemplate = RetryTemplate.builder() .maxAttempts(3) .fixedBackoff(1000) .retryOn(McpConnectionException.class) .build(); } public McpToolResponse callToolWithRetry(McpToolRequest request) { return retryTemplate.execute(context -> { try { return delegate.callTool(request); } catch (McpConnectionException e) { log.warn("MCP 连接异常，重试次数: {}", context.getRetryCount()); throw e; } }); } }

通过本文的完整实现方案，你不仅能够掌握 MCP-stdio 在 SpringAI 中的技术细节，更重要的是理解了如何构建生产可用的 AI 工具集成系统。这种架构设计思路可以扩展到其他类型的工具集成，为构建更强大的 AI 应用奠定坚实基础。

建议在实际项目中先从简单的工具开始实践，逐步完善监控、安全、性能等生产级特性。随着 MCP 生态的成熟，这种标准化集成方式将成为 AI 应用开发的标配。