Java MCP 服务端

SDK 内容

服务器功能

MCP 服务端是模型上下文协议 (MCP) 架构中的核心组件，为客户端提供工具、资源和能力。它实现了协议的服务端部分，负责：

暴露客户端可以发现并执行的工具。支持输入和输出模式，并返回结构化和非结构化的内容类型。
通过基于 URI 的访问模式管理资源
提供提示词模板并处理提示词请求
支持与客户端的能力协商
实现服务端协议操作
管理并发客户端连接
提供结构化日志、进度跟踪和通知
提供 STDIO、Streamable-HTTP 和 SSE 服务端传输实现，无需外部 Web 框架。
可选的 Spring 特定传输依赖：io.modelcontextprotocol.sdk:mcp-spring-webflux，io.modelcontextprotocol.sdk:mcp-spring-webmvc，供 Spring AI 用户使用。

这个基于 Spring AI MCP 的快速入门演示将向您展示如何构建 MCP 服务端。

服务端同时支持同步和异步 API，允许在不同的应用上下文中灵活集成。

同步 (Sync) API
异步 (Async) API

// Create a server with custom configuration
McpSyncServer syncServer = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .capabilities(ServerCapabilities.builder()
        .resources(false, true)  // Enable resource support
        .tools(true)             // Enable tool support
        .prompts(true)           // Enable prompt support
        .logging()               // Enable logging support
        .completions()           // Enable completions support
        .build())
    .build();

// Register tools, resources, and prompts
syncServer.addTool(syncToolSpecification);
syncServer.addResource(syncResourceSpecification);
syncServer.addPrompt(syncPromptSpecification);

// Close the server when done
syncServer.close();

在处理器中保留线程本地变量 (Thread-locals)

McpSyncServer 将执行委托给底层的 McpAsyncServer。工具、资源等处理器的执行可能不会在调用方法的线程上发生。在这种情况下，线程本地变量会丢失，这可能会破坏依赖线程绑定工作的框架中的某些功能。为确保在调用线程上执行并保持线程本地变量可用，请设置 McpServer.sync(...).immediateExecution(true)。

这仅适用于同步服务端。异步服务端使用响应式堆栈，不应依赖线程本地变量。

