LangChain4j MCP 模型上下文协议

学习时间：2026/4/5
技术栈：Spring Boot 4.0.5 + LangChain4j 1.12.2 + 通义千问模型

一、什么是 MCP？

MCP（Model Context Protocol，模型上下文协议）是一种标准化的协议，用于让 AI 模型能够访问外部数据源和工具。

解决的问题：

• 传统 Function Call 需要为每个外部能力编写 Java 代码
• MCP 提供了统一的协议来连接 AI 和外部工具
• 开发者可以复用社区现有的 MCP Server

MCP vs Function Call

特性	Function Call	MCP
实现方式	手动编写 Java 方法	使用标准化协议
工具来源	自己开发	社区生态（现成可用）
维护成本	高（需要自己维护代码）	低（使用标准服务器）
灵活性	高（完全自定义）	中（依赖现有服务器）

二、MCP 架构

LLM ←→ LangChain4j ←→ MCP Client ←→ MCP Transport ←→ MCP Server ←→ 外部资源

核心组件：

组件	作用
MCP Server	提供工具和资源的服务器
MCP Transport	传输层，支持 Stdio、SSE 等
MCP Client	客户端，连接到 MCP Server
McpToolProvider	将 MCP 工具提供给 LangChain4j

三、实战示例：集成百度地图

3.1 添加 MCP 依赖

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-mcp</artifactId>
    <version>${langchain4j.version}</version>
</dependency>

3.2 创建 MCP 客户端

public class TestMCP {

    public interface Assistant {
        String chat(String message);
    }

    @Test
    public void testMCP() {
        // 1. 创建聊天模型
        ChatModel qwenModel = QwenChatModel.builder()
                .apiKey(System.getenv("ALI_AI"))
                .modelName("qwen-max")
                .build();

        // 2. 创建 MCP 传输实例
        McpTransport transport = new StdioMcpTransport.Builder()
                .command(List.of(
                        "/usr/local/bin/npm",  // npm 路径
                        "exec",
                        "@baidumap/mcp-server-baidu-map"))
                .environment(Map.of("BAIDU_MAP_API_KEY", "your_api_key"))
                .logEvents(true)  // 启用调试日志
                .build();

        // 3. 创建 MCP 客户端
        DefaultMcpClient mcpClient = DefaultMcpClient.builder()
                .transport(transport)
                .build();

        // 4. 创建工具提供者
        McpToolProvider toolProvider = McpToolProvider.builder()
                .mcpClients(mcpClient)
                .build();

        // 5. 构建 AI 助手（集成 MCP 工具）
        Assistant assistant = AiServices.builder(Assistant.class)
                .chatModel(qwenModel)
                .toolProvider(toolProvider)
                .build();

        try {
            String response = assistant.chat("长沙的天气如何");
            System.out.println(response);
        } finally {
            mcpClient.close();  // 重要：关闭客户端释放资源
        }
    }
}

四、工作流程

用户提问："长沙的天气如何"
    ↓
1. AI 识别需要调用天气工具
    ↓
2. 通过 MCP Client 调用百度地图 MCP Server
    ↓
3. MCP Server 执行实际 API 调用
    ↓
4. 返回天气数据给 AI
    ↓
5. AI 组织语言回复用户
    ↓
AI 回复："长沙今天天气晴朗，气温 20-28°C..."

五、MCP 生态资源

5.1 MCP 市场

• MCP.so - 中文 MCP 生态系统
• Model Context Protocol GitHub - 官方服务器仓库

5.2 常见 MCP Server 类型

类型	功能
📁 文件系统	读取、写入、搜索文件
🗄️ 数据库	PostgreSQL、MySQL、SQLite 等
🔧 开发工具	Git、终端命令、代码编辑器
🌐 Web 服务	地图 API、天气查询、社交媒体
📊 数据源	CSV、Excel、API 接口

六、安全注意事项

6.1 限制访问范围

// ❌ 危险：允许访问整个文件系统
.command(List.of("npx", "@modelcontextprotocol/server-filesystem", "/"))

// ✅ 安全：只允许访问特定目录
.command(List.of("npx", "@modelcontextprotocol/server-filesystem", "/app/data"))

6.2 环境变量管理

// ✅ 从环境变量读取 API Key
.environment(Map.of("BAIDU_MAP_API_KEY", System.getenv("BAIDU_MAP_API_KEY")))

// ❌ 不要硬编码密钥
.environment(Map.of("BAIDU_MAP_API_KEY", "sk-xxx..."))

6.3 资源清理

try {
    // 使用 MCP 客户端
} finally {
    mcpClient.close();  // 确保关闭连接
}

七、最佳实践

7.1 复用 MCP Client

// ✅ 在 Spring Bean 中单例管理
@Bean
public McpToolProvider mcpToolProvider() {
    DefaultMcpClient client = createMcpClient();
    return McpToolProvider.builder()
            .mcpClients(client)
            .build();
}

// ❌ 每次请求都创建新的 Client

7.2 生产环境配置

// 生产环境
StdioMcpTransport transport = new StdioMcpTransport.Builder()
        .command(...)
        .logEvents(false)  // 关闭调试日志
        .build();

7.3 错误处理

try {
    String response = assistant.chat("查询天气");
    System.out.println(response);
} catch (Exception e) {
    // MCP Server 可能不可用或 API Key 无效
    System.err.println("MCP 调用失败: " + e.getMessage());
    // 降级方案：使用备用数据源
}

八、与 Function Call 组合使用

MCP 和 Function Call 可以同时使用：

Assistant assistant = AiServices.builder(Assistant.class)
    .chatModel(model)
    .tools(toolsService)           // Function Call
    .toolProvider(mcpToolProvider) // MCP
    .build();

九、应用场景

场景	MCP Server	优势
智能客服	数据库 + 知识库	实时查询订单、用户信息
代码助手	Git + 文件系统	读取代码库、提交记录
数据分析	PostgreSQL + CSV	直接查询数据库生成报告
办公自动化	文件系统 + API	自动处理文档、发送邮件
DevOps	Git + 终端	自动化部署、监控

十、总结

MCP 提供了标准化的外部工具集成方式：

• ✅ 标准化协议：统一的接口规范
• ✅ 生态丰富：大量现成的 MCP Server 可用
• ✅ 快速集成：几分钟内即可接入外部能力
• ✅ 安全可控：可限制访问范围和权限

---

相关笔记：

1. LangChain4j 入门指南
2. LangChain4j 声明式 AI 服务开发
3. LangChain4j 对话记忆与多用户隔离
4. LangChain4j Function Call 工具调用
5. LangChain4j RAG 检索增强生成