spring-project-samples

Spring AI - MCP Starter WebFlux Client

This project demonstrates how to use the Spring AI MCP (Model Context Protocol) Client Boot Starter with WebFlux in a Spring Boot application. It showcases how to connect to MCP servers and integrate them with Spring AI’s tool execution framework.

Follow the MCP Client Boot Starter reference documentation.

Overview

The project uses Spring Boot 3.3.6 and Spring AI 1.1.0-SNAPSHOT to create a command-line application that demonstrates MCP server integration with WebFlux. The application:

Connects to MCP servers using STDIO and/or SSE (WebFlux-based) transports
Integrates with Spring AI’s chat capabilities
Demonstrates tool execution through MCP servers
Takes a user-defined question via the -Dai.user.input command-line property, which is mapped to a Spring @Value annotation in the code

For example, running the application with -Dai.user.input="What tools are available?" will inject this question into the application through Spring’s property injection, and the application will use it to query the MCP server using WebFlux’s reactive programming model.

Prerequisites

Java 17 or later
Maven 3.6+
Anthropic API key (Claude) (Get one at https://docs.anthropic.com/en/docs/initial-setup)
OpenAI API key (optional, commented out by default) (Get one at https://platform.openai.com/api-keys)
Brave Search API key (for the Brave Search MCP server) (Get one at https://brave.com/search/api/)

Dependencies

The project uses the following main dependencies:

<dependencies>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-mcp-client-webflux</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-anthropic</artifactId>
    </dependency>
    <!-- OpenAI dependency is commented out by default but can be enabled -->
    <!-- <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
    </dependency> -->
</dependencies>

Configuration

Application Properties

Check the MCP Client configuration properties documentation.

The application can be configured through application.properties or application.yml:

Common Properties

# Application Configuration
spring.application.name=mcp
spring.main.web-application-type=none

# AI Provider Configuration
spring.ai.anthropic.api-key=${ANTHROPIC_API_KEY}
spring.ai.openai.api-key=${OPENAI_API_KEY}

# Enable the MCP client tool-callback auto-configuration
spring.ai.mcp.client.toolcallback.enabled=true

STDIO Transport Properties

Follow the STDIO Configuration properties documentation.

Configure a separate, named configuration for each STDIO server you connect to:

spring.ai.mcp.client.stdio.connections.brave-search.command=npx
spring.ai.mcp.client.stdio.connections.brave-search.args=-y,@modelcontextprotocol/server-brave-search

Here, brave-search is the name of your connection.

Alternatively, you can configure STDIO connections using an external JSON file in the Claude Desktop format:

spring.ai.mcp.client.stdio.servers-configuration=classpath:/mcp-servers-config.json

Example mcp-servers-config.json:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {
      }
    }
  }
}

SSE Transport Properties

You can also connect to Server-Sent Events (SSE) servers using WebFlux. Follow the SSE Configuration properties documentation.

The properties for SSE transport are prefixed with spring.ai.mcp.client.sse:

spring.ai.mcp.client.sse.connections.server1.url=http://localhost:8080
spring.ai.mcp.client.sse.connections.server2.url=http://localhost:8081

How It Works

The application demonstrates a simple command-line interaction with an AI model using MCP tools:

The application starts and configures multiple MCP Clients (one for each provided STDIO or SSE connection configuration)
It builds a ChatClient with the configured MCP tools
Sends a predefined question (set via the ai.user.input property) to the AI model
Displays the AI’s response
Automatically closes the application

Running the Application

Set the required environment variables:

export ANTHROPIC_API_KEY=your-api-key
# If using OpenAI (uncomment the dependency in pom.xml first)
# export OPENAI_API_KEY=your-openai-api-key
# For the Brave Search MCP server
export BRAVE_API_KEY=your-brave-api-key

Build the application:
```
./mvnw clean install
```

Run the application:

# Run with the default question from application.properties
java -jar target/mcp-starter-webflux-client-0.0.1-SNAPSHOT.jar
   
# Or specify a custom question
java -Dai.user.input='Does Spring AI support MCP?' -jar target/mcp-starter-webflux-client-0.0.1-SNAPSHOT.jar

The application will execute the question, use the configured MCP tools to answer it, and display the AI assistant’s response.

Additional Resources

This site is open source. Improve this page.