// Create an async server with custom configuration
McpAsyncServer asyncServer = McpServer.async(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .capabilities(ServerCapabilities.builder()
        .resources(false, true)     // Enable resource support
        .tools(true)                // Enable tool support
        .prompts(true)              // Enable prompt support
        .logging()                  // Enable logging support
        .completions()              // Enable completions support
        .build())
    .build();

// Register tools, resources, and prompts
asyncServer.addTool(asyncToolSpecification)
    .doOnSuccess(v -> logger.info("Tool registered"))
    .subscribe();

asyncServer.addResource(asyncResourceSpecification)
    .doOnSuccess(v -> logger.info("Resource registered"))
    .subscribe();

asyncServer.addPrompt(asyncPromptSpecification)
    .doOnSuccess(v -> logger.info("Prompt registered"))
    .subscribe();

// Close the server when done
asyncServer.close()
    .doOnSuccess(v -> logger.info("Server closed"))
    .subscribe();

服务端传输层提供者

MCP SDK 中的传输层负责处理客户端和服务端之间的通信。它提供不同的实现来支持各种通信协议和模式。SDK 包含几个内置的传输提供者实现：

STDIO
WebFlux
WebMVC
Servlet

创建进程内 (In-process) 传输

StdioServerTransportProvider transportProvider = new StdioServerTransportProvider(new ObjectMapper());

通过标准输入/输出流提供双向 JSON-RPC 消息处理，具有非阻塞消息处理、序列化/反序列化和优雅停机支持。关键特性：

通过 stdin/stdout 进行双向通信
支持基于进程的集成
简单的安装和配置
轻量级实现

基于 WebFlux 的 SSE 和 Streamable-HTTP 服务端传输。需要 mcp-spring-webflux 依赖。

Streamable-HTTP (WebFlux)
无状态 Streamable-HTTP (WebFlux)
SSE (WebFlux)

@Configuration
class McpConfig {
    @Bean
    WebFluxStreamableServerTransportProvider webFluxStreamableServerTransportProvider(ObjectMapper mapper) {
      	return this.mcpStreamableServerTransportProvider = WebFluxStreamableServerTransportProvider.builder()
                .objectMapper(mapper)
                .messageEndpoint("/mcp")
                .build();
    }

    @Bean
    RouterFunction<?> mcpRouterFunction(WebFluxStreamableServerTransportProvider transportProvider) {
        return transportProvider.getRouterFunction();
    }
}

实现 Streamable HTTP 传输规范，提供：

通过 Streamable-HTTP 进行双向通信
使用 WebFlux 的响应式 HTTP 流
通过 Streamable-HTTP 端点实现并发客户端连接
消息路由和会话管理
优雅停机能力

由于缺乏会话存储，当前实现不支持可恢复性

在具有多个 MCP 服务端实例的分布式环境中，需要正确的消息路由。为了在不增加显著基础设施开销的情况下实现可扩展性，请考虑使用 Stateless Streamable-HTTP 服务端传输实现。

无状态 MCP 服务端专为不需在请求之间维护会话状态的简化部署而设计。它们实现了 Streamable-HTTP 规范的一个子集，返回 application/json 响应。之所以称其为无状态，是因为与标准的 Streamable-HTTP 传输不同，它们不在请求之间维护会话状态。这些服务端是微服务架构和云原生部署的理想选择。

@Configuration
class McpConfig {
    @Bean
    WebFluxStatelessServerTransport webFluxStatelessServerTransport(ObjectMapper mapper) {
      	return this.mcpStatelessServerTransport = WebFluxStatelessServerTransport.builder()
                .objectMapper(mapper)
                .messageEndpoint("/mcp")
                .build();
    }

    @Bean
    RouterFunction<?> mcpRouterFunction(WebFluxStatelessServerTransport transportProvider) {
        return transportProvider.getRouterFunction();
    }

    @Bean
    public McpStatelessSyncServer prepareSyncServerBuilder(WebFluxStatelessServerTransport statelessServerTransport) {
      return McpServer.sync(statelessServerTransport)
              //...
              .build();
    }

}

实现 MCP 无状态 Streamable-HTTP 传输规范，提供：

通过 Streamable-HTTP 进行单向（客户端到服务端）通信
使用 WebFlux 的响应式 HTTP 流
通过无状态端点实现并发客户端连接
消息路由和会话管理
优雅停机能力

当前实现不支持向客户端发送通知 (Notifications)。

@Configuration
class McpConfig {
    @Bean
    WebFluxSseServerTransportProvider webFluxSseServerTransportProvider(ObjectMapper mapper) {
        return new WebFluxSseServerTransportProvider(mapper, "/mcp/message");
    }

    @Bean
    RouterFunction<?> mcpRouterFunction(WebFluxSseServerTransportProvider transportProvider) {
        return transportProvider.getRouterFunction();
    }
}

实现 MCP SSE 传输规范，提供：

使用 WebFlux 的响应式 HTTP 流
通过 SSE 端点实现并发客户端连接
消息路由和会话管理
优雅停机能力

创建基于 WebMvc 的 SSE 服务端传输。需要 mcp-spring-webmvc 依赖。

Streamable-HTTP (WebMvc)
无状态 Streamable-HTTP (WebMvc)
SSE (WebMvc)

@Configuration
@EnableWebMvc
class McpConfig {
    @Bean
    WebMvcStreamableServerTransportProvider webMvcStreamableHttpServerTransportProvider(ObjectMapper mapper) {
        return new WebMvcStreamableServerTransportProvider(mapper, "/mcp/message");
    }

    @Bean
    RouterFunction<ServerResponse> mcpRouterFunction(WebMvcStreamableServerTransportProvider transportProvider) {
        return transportProvider.getRouterFunction();
    }
}

实现 Streamable HTTP 传输规范，提供：

通过 Streamable-HTTP 进行双向通信
使用 WebFlux 的响应式 HTTP 流
通过 Streamable-HTTP 端点实现并发客户端连接
消息路由和会话管理
优雅停机能力

由于缺乏会话存储，当前实现不支持可恢复性

@Configuration
@EnableWebMvc
static class McpConfig {

  @Bean
  public WebMvcStatelessServerTransport webMvcStatelessServerTransport() {

    return WebMvcStatelessServerTransport.builder()
      .objectMapper(new ObjectMapper())
      .messageEndpoint(MESSAGE_ENDPOINT)
      .build();

  }

  @Bean
  public RouterFunction<ServerResponse> routerFunction(WebMvcStatelessServerTransport statelessServerTransport) {
    return statelessServerTransport.getRouterFunction();
  }

  @Bean
  public McpStatelessSyncServer prepareSyncServerBuilder(WebMvcStatelessServerTransport statelessServerTransport) {
    return McpServer.sync(statelessServerTransport)
            //...
            .build();
  }
}

实现 MCP Streamable-HTTP 和无状态传输规范，提供：

通过 Streamable-HTTP 进行单向（客户端到服务端）通信
使用 WebFlux 的响应式 HTTP 流
通过无状态端点实现并发客户端连接
消息路由和会话管理
优雅停机能力

当前实现不支持向客户端发送通知 (Notifications)。

@Configuration
@EnableWebMvc
class McpConfig {
    @Bean
    WebMvcSseServerTransportProvider webMvcSseServerTransportProvider(ObjectMapper mapper) {
        return new WebMvcSseServerTransportProvider(mapper, "/mcp/message");
    }

    @Bean
    RouterFunction<ServerResponse> mcpRouterFunction(WebMvcSseServerTransportProvider transportProvider) {
        return transportProvider.getRouterFunction();
    }
}

实现 MCP SSE 传输规范，提供：

服务端事件流 (SSE)
与 Spring WebMVC 集成
支持传统的 Web 应用程序
同步操作处理

创建基于 Servlet 的 SSE、Streamable-HTTP 和 Stateless 服务端传输。它可以与任何 Servlet 容器配合使用。

Streamable-HTTP (Servlet)
无状态 Streamable-HTTP (Servlet)
SSE (Servlet)

@Configuration
@EnableWebMvc
public class McpServerConfig implements WebMvcConfigurer {

    @Bean
    public HttpServletStreamableServerTransportProvider servletStreamableMcpSessionTransport() {
        return HttpServletStreamableServerTransportProvider.builder()
          .objectMapper(new ObjectMapper())
          .contextExtractor(TEST_CONTEXT_EXTRACTOR)
          .mcpEndpoint(MESSAGE_ENDPOINT)
          .keepAliveInterval(Duration.ofSeconds(1))
          .build();
    }

    //(Optionally) To use it with a Spring Web application, you can register it as a Servlet bean
    @Bean
    public ServletRegistrationBean customServletBean(HttpServletStreamableServerTransportProvider transportProvider) {
        return new ServletRegistrationBean(transportProvider);
    }
}

使用传统的 Servlet API 实现 Streamable HTTP 传输规范，提供：

通过 Streamable-HTTP 进行双向通信
使用 Servlet 6.0 异步支持的异步消息处理
多客户端连接的会话管理
单个端点
- 用于客户端到服务端请求的消息端点（可配置）
错误处理和响应格式化
优雅停机支持

由于缺乏会话存储，当前实现不支持可恢复性

@Configuration
@EnableWebMvc
public class McpServerConfig implements WebMvcConfigurer {

    @Bean
    public HttpServletStatelessServerTransport servletStatelessMcpSessionTransport() {
        return HttpServletStatelessServerTransport.builder()
          .objectMapper(new ObjectMapper())
          .mcpEndpoint(MESSAGE_ENDPOINT)
          .keepAliveInterval(Duration.ofSeconds(1))
          .build();
    }


    //(Optionally) To use it with a Spring Web application, you can register it as a Servlet bean
    @Bean
    public ServletRegistrationBean customServletBean(HttpServletStatelessServerTransport transportProvider) {
        return new ServletRegistrationBean(transportProvider);
    }

    @Bean
    public McpStatelessSyncServer prepareSyncServerBuilder(HttpServletStatelessServerTransport statelessServerTransport) {
        return McpServer.sync(statelessServerTransport)
                .build();
    }
  }
}

