Chapter 7: Applying Model Context Protocol

Introduction

Introduces MCP as a way to package related tools for sharing across AI applications, in contrast to coding tools into one Spring AI application.

• Shared tool collections with MCP: Explain that Model Context Protocol (MCP) collects related tools so they can be shared and used by AI applications, rather than coding the tools as part of each application.
  Why it matters: This distinction explains why an application might use MCP instead of keeping every tool in its own code.

Key terms: Model Context Protocol (MCP), tools, Spring AI application

7.1 Introducing Model Context Protocol

Introduces MCP’s client-server model, its transport options, and a Claude Desktop example of using an existing MCP Server.

• MCP client-server relationship: Explain how an MCP Server exposes resource-backed tools and how an MCP Client makes those tools available to an LLM. State that MCP is not limited to Anthropic models.
  Why it matters: This relationship explains how an application can give an LLM access to tools supplied by another service.
• MCP transport options: Distinguish the three MCP transport options and describe which ones Spring AI 1.0.0 supports.
  Why it matters: The transport an MCP Server offers determines whether this version of Spring AI can work with it.
• Existing servers in Claude Desktop: Describe how the section’s Google Maps example uses an existing MCP Server with Claude Desktop.
  Why it matters: The example shows what using a ready-made MCP Server looks like before integrating one into a Spring AI application.

Key terms: MCP Server, MCP Client, tools, prompt’s context, STDIO, HTTP+SSE, Streamable HTTP, Spring AI 1.0.0, Claude Desktop, Google Maps MCP Server

7.2 Working with MCP Clients

This section shows how to connect a Spring AI application to an existing Filesystem MCP Server and make its tools available to a ChatClient.

• STDIO client configuration: Describe how Spring Boot configuration connects an MCP Client to the Filesystem MCP Server over STDIO. Explain what the configured command and arguments do when the application starts.
  Why it matters: This explains how the application launches and connects to an existing server without implementing one.
• Claude Desktop configuration alternative: Distinguish Spring-style MCP Client properties from the Claude Desktop–compatible JSON option described for STDIO servers.
  Why it matters: Existing server configuration can be reused instead of translated into Spring properties.
• MCP tools in ChatClient: Explain how the controller makes an MCP Server's tools available to ChatClient and describe the filesystem capabilities used to try it out.
  Why it matters: Registering the callbacks is what lets the application use the connected server's functionality in answers.

Key terms: MCP Client, STDIO transport, spring.ai.mcp.client, command, args, Spring-style configuration, Claude Desktop–compatible JSON, servers-configuration, ChatClient, ToolCallbackProvider

7.3 Creating your own MCP Server

This section motivates a board-game MCP Server whose tools expose structured game data for questions that rulebook-based RAG handles poorly.

• Cross-game question data needs: Explain why questions about player counts or play time across many games are better answered by querying a database or API than by searching rulebook chunks with RAG.
  Why it matters: Choosing data suited to the question makes answers about a collection of games more reliable.
• Board-game MCP tool purpose: Describe how the proposed Spring AI MCP Server would help a client answer board-game recommendations by exposing tools that return basic game data.
  Why it matters: The server gives client applications access to game facts they can use when answering recommendation questions.

Key terms: RAG, document chunks, database, API, Spring AI, MCP Server, tools, client application

7.3.1 Building the server

This subsection explains how to initialize a Spring Boot project for a database-backed custom MCP Server and why it needs no LLM dependency.

• MCP Server project dependencies: Describe the dependencies to select for the new Spring Boot MCP Server and what each database-related dependency is for. Explain why the server does not need an OpenAI or other LLM-specific dependency.
  Why it matters: These choices give the server its MCP and database capabilities without adding an LLM integration it will not use.

Key terms: Model Context Protocol Server, Spring Data JDBC, PostgreSQL Driver, Docker Compose Support, LLM-specific dependency

7.3.2 Setting up the database

This section sets up a PostgreSQL database for the MCP Server and defines the Spring Data JDBC types used to query its game data.

• PostgreSQL startup and initialization: Explain how the project starts PostgreSQL and initializes it with a Game table and sample data, including why explicit SQL initialization is needed.
  Why it matters: The MCP Server needs a running database with game data before its tools can answer questions about games.
• Game repository and record: Describe how GameRepository provides the database queries the MCP Server needs and how Game represents their results.
  Why it matters: These types give the MCP Server a way to count games and retrieve matching game records.

Key terms: Docker Compose, PostgreSQL, compose.yaml, schema.sql, data.sql, spring.sql.init.mode, Spring Data JDBC, GameRepository, CrudRepository, count()

7.3.3 Creating the MCP Server tools

