= Model Context Protocol (MCP)

The link:https://modelcontextprotocol.org/docs/concepts/architecture[Model Context Protocol] (MCP) is a standardized protocol that enables AI models to interact with external tools and resources in a structured way. 
It supports multiple transport mechanisms to provide flexibility across different environments.

The link:https://modelcontextprotocol.io/sdk/java[MCP Java SDK] provides a Java implementation of the Model Context Protocol, enabling standardized interaction with AI models and tools through both synchronous and asynchronous communication patterns.

`**Spring AI MCP**` extends the MCP Java SDK with Spring Boot integration, providing both xref:api/mcp/mcp-client-boot-starter-docs.adoc[client] and xref:api/mcp/mcp-server-boot-starter-docs.adoc[server] starters. 
Bootstrap your AI applications with MCP support using link:https://start.spring.io[Spring Initializer].

[NOTE]
====
Breaking Changes in MCP Java SDK 0.8.0 ⚠️

MCP Java SDK version 0.8.0 introduces several breaking changes including a new session-based architecture. If you're upgrading from Java SDK 0.7.0, please refer to the https://github.com/modelcontextprotocol/java-sdk/blob/main/migration-0.8.0.md[Migration Guide] for detailed instructions.
====

== MCP Java SDK Architecture

TIP: This section provides an overview for the link:https://modelcontextprotocol.io/sdk/java[MCP Java SDK architecture]. 
For the Spring AI MCP integration, refer to the xref:#_spring_ai_mcp_integration[Spring AI MCP Boot Starters] documentation.

The Java MCP implementation follows a three-layer architecture:

|===
|  |
^a| image::mcp/mcp-stack.svg[MCP Stack Architecture]
a| * *Client/Server Layer*: The McpClient handles client-side operations while the McpServer manages server-side protocol operations. Both utilize McpSession for communication management.
* *Session Layer (McpSession)*: Manages communication patterns and state through the DefaultMcpSession implementation.
* *Transport Layer (McpTransport)*: Handles JSON-RPC message serialization and deserialization with support for multiple transport implementations.
|===

|===
| link:https://modelcontextprotocol.io/sdk/java/mcp-client[MCP Client] |

a| The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers. It implements the client-side of the protocol, handling:

* Protocol version negotiation to ensure compatibility with servers
* Capability negotiation to determine available features
* Message transport and JSON-RPC communication
* Tool discovery and execution
* Resource access and management
* Prompt system interactions
* Optional features:
** Roots management
** Sampling support
* Synchronous and asynchronous operations
* Transport options:
** Stdio-based transport for process-based communication
** Java HttpClient-based SSE client transport
** WebFlux SSE client transport for reactive HTTP streaming

^a| image::mcp/java-mcp-client-architecture.jpg[Java MCP Client Architecture, width=500]
|===

|===
| link:https://modelcontextprotocol.io/sdk/java/mcp-server[MCP Server] |

a| The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients. It implements the server-side of the protocol, responsible for:

* Server-side protocol operations implementation
** Tool exposure and discovery
** Resource management with URI-based access
** Prompt template provision and handling
** Capability negotiation with clients
** Structured logging and notifications
* Concurrent client connection management
* Synchronous and Asynchronous API support
* Transport implementations:
** Stdio-based transport for process-based communication
** Servlet-based SSE server transport
** WebFlux SSE server transport for reactive HTTP streaming
** WebMVC SSE server transport for servlet-based HTTP streaming

^a| image::mcp/java-mcp-server-architecture.jpg[Java MCP Server Architecture, width=600]
|===

For detailed implementation guidance, using the low-level MCP Client/Server APIs, refer to the link:https://modelcontextprotocol.io/sdk/java[MCP Java SDK documentation].
For simplified setup using Spring Boot, use the MCP Boot Starters described below.

== Spring AI MCP Integration

Spring AI provides MCP integration through the following Spring Boot starters:

=== link:mcp-client-boot-starter-docs.html[Client Starters]
* `spring-ai-starter-mcp-client` - Core starter providing STDIO and HTTP-based SSE support
* `spring-ai-starter-mcp-client-webflux` - WebFlux-based SSE transport implementation

=== link:mcp-server-boot-starter-docs.html[Server Starters]
* `spring-ai-starter-mcp-server` - Core server with STDIO transport support
* `spring-ai-starter-mcp-server-webmvc` - Spring MVC-based SSE transport implementation
* `spring-ai-starter-mcp-server-webflux` - WebFlux-based SSE transport implementation

== Additional Resources

* link:mcp-client-boot-starter-docs.html[MCP Client Boot Starters Documentation]
* link:mcp-server-boot-starter-docs.html[MCP Server Boot Starters Documentation]
* link:mcp-helpers.html[MCP Utilities Documentation]
* link:https://modelcontextprotocol.github.io/specification/[Model Context Protocol Specification]