使用传统的 Servlet API 实现 Streamable-HTTP 无状态传输规范，提供：

通过 Streamable-HTTP 进行单向（客户端到服务端）通信
使用 Servlet 6.0 异步支持的异步消息处理
多客户端连接的会话管理
单个端点
- 用于客户端到服务端请求的消息端点（可配置）
错误处理和响应格式化
优雅停机支持

当前实现不支持向客户端发送通知 (Notifications)。

@Configuration
@EnableWebMvc
public class McpServerConfig implements WebMvcConfigurer {

    @Bean
    public HttpServletSseServerTransportProvider servletSseServerTransportProvider() {
        return HttpServletSseServerTransportProvider.builder()
            .objectMapper(new ObjectMapper())
            .messageEndpoint("/mcp/message")
            .keepAliveInterval(Duration.ofSeconds(1))
            .build();
    }

    //(Optionally) To use it with a Spring Web application, you can register it as a Servlet bean
    @Bean
    public ServletRegistrationBean customServletBean(HttpServletSseServerTransportProvider transportProvider) {
        return new ServletRegistrationBean(transportProvider);
    }
}

使用传统的 Servlet API 实现 MCP SSE 传输规范，提供：

使用 Servlet 6.0 异步支持的异步消息处理
多客户端连接的会话管理
两种类型的端点
- 用于服务端到客户端事件的 SSE 端点 (/sse)
- 用于客户端到服务端请求的消息端点（可配置）
错误处理和响应格式化
优雅停机支持

