Skip to content

mcp-spring-migration-guide.md

Latest commit

 

History

History
109 lines (79 loc) · 4.3 KB

mcp-spring-migration-guide.md

File metadata and controls

109 lines (79 loc) · 4.3 KB

MCP Spring Transport Migration Guide

Overview

Starting with Spring AI 2.0, the Spring-specific MCP transport implementations (mcp-spring-webflux and mcp-spring-webmvc) are no longer shipped by the MCP Java SDK. They have been moved into the Spring AI project itself. This is a breaking change that requires dependency and import updates in every application that directly references these transport classes.

Breaking Changes

1. Maven Dependency Group ID Change

The mcp-spring-webflux and mcp-spring-webmvc artifacts have moved from the io.modelcontextprotocol.sdk group to org.springframework.ai.

Before (MCP Java SDK < 1.0.x & Spring AI < 2.0.x)

<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-spring-webflux</artifactId>
</dependency>

<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-spring-webmvc</artifactId>
</dependency>

After (MCP Java SDK ≥ 1.0.x & Spring AI ≥ 2.0.x)

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>mcp-spring-webflux</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>mcp-spring-webmvc</artifactId>
</dependency>

Note: When using the spring-ai-bom or the Spring AI starter dependencies (spring-ai-starter-mcp-server-webflux, spring-ai-starter-mcp-server-webmvc, spring-ai-starter-mcp-client-webflux) no explicit version is needed — the BOM manages it automatically.

2. Java Package Relocation

All transport classes have been moved to org.springframework.ai packages.

Server Transports

Class Old package (MCP SDK) New package (Spring AI)
WebFluxSseServerTransportProvider io.modelcontextprotocol.server.transport org.springframework.ai.mcp.server.webflux.transport
WebFluxStreamableServerTransportProvider io.modelcontextprotocol.server.transport org.springframework.ai.mcp.server.webflux.transport
WebFluxStatelessServerTransport io.modelcontextprotocol.server.transport org.springframework.ai.mcp.server.webflux.transport
WebMvcSseServerTransportProvider io.modelcontextprotocol.server.transport org.springframework.ai.mcp.server.webmvc.transport
WebMvcStreamableServerTransportProvider io.modelcontextprotocol.server.transport org.springframework.ai.mcp.server.webmvc.transport
WebMvcStatelessServerTransport io.modelcontextprotocol.server.transport org.springframework.ai.mcp.server.webmvc.transport

Client Transports

Class Old package (MCP SDK) New package (Spring AI)
WebFluxSseClientTransport io.modelcontextprotocol.client.transport org.springframework.ai.mcp.client.webflux.transport
WebClientStreamableHttpTransport io.modelcontextprotocol.client.transport org.springframework.ai.mcp.client.webflux.transport

Example — Update Imports

// Before
import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
import io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider;
import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;

// After
import org.springframework.ai.mcp.server.webflux.transport.WebFluxSseServerTransportProvider;
import org.springframework.ai.mcp.server.webmvc.transport.WebMvcSseServerTransportProvider;
import org.springframework.ai.mcp.client.webflux.transport.WebFluxSseClientTransport;
import org.springframework.ai.mcp.client.webflux.transport.WebClientStreamableHttpTransport;

3. MCP SDK Version Requirement

Spring AI 2.0 requires MCP Java SDK 1.0.0 (RC1 or later). The SDK version has been bumped from 0.18.x to the 1.0.x release line. Update your BOM or explicit version accordingly.

Spring Boot Auto-configuration Users (No Manual Changes Needed)

If you rely exclusively on Spring Boot auto-configuration via the Spring AI starters, you do not need to change any Java code. The auto-configurations have already been updated internally to reference the new packages. Only update your pom.xml/build.gradle dependency coordinates as described in section 1.