上下文协议（MCP）Java SDK 指南

当我们把各种内部系统、数据源、工具接入大语言模型时，往往会遇到一个尴尬的问题：每个团队、每套系统都有自己的一套“接入规范”。有的用 HTTP API，有的用消息队列，有的直接连数据库，最后一圈串下来，既难以统一治理，又很难在不同应用之间复用。这时，你可能会问：有没有一种通用的协议，既能让 AI 模型方便地调用外部工具、访问数据，又能让后端服务方用标准方式暴露能力？

Model Context Protocol（MCP）就是为此而生的标准之一，而本文要介绍的 Java SDK，则为 Java 开发者提供了一条直接接入 MCP 生态的通路。通过它，你可以用统一的模型，在 Java 应用里暴露工具、资源、提示模版，也可以轻松作为客户端去调用这些能力。本文将从整体架构讲起，一步步带你用一个可运行的示例，搭建起自己的 MCP 服务端与客户端。

1. 概览

随着近年来 AI 的快速发展，越来越多的工具和系统开始与 AI 模型集成。但随之而来的一个挑战是：每种集成都可能采用完全不同的标准和方式，将外部工具、资源和系统接入到 AI 模型中。

Model Context Protocol（MCP）是一个开源标准，它定义了 AI 应用（如大语言模型、图像生成模型等）与工具、数据源以及其他资源之间的集成方式。借助 MCP，AI 应用可以按外部系统约定的方式访问数据、调用工具并执行工作流。

MCP 的 Java SDK 为开发者提供了一组库，支持多种协议和通信机制，用于把 Java 应用与 AI 应用连接起来。

在本教程中，我们将一起了解这个 SDK，并通过一个简单示例来体验 MCP 的使用方式。

2. 架构

MCP 架构的核心组件主要包括：

• MCP Host：负责管理多个 MCP Client
• MCP Client：从 MCP Server 获取上下文，供 MCP Host 使用
• MCP Server：向 MCP Client 提供上下文信息和可调用能力

MCP 将通信划分为两个概念层次：数据层（Data Layer），用于定义客户端与服务端的通信协议和生命周期管理；以及传输层（Transport Layer），用于定义客户端和服务端之间的具体传输通道和机制。

Java 版的 MCP SDK 将这些概念映射为如下几个层次：

• Client/Server 层：通过McpClient/McpServer实现并管理客户端/服务端的具体操作
• Session 层：通过McpSession管理通信模式和会话状态
• Transport 层：通过McpTransport处理消息的序列化与反序列化

客户端会调用 MCP 服务端暴露的一到多个工具（tool），而底层的通信则由传输层负责。

在 MCP 中，Primitive（原语）是最基础的构建单元，用来定义可用的上下文信息类型以及可执行的操作范围。服务端和客户端都提供了一些原语。

服务端侧的原语包括工具（tools）、资源（resources）和提示模版（prompts）。工具是 AI 应用可以调用的可执行函数，例如查询数据库、文件操作等。资源是提供给客户端的上下文数据源，例如数据库结构、文件内容等。提示模版是可复用的模版，用于与语言模型进行交互。

客户端侧的原语则帮助McpServer的实现者构建更丰富的交互能力，包括采样（sampling）、信息补充（elicitation）和日志（logging）。采样允许服务端在不集成模型 SDK 的情况下，向客户端请求语言模型补全结果。信息补充让服务端能够向用户请求额外信息或确认操作。日志则允许服务端向客户端发送日志消息，用于调试和监控。

3. 环境准备

要使用 MCP Java SDK，我们需要在项目中加入mcp依赖：

<dependency><groupId>io.modelcontextprotocol.sdk</groupId><artifactId>mcp</artifactId><version>0.15.0</version></dependency>

3.1 定义一个 MCP 工具

我们先通过LoggingTool这个类，定义一个非常简单的 MCP 工具，用来打印收到的提示词（prompt），该方法返回一个SyncToolSpecification：

publicclassLoggingTool{publicstaticMcpServerFeatures.SyncToolSpecificationlogPromptTool(){McpSchema.JsonSchemainputSchema=newMcpSchema.JsonSchema("object",Map.of("prompt",String.class),List.of("prompt"),false,null,null);returnnewMcpServerFeatures.SyncToolSpecification(newMcpSchema.Tool("logPrompt","Log Prompt","Logs a provided prompt",inputSchema,null,null,null),(exchange,args)->{Stringprompt=(String)args.get