服务端能力

服务端可以配置各种能力

var capabilities = ServerCapabilities.builder()
    .resources(false, true)  // Resource support with list changes notifications
    .tools(true)            // Tool support with list changes notifications
    .prompts(true)          // Prompt support with list changes notifications
    .logging()              // Enable logging support (enabled by default with logging level INFO)
    .build();

工具 (Tool) 规范

模型上下文协议允许服务端暴露工具，这些工具可以被语言模型调用。Java SDK 允许实现带有处理器函数的工具规范。工具使 AI 模型能够进行计算、访问外部 API、查询数据库和操作文件。

同步 (Sync)
异步 (Async)

// Sync tool specification
var schema = """
            {
              "type" : "object",
              "id" : "urn:jsonschema:Operation",
              "properties" : {
                "operation" : {
                  "type" : "string"
                },
                "a" : {
                  "type" : "number"
                },
                "b" : {
                  "type" : "number"
                }
              }
            }
            """;
var syncToolSpecification = new McpServerFeatures.SyncToolSpecification(
    new Tool("calculator", "Basic calculator", schema),
    (exchange, arguments) -> {
        // Tool implementation
        return new CallToolResult(result, false);
    }
);

// Async tool specification
var schema = """
            {
              "type" : "object",
              "id" : "urn:jsonschema:Operation",
              "properties" : {
                "operation" : {
                  "type" : "string"
                },
                "a" : {
                  "type" : "number"
                },
                "b" : {
                  "type" : "number"
                }
              }
            }
            """;
var asyncToolSpecification = new McpServerFeatures.AsyncToolSpecification(
    new Tool("calculator", "Basic calculator", schema),
    (exchange, arguments) -> {
        // Tool implementation
        return Mono.just(new CallToolResult(result, false));
    }
);

工具规范包括一个具有 name（名称）、description（描述）和 parameter schema（参数模式）的工具定义，以及一个实现工具逻辑的调用处理器。函数的第一个参数是用于客户端交互的 McpAsyncServerExchange，第二个参数是工具参数的映射。

资源 (Resource) 规范

带有处理器函数的资源规范。资源通过暴露如下数据为 AI 模型提供上下文：文件内容、数据库记录、API 响应、系统信息、应用程序状态。资源规范示例：

同步 (Sync)
异步 (Async)

// Sync resource specification
var syncResourceSpecification = new McpServerFeatures.SyncResourceSpecification(
    new Resource("custom://resource", "name", "description", "mime-type", null),
    (exchange, request) -> {
        // Resource read implementation
        return new ReadResourceResult(contents);
    }
);

// Async resource specification
var asyncResourceSpecification = new McpServerFeatures.AsyncResourceSpecification(
    new Resource("custom://resource", "name", "description", "mime-type", null),
    (exchange, request) -> {
        // Resource read implementation
        return Mono.just(new ReadResourceResult(contents));
    }
);