This section shows how repository-backed tool methods become MCP Server tools, why a STDIO server must keep standard output free of unrelated text, and how the built server is run.

• Repository-backed game tools: Explain how GameTools methods obtain game data and are marked as tools: the constructor receives a GameRepository, which the @Tool-annotated methods use to query the games database.
  Why it matters: These methods provide the game-querying behavior the MCP Server will expose.
• MCP tool provider bean: Explain how the annotated GameTools methods are made available as MCP tools: configure a ToolCallbackProvider bean, after which Spring AI auto-configuration creates the other components needed by the server.
  Why it matters: The provider bean is the step that makes the existing tool methods available through MCP.
• Clean STDIO communication: Justify disabling the Spring Boot banner and standard-output logging for a STDIO MCP Server, and describe the alternative of directing logs to a different sink.
  Why it matters: Keeping standard output clean prevents ordinary application output from corrupting MCP communication.

Key terms: @Tool, GameTools, GameRepository, ToolCallbackProvider, toolCallbackProvider(), Spring AI auto-configuration, STDIO transport, standard output, Spring Boot’s ASCII art banner

7.3.4 Inspecting the MCP Server

Shows how to connect MCP Inspector to the executable MCP Server and check that its tools are exposed and respond.

• Inspector connection setup: Describe how to launch MCP Inspector and connect it to the server’s executable JAR, including the Docker Compose file setting needed by this Spring Boot server.
  Why it matters: These settings let the inspector start and connect to this server without building a full MCP client.
• Exposed tool verification: Explain how to use the connected inspector to confirm which tools the server exposes and try a tool response, and state the limit of that check.
  Why it matters: It lets you check the server’s tool exposure and responses before involving an AI application.

Key terms: MCP Inspector, executable JAR, SPRING_DOCKER_COMPOSE_FILE, compose.yaml, Tools tab, List Tools, GameTools, Run Tool

7.3.5 Using the server in a client application

Shows how to connect a Spring AI client to the custom Board Game DB MCP Server, try it through the /ask endpoint, and understand why its STDIO setup may be worth changing.

• Board Game Server Client Setup: Describe how to use a new or existing Spring AI application with the Board Game DB MCP Server, including the two configuration options and their path requirements. Explain how questions sent to /ask can check that the connection works.
  Why it matters: It lets you connect an application to your own server and verify the result with a practical question.
• STDIO Client Server Relationship: Explain who starts an MCP Server using STDIO and how it communicates with the client. Distinguish why local operation mattered for the Filesystem MCP Server but is not necessary for the Board Game DB MCP Server.
  Why it matters: This explains the motivation for considering a transport that lets the board-game server run independently.

Key terms: MCP Client, Board Game DB MCP Server, application.yaml, Claude Desktop configuration, JAVA_HOME, MCP_SERVER_PATH, STDIO transport, standard input, standard output, Filesystem MCP Server

7.4 Working with the HTTP+SSE transport

This section contrasts STDIO with HTTP+SSE for MCP communication and explains why the book uses HTTP+SSE despite its deprecation.

• MCP transport deployment tradeoffs: Explain how STDIO couples an MCP client and server at deployment, and how HTTP+SSE lets them run and be managed independently.
  Why it matters: The transport choice affects where the server can run and how easily you can operate it.
• HTTP transport specification status: Distinguish HTTP+SSE’s deprecated status from the book’s reason for covering it instead of Streamable HTTP.
  Why it matters: It explains why the example uses a transport that the MCP specification has since replaced.
• Spring AI transport switch: Describe the stated extent of changes needed to use HTTP+SSE rather than STDIO in the Spring AI example.
  Why it matters: It sets expectations for the amount of application change involved in switching transports.

Key terms: STDIO transport, HTTP+SSE transport, MCP Server, Streamable HTTP transport, Spring AI, Java MCP SDK, HTTP+SSE, properties, build dependency

7.4.1 Configuring an HTTP+SSE in the MCP Server

This section explains how to switch an MCP Server from STDIO to HTTP+SSE using a Spring starter, choose between MVC and WebFlux implementations, and restore settings appropriate for a web server.

• HTTP+SSE starter switch: Explain that replacing the original MCP Server starter with an HTTP+SSE transport starter is the main configuration change, because Spring Boot autoconfiguration handles the transport setup.
  Why it matters: You can change the server’s transport primarily through its build dependency rather than configuring the transport by hand.
• MVC and WebFlux transport choices: Distinguish the Spring MVC and Spring WebFlux HTTP+SSE starters by their nonreactive or reactive foundations and their respective Tomcat or Netty servers; describe the thread-efficiency benefit given for WebFlux.
  Why it matters: The starter choice also determines the web framework and server that handle MCP requests.
