Building an MCP Server Using Spring AI, JSON-RPC and SSE (Server-Sent Events)

A developer built an MCP (Model Context Protocol) server using Spring AI with JSON-RPC and Server-Sent Events (SSE) transport. The implementation enables standardized tool exposure for AI agents by leveraging Spring Boot's auto-configuration to create SSE endpoints and JSON-RPC message handling. The server architecture automatically discovers and registers tools through `@Tool` annotations, wrapping them in `ToolCallback` objects for the MCP tool registry.

Introduction: Modern LLM-powered applications require external tools to interact with real-systems such as a databases, APIs, cloud platforms, and enterprise services. MCP Model context Protocol provides standardized mechanism for exposing tools to AI agents. In this article, we will build an MCP Server using Spring AI with SSE Server-Sent Events transport support. We will also understand how JSON-RPC and Server-Sent Events work together to enable asynchronous communication between AI agents and tools. What is MCP? MCP Model Context Protocol is a protocol designed to expose tools, resources, and capabilities to LLM-powered applications in a standardized way. An MCP server acts as a tool provider, while an MCP client acts as a Consumer. The protocol enables: Why JSON-RPC MCP Model Context Protocol uses JSON-RPC as the communication protocol. JSON-RPC provides: Example request: { "jsonrpc":"2.0", "id":"101", "method":"tools/call", "params":{ "name":"getWeather", "arguments":{ "city":"Atlanta" } } } Why SSE Transport? Traditional HTTP request-response communication is insufficient for long-running AI workflows. SSE Server-sent Events enables: In MCP architecture: Spring AI MCP Server Architecture : The MCP Server Contains: Implementing MCP Server Using Spring AI Folder structure Include below dependencies pom.xml What happens internally when Spring AI MCP Server Starts? Consider the dependency: org.springframework.ai spring-ai-starter-mcp-server-webmvc At first glance it look like a simple starter dependency, but internally Spring boot performs several steps to transform your application into an MCP-compliant server. Step 1: Spring Boot Starts When the application starts: SpringApplication.run Application.class, args ; Spring boot begins its bootstrap process. During bootstrap it scans: META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports Inside every starter dependency. Step 2: MCP Auto Configuration is Discovered The MCP starter contributes auto-configuration classes. Conceptually: Spring-ai-starter-mcp-server-webmvc is McpWebMvcServerTransportAutoConfiguration. Spring Boot automatically imports these configurations into application Context. At this stage Spring creates infrastructure beans required by: No application code has run yet. Step 3: Defining Tools Spring AI MCP server exposes tools using: @Tool @ToolParam Step 4: Registering Tool This is the most important part. Spring AI does not invoke methods directly from JSON-RPC requests. Instead it wraps each discovered tool in to a ToolCallback The tools are registered through: MethodToolCallbackProvider These tools become available in the MCP tool Registry. Step 5: SSE Endpoint is Created The MCP auto-configuration also creates infrastructure for SSE Transport. Conceptually: GET /sse. This endpoint maintains long-lived connections. Client: GET /sse. Connection remains open. Spring internally creates SseEmitter objects for connected clients. Example: Connected clients Client A - SseEmitter Client B - SseEmitter Client C - SseEmittter. These emitters are retained and reused whenever events need to be published. Step 6: JSON-RPC Endpoint is Created The MCP starter also exposes POST /mcp/message. This endpoint accepts JSON-RPC messages. Example: { "jsonrpc":"2.0", "id":3, "method":"tools/call", "params":{ "name":"calculate discount", "arguments":{ "originalPrice":100, "discountPercentage":20 } } } Step 7: Request Arrives Client sends: POST /mcp/message. Spring MCV dispatches request to MCP Controller. Conceptually: DispatcherServlet - MCP Controller. The MCP Controller Parses method = tools/call, toolName = calculateDiscount and arguments = {…}. The Controller queries Tool Registry. Conceptually : ToolCallback callback = registry.find “calculateDiscount” ; Result : calculateDiscountCallback. The callback executes underlying method. conceptually : callback.call argument which internally invokes calculateDiscount method and Tool execution Occurs. Step 8: JSON-RPC Response Creation Framework builds: { "jsonrpc":"2.0", "id":3, "result":{"content": {"type":"text","text":"\"Original Price: $100.00, Discount: 20.0%, you Save: $20.00, Final Price: $80.00\""} } . Notice: id = 3 is preserved. This ID is critical for request-response correlation. Step 9: SSE Publication Instead of returning the response directly through the Original HTTP request, the framework publishes the response through the active SSE channel. Conceptually: SseEmitter.send responseMessage ; Result: { "jsonrpc":"2.0", "id":3, "result":{"content": {"type":"text","text":"\"Original Price: $100.00, Discount: 20.0%, you Save: $20.00, Final Price: $80.00\""} } } is streamed to connected Client. Step 10: Client Receives Event The MCP Client SSE Listener Thread receives: { "jsonrpc":"2.0", "id":3, "result":{"content": {"type":"text","text":"\"Original Price: $100.00, Discount: 20.0%, you Save: $20.00, Final Price: $80.00\""} } } The listener extracts : id=3 Looks up : ConcurrentHashMap< Integer, CompletableFuture pendingRequest Finds : future = pendingRequest.remove 3 Then : future.complete response The waiting caller thread wakes up. Execution: Execute HttpMcpServerApplication.java to bootstrap the Spring Boot application, Which hosts the MCP Server and listens on port 8090. During the spring boot bootstrap process, the MCP auto-configuration scans for tool definitions, create too callbacks, and registers then with MCP server’s tool registry. The MCP auto-configuration also creates infrastructure for SSE Transport. GET /sse endpoint maintains long-lived connections When the MCP client connects to the /sse endpoint, The MCP server establishes a Server-Sent Events SSE stream and returns an endpoint event containing a unique session identifier as shown in above figure. The client extracts the sessionId from the endpoint URL and include it in all subsequent HTTP POST requests to the /mcp/message endpoint, including: The sessionId uniquely identifies a client session and enables the MCP server to correlate requests, responses, and asynchronous events belong to same client. This mechanism forms the foundation of stateful and asynchronous communication between MCP Client and MCP Server when using the SSE transport. According to the MCP protocol lifecycle, the expected life cycle is The purpose of initialize is to negotiate capabilities and protocol versions between client and server. The notification/initialization message tells the server that the client has completed initialization and is ready for normal operations. Initialize: The MCP client sends an HTTP POST request containing the JSON-RPC initialize message. Upon processing the request, The MCP Server publishes the corresponding JSON-RPC response asynchronous over the established /sse event stream. The MCP client sends an HTTP POST request containing the JSON-RPC notification/initialized message. The MCP client sends an HTTP POST request containing the JSON-RPC tools/list message. Upon processing the request, The MCP Server publishes the corresponding JSON-RPC response asynchronous over the established /sse event stream. The MCP client sends an HTTP POST request containing the JSON-RPC tools/list message. Upon processing the request, The MCP Server publishes the corresponding JSON-RPC response asynchronous over the established /sse event stream.