资源规范由资源定义和资源读取处理器组成。资源定义包括 name、description 和 MIME type。处理资源读取请求的函数第一个参数是 McpAsyncServerExchange，服务端可以通过它与连接的客户端交互。第二个参数是 McpSchema.ReadResourceRequest。

提示词 (Prompt) 规范

作为提示词能力的一部分，MCP 为服务端向客户端暴露提示词模板提供了一种标准化方式。提示词规范是 AI 模型交互的结构化模板，支持一致的消息格式化、参数替换、上下文注入、响应格式化和指令模板化。

同步 (Sync)
异步 (Async)

// Sync prompt specification
var syncPromptSpecification = new McpServerFeatures.SyncPromptSpecification(
    new Prompt("greeting", "description", List.of(
        new PromptArgument("name", "description", true)
    )),
    (exchange, request) -> {
        // Prompt implementation
        return new GetPromptResult(description, messages);
    }
);

// Async prompt specification
var asyncPromptSpecification = new McpServerFeatures.AsyncPromptSpecification(
    new Prompt("greeting", "description", List.of(
        new PromptArgument("name", "description", true)
    )),
    (exchange, request) -> {
        // Prompt implementation
        return Mono.just(new GetPromptResult(description, messages));
    }
);

提示词定义包括名称（提示词的标识符）、描述（提示词的用途）和参数列表（模板化所需的参数）。处理器函数处理请求并返回格式化后的模板。第一个参数是用于客户端交互的 McpAsyncServerExchange，第二个参数是 GetPromptRequest 实例。

补全 (Completion) 规范

作为补全能力的一部分，MCP 为服务端提供了一种标准化方式，为提示词和资源 URI 提供参数自动补全建议。

同步 (Sync)
异步 (Async)

// Sync completion specification
var syncCompletionSpecification = new McpServerFeatures.SyncCompletionSpecification(
			new McpSchema.PromptReference("code_review"), (exchange, request) -> {

        // completion implementation ...

        return new McpSchema.CompleteResult(
            new CompleteResult.CompleteCompletion(
              List.of("python", "pytorch", "pyside"),
              10, // total
              false // hasMore
            ));
      }
);

// Create a sync server with completion capabilities
var mcpServer = McpServer.sync(mcpServerTransportProvider)
  .capabilities(ServerCapabilities.builder()
    .completions() // enable completions support
      // ...
    .build())
  // ...
  .completions(syncCompletionSpecification) // register completion specification
  .build();

// Async prompt specification
var asyncCompletionSpecification = new McpServerFeatures.AsyncCompletionSpecification(
			new McpSchema.PromptReference("code_review"), (exchange, request) -> {

        // completion implementation ...

        return Mono.just(new McpSchema.CompleteResult(
            new CompleteResult.CompleteCompletion(
              List.of("python", "pytorch", "pyside"),
              10, // total
              false // hasMore
            )));
      }
);

// Create a async server with completion capabilities
var mcpServer = McpServer.async(mcpServerTransportProvider)
  .capabilities(ServerCapabilities.builder()
    .completions() // enable completions support
      // ...
    .build())
  // ...
  .completions(asyncCompletionSpecification) // register completion specification
  .build();

McpSchema.CompletionReference 定义了补全规范的类型（PromptReference 或 ResourceReference）和标识符（例如处理器）。处理器函数处理请求并返回补全响应。第一个参数是用于客户端交互的 McpAsyncServerExchange，第二个参数是 CompleteRequest 实例。查看使用补全以了解如何在客户端使用补全能力。

从服务端使用采样 (Sampling)

要使用采样能力，您需要一个支持采样的兼容客户端。不需要特殊的服务端配置，但在发起请求前请验证客户端的采样支持。了解关于客户端采样支持的信息。当兼容的客户端连接到有状态服务端时，服务端可以请求语言模型生成：

同步 (Sync) API
异步 (Async) API

// Create a server
McpSyncServer server = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .build();