• Web server property cleanup: Describe why the STDIO-era banner and logging settings should be removed for HTTP+SSE, and explain that setting port 3001 is optional but convenient for MCP Inspector.
  Why it matters: Cleaning up the old STDIO settings prepares the server for HTTP+SSE, while the suggested port makes inspection convenient.

Key terms: MCP Server, HTTP+SSE transport, starter dependency, autoconfiguration, Spring MVC, Spring WebFlux, Tomcat, Netty, reactive, STDIO transport

7.4.2 Inspecting the MCP Server

Shows how to start an HTTP+SSE-enabled MCP Server and verify its tools with MCP Inspector.

• HTTP+SSE server inspection: Describe how to run the MCP Server independently and use MCP Inspector to confirm that its tools are available and callable.
  Why it matters: Checking the server with MCP Inspector separates server connectivity and tool problems from client-application problems.

Key terms: MCP Inspector, HTTP+SSE client transport, SSE, List Tools, Run Tool

7.4.3 Configuring the client to use an HTTP+SSE server

This subsection shows how to connect an MCP Client to an HTTP+SSE server and identifies the resulting independence between server and client.

• HTTP+SSE client configuration: Describe how to configure an MCP Client for an HTTP+SSE server using Spring configuration properties, including the connection name and server URL. Distinguish the optional reactive-client starter from the standard starter, which can remain in place.
  Why it matters: These settings tell the client where to connect without requiring a change to its standard starter dependency.
• Independent server management: Explain the practical benefit the subsection attributes to using the configured HTTP+SSE transport: the MCP Server can be developed, evolved, deployed, and managed independently from the client.
  Why it matters: Independent server management is the larger benefit highlighted after the client connection works.

Key terms: HTTP+SSE, MCP Client, Spring configuration properties, spring.ai.mcp.client.sse.connections, url, reactive client, MCP Server, independently

7.5 Exposing prompts and resources

Explains how an MCP Server can supply predefined prompts and domain data to an application, and identifies how Spring AI declares them.

• Server-provided prompt templates: Explain how an MCP Server can provide predefined prompts that an application fills with details from its user interface before sending them to an LLM.
  Why it matters: This separates the prompt supplied by the server from the UI details supplied by the application.
• Domain data resources: Describe what resources exposed by an MCP Server can provide to an application.
  Why it matters: Resources give the application access to domain-related data as well as predefined prompts.
• Spring bean declarations: State where and how Spring AI’s MCP module lets developers declare prompts and resources.
  Why it matters: This identifies the Spring configuration mechanism used to expose prompts and resources.

Key terms: MCP Server, predefined prompts, UI, LLM, resources, textual, binary data, Spring AI’s MCP module, Spring configuration, @Bean-annotated methods

7.5.1 Declaring prompt and resource-exposing beans

This section shows how to expose prompts and a repository-backed resource from a Spring AI MCP Server by declaring specification-list beans.

• Prompt specification beans: Explain how a Spring AI MCP Server exposes prompts through a bean containing prompt specifications. Describe how each specification pairs prompt metadata with a lambda that turns a client-supplied argument into a prompt result.
  Why it matters: This distinction explains both what a client can discover about a prompt and how the server produces it when requested.
• Repository-backed resource specification: Describe how the example exposes a game-list resource using a bean that returns resource specifications, including how repository data becomes the resource text.
  Why it matters: It shows how application data can be presented to MCP clients as a resource rather than as a prompt.

Key terms: prompt specification, prompt definition, prompt result, SyncPromptSpecification, AsyncPromptSpecification, resource specification, GameRepository, Game List resource

7.5.2 Applying annotation-driven prompts and resources

This section shows how a community annotation project defines MCP prompts and resources in service methods, then exposes them through simpler specification beans.

• Annotation project status: Explain why an MCP Server needs a separate dependency to use annotation-driven prompts and resources.
  Why it matters: This explains why the annotation approach needs an added dependency.
• Annotated prompt methods: Describe how a service method defines an MCP prompt using annotations and what it returns.
  Why it matters: These annotations make a prompt’s metadata, input, and response visible in one service method.
• Annotated resource methods: Describe how an annotated service method supplies an MCP resource and distinguish text from binary resource content.
  Why it matters: This shows how an MCP resource request reaches the method that produces its content.
• Annotation specification beans: Explain how annotated service methods become exposed MCP prompts and resources.
  Why it matters: The provider bean is the step that makes annotated methods available through the MCP interface.

Key terms: mcp-annotations, incubating, @McpPrompt, @McpArg, PromptMessage, @McpResource, TextResourceContents, BlobResourceContents, GameRepository, @Bean

7.6 Summary