Java SDK

Официальный Java SDK для Model Context Protocol — создание MCP-серверов и клиентов с поддержкой Spring Boot

Официальный Java SDK для Model Context Protocol обеспечивает интеграцию Java-приложений с AI-моделями через стандартизированный интерфейс. Поддерживает синхронные и асинхронные паттерны взаимодействия.

Требования

Java 17+
Maven или Gradle
Docker и npx (для тестов)

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.modelcontextprotocol.sdk</groupId>
      <artifactId>mcp-bom</artifactId>
      <version>LATEST</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp</artifactId>
  </dependency>
</dependencies>

dependencies {
    implementation(platform("io.modelcontextprotocol.sdk:mcp-bom:LATEST"))
    implementation("io.modelcontextprotocol.sdk:mcp")
}

Архитектура SDK

Модульная структура

Модуль	Описание
`mcp-bom`	Версии зависимостей (Bill of Materials)
`mcp-core`	Эталонная реализация (STDIO, JDK HttpClient, Servlet)
`mcp-json`	Абстракция JSON-сериализации
`mcp-jackson2`	Реализация JSON на базе Jackson
`mcp`	Удобный бандл (core + Jackson)
`mcp-test`	Утилиты для тестирования
`mcp-spring`	Интеграция со Spring (WebClient, WebFlux, WebMVC)

Ключевые решения

JSON-сериализация:

Jackson как реализация по умолчанию
Абстракция mcp-json для альтернативных библиотек

Модель программирования:

Reactive Streams для публичных API
Project Reactor как внутренняя реализация
Синхронный фасад для блокирующих сценариев

Observability:

SLF4J для логирования
Reactor Context для распространения трассировки

Создание клиента

import io.modelcontextprotocol.sdk.McpClient;
import io.modelcontextprotocol.sdk.McpClientSession;

// Создание клиента
McpClient client = McpClient.builder()
    .clientInfo("my-client", "1.0.0")
    .build();

// Подключение через stdio
McpClientSession session = client.connect(stdioTransport);

// Получение списка инструментов
ListToolsResult tools = session.listTools().block();

// Вызов инструмента
CallToolResult result = session.callTool(
    "weather",
    Map.of("location", "Moscow")
).block();

Создание сервера

import io.modelcontextprotocol.sdk.McpServer;
import io.modelcontextprotocol.sdk.McpServerSession;

// Создание сервера
McpServer server = McpServer.builder()
    .serverInfo("my-server", "1.0.0")
    .capabilities(ServerCapabilities.builder()
        .tools(true)
        .resources(true)
        .build())
    .build();

// Регистрация инструмента
server.addTool(
    "calculator",
    "Выполняет математические вычисления",
    inputSchema,
    (arguments) -> {
        String expression = arguments.get("expression").asText();
        double result = evaluate(expression);
        return new CallToolResult(List.of(
            new TextContent("Результат: " + result)
        ));
    }
);

// Запуск сервера
server.start(stdioTransport);

Транспорты

Клиентские транспорты

JDK HttpClient (по умолчанию):

HttpClientTransport transport = HttpClientTransport.builder()
    .endpoint(URI.create("http://localhost:8080/mcp"))
    .build();

Spring WebClient:

WebClientTransport transport = WebClientTransport.builder()
    .webClient(webClient)
    .endpoint(URI.create("http://localhost:8080/mcp"))
    .build();

Серверные транспорты

Jakarta Servlet:

ServletTransport transport = new ServletTransport(server);
// Регистрация в Servlet-контейнере

Spring WebFlux:

@Bean
RouterFunction<ServerResponse> mcpRoutes(McpServer server) {
    return WebFluxTransport.routes(server);
}

Spring WebMVC:

@Bean
RouterFunction<ServerResponse> mcpRoutes(McpServer server) {
    return WebMvcTransport.routes(server);
}

Интеграция со Spring Boot

Клиент Spring Boot

@Configuration
public class McpClientConfig {

    @Bean
    McpClient mcpClient() {
        return McpClient.builder()
            .clientInfo("spring-client", "1.0.0")
            .build();
    }
}

Сервер Spring Boot

@Configuration
public class McpServerConfig {

    @Bean
    McpServer mcpServer() {
        return McpServer.builder()
            .serverInfo("spring-server", "1.0.0")
            .capabilities(ServerCapabilities.builder()
                .tools(true)
                .build())
            .build();
    }

    @Bean
    RouterFunction<ServerResponse> mcpRoutes(McpServer server) {
        return WebFluxTransport.routes(server);
    }
}

Авторизация

SDK предоставляет pluggable hooks для авторизации без встроенной реализации:

McpServer server = McpServer.builder()
    .serverInfo("secure-server", "1.0.0")
    .authorizationHandler((request) -> {
        String token = request.getHeader("Authorization");
        return validateToken(token);
    })
    .build();

Асинхронная модель

Реактивный подход (рекомендуется)

// Асинхронное выполнение
Mono<CallToolResult> resultMono = session.callTool("weather", args);

resultMono
    .doOnSuccess(result -> log.info("Результат: {}", result))
    .doOnError(error -> log.error("Ошибка: {}", error))
    .subscribe();

Синхронный фасад

// Блокирующее выполнение
CallToolResult result = session.callTool("weather", args).block();

Сборка из исходников

# Сборка без тестов
./mvnw clean install -DskipTests

# Запуск тестов (требуется Docker и npx)
./mvnw test

Документация

Features — обзор возможностей
Architecture — архитектура SDK
MCP Client — использование клиента
MCP Server — создание сервера
Spring AI MCP — интеграция со Spring

Ссылки

GitHub
Maven Central
Spring Initializer — быстрый старт со Spring AI MCP