// Define a tool that uses sampling
var calculatorTool = new McpServerFeatures.SyncToolSpecification(
    new Tool("ai-calculator", "Performs calculations using AI", schema),
    (exchange, arguments) -> {
        // Check if client supports sampling
        if (exchange.getClientCapabilities().sampling() == null) {
            return new CallToolResult("Client does not support AI capabilities", false);
        }

        // Create a sampling request
        McpSchema.CreateMessageRequest request = McpSchema.CreateMessageRequest.builder()
            .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
                new McpSchema.TextContent("Calculate: " + arguments.get("expression")))
            .modelPreferences(McpSchema.ModelPreferences.builder()
                .hints(List.of(
                    McpSchema.ModelHint.of("claude-3-sonnet"),
                    McpSchema.ModelHint.of("claude")
                ))
                .intelligencePriority(0.8)  // Prioritize intelligence
                .speedPriority(0.5)         // Moderate speed importance
                .build())
            .systemPrompt("You are a helpful calculator assistant. Provide only the numerical answer.")
            .maxTokens(100)
            .build();

        // Request sampling from the client
        McpSchema.CreateMessageResult result = exchange.createMessage(request);

        // Process the result
        String answer = result.content().text();
        return new CallToolResult(answer, false);
    }
);

// Add the tool to the server
server.addTool(calculatorTool);

// Create a server
McpAsyncServer server = McpServer.async(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .build();

// Define a tool that uses sampling
var calculatorTool = new McpServerFeatures.AsyncToolSpecification(
    new Tool("ai-calculator", "Performs calculations using AI", schema),
    (exchange, arguments) -> {
        // Check if client supports sampling
        if (exchange.getClientCapabilities().sampling() == null) {
            return Mono.just(new CallToolResult("Client does not support AI capabilities", false));
        }

        // Create a sampling request
        McpSchema.CreateMessageRequest request = McpSchema.CreateMessageRequest.builder()
            .content(new McpSchema.TextContent("Calculate: " + arguments.get("expression")))
            .modelPreferences(McpSchema.ModelPreferences.builder()
                .hints(List.of(
                    McpSchema.ModelHint.of("claude-3-sonnet"),
                    McpSchema.ModelHint.of("claude")
                ))
                .intelligencePriority(0.8)  // Prioritize intelligence
                .speedPriority(0.5)         // Moderate speed importance
                .build())
            .systemPrompt("You are a helpful calculator assistant. Provide only the numerical answer.")
            .maxTokens(100)
            .build();

        // Request sampling from the client
        return exchange.createMessage(request)
            .map(result -> {
                // Process the result
                String answer = result.content().text();
                return new CallToolResult(answer, false);
            });
    }
);

// Add the tool to the server
server.addTool(calculatorTool)
    .subscribe();

CreateMessageRequest 对象允许您指定：Content（模型的输入文本或图像）、Model Preferences（模型选择的提示和优先级）、System Prompt（模型行为指令）以及 Max Tokens（生成响应的最大长度）。

从服务端使用启发 (Elicitation)

要使用启发能力，您需要一个支持启发的兼容客户端。不需要特殊的服务端配置，但在发起请求前请验证客户端的启发支持。了解关于客户端启发支持的信息。当兼容的客户端连接到有状态服务端时，服务端可以向用户请求额外信息：

同步 (Sync) API
异步 (Async) API

// Create a server
McpSyncServer server = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .build();

// Define a tool that uses elicitation
var calculatorTool = new McpServerFeatures.SyncToolSpecification(
    new Tool("ai-calculator", "Performs calculations using AI", schema),
    (exchange, arguments) -> {
        // Check if client supports elicitation
        if (exchange.getClientCapabilities().elicitation() == null) {
            return new CallToolResult("Client does not support elicitation capabilities", false);
        }

        // Create an elicitation request
        McpSchema.ElicitRequest request = McpSchema.ElicitRequest.builder()
					.message("Test message")
					.requestedSchema(
							Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
					.build();

        // Request elicitation from the client
        McpSchema.ElicitResult result = exchange.createElicitation(request);

        // Process the result
        Map<String, Object> answer = result.content();
        return new CallToolResult(answer, false);
    }
);

// Add the tool to the server
server.addTool(calculatorTool);

// Create a server
McpAsyncServer server = McpServer.async(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .build();

// Define a tool that uses elicitation
var calculatorTool = new McpServerFeatures.AsyncToolSpecification(
    new Tool("ai-calculator", "Performs calculations using AI", schema),
    (exchange, arguments) -> {
        // Check if client supports elicitation
        if (exchange.getClientCapabilities().elicitation() == null) {
            return Mono.just(new CallToolResult("Client does not support elicitation capabilities", false));
        }

        // Create an elicitation request
        McpSchema.ElicitRequest request = McpSchema.ElicitRequest.builder()
            .message("Test message")
            .requestedSchema(
                    Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
            .build();

        // Request elicitation from the client
        return exchange.createElicitation(request)
            .map(result -> {
                // Process the result
                Map<String, Object> answer = result.content();
                return new CallToolResult(answer, false);
            });
    }
);

// Add the tool to the server
server.addTool(calculatorTool)
    .subscribe();

日志支持

服务端提供结构化日志记录能力，允许向客户端发送具有不同严重程度级别的日志消息。日志通知只能从现有的客户端会话（如工具、资源和提示词调用）内发送。例如，我们可以在工具处理器函数中发送日志消息。在客户端，您可以注册一个日志消费者来接收来自服务端的日志消息，并设置最小日志级别以过滤消息。

var mcpClient = McpClient.sync(transport)
        .loggingConsumer(notification -> {
            System.out.println("Received log message: " + notification.data());
        })
        .build();

mcpClient.initialize();

mcpClient.setLoggingLevel(McpSchema.LoggingLevel.INFO);

// Call the tool that sends logging notifications
CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("logging-test", Map.of()));

服务端可以在工具/资源/提示词处理器函数中使用 McpAsyncServerExchange/McpSyncServerExchange 对象发送日志消息。

var tool = new McpServerFeatures.AsyncToolSpecification(
    new McpSchema.Tool("logging-test", "Test logging notifications", emptyJsonSchema),
    (exchange, request) -> {

      exchange.loggingNotification( // Use the exchange to send log messages
          McpSchema.LoggingMessageNotification.builder()
            .level(McpSchema.LoggingLevel.DEBUG)
            .logger("test-logger")
            .data("Debug message")
            .build())
        .block();

      return Mono.just(new CallToolResult("Logging test completed", false));
    });

var mcpServer = McpServer.async(mcpServerTransportProvider)
  .serverInfo("test-server", "1.0.0")
  .capabilities(
    ServerCapabilities.builder()
      .logging() // Enable logging support
      .tools(true)
      .build())
  .tools(tool)
  .build();

客户端可以通过 mcpClient.setLoggingLevel(level) 请求控制其接收的最小日志级别。低于设置级别的消息将被过滤掉。支持的日志级别（按严重程度递增排序）：DEBUG (0), INFO (1), NOTICE (2), WARNING (3), ERROR (4), CRITICAL (5), ALERT (6), EMERGENCY (7)

错误处理

SDK 通过 McpError 类提供全面的错误处理，涵盖协议兼容性、传输通信、JSON-RPC 消息传递、工具执行、资源管理、提示词处理、超时和连接问题。这种统一的错误处理方法确保了在同步和异步操作中都能实现一致且可靠的错误管理。

开始使用

关于 MCP

使用 MCP 开发

开发者工具

SDK 内容

服务器功能

在处理器中保留线程本地变量 (Thread-locals)

服务端传输层提供者

服务端能力

工具 (Tool) 规范

资源 (Resource) 规范

提示词 (Prompt) 规范

补全 (Completion) 规范

从服务端使用采样 (Sampling)

从服务端使用启发 (Elicitation)

日志支持

错误处理

开始使用

关于 MCP

使用 MCP 开发

开发者工具

​SDK 内容

​服务器功能

​在处理器中保留线程本地变量 (Thread-locals)

​服务端传输层提供者

​服务端能力

​工具 (Tool) 规范

​资源 (Resource) 规范

​提示词 (Prompt) 规范

​补全 (Completion) 规范

​从服务端使用采样 (Sampling)

​从服务端使用启发 (Elicitation)

​日志支持

​错误处理

SDK 内容

服务器功能

在处理器中保留线程本地变量 (Thread-locals)

服务端传输层提供者

服务端能力

工具 (Tool) 规范

资源 (Resource) 规范

提示词 (Prompt) 规范

补全 (Completion) 规范

从服务端使用采样 (Sampling)

从服务端使用启发 (Elicitation)

日志支持

错误处理