spring-ai-examples/model-context-protocol/client-starter/starter-default-client

Spring AI - MCP Starter Client

This project demonstrates how to use the Spring AI MCP (Model Context Protocol) Client Boot Starter 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 and Spring AI to create a command-line application that:

• Connects to MCP servers using STDIO and/or SSE (HttpClient-based) transports
• Integrates with Spring AI's chat capabilities
• Demonstrates tool execution through MCP servers

Prerequisites

• Java 17 or later
• Maven 3.6+
• Anthropic API key (for Claude AI model)

Dependencies

The project uses the following main dependencies:

<dependencies>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-anthropic-spring-boot-starter</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}

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 HttpClient. 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:

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

Running the Application

1. Set the required environment variable:

   export ANTHROPIC_API_KEY=your-api-key
   

2. Build the application:

   ./mvnw clean install
   

3. Run the application:

   java -Dai.user.input='Does Spring AI support MCP?' -jar target/mcp-starter-default-client-0.0.1-SNAPSHOT.jar
   

The application will execute the question "Does Spring AI support MCP?", use the provided brave (or other tools) to answer it, and display the AI assistant's response.

Additional Resources

• Spring AI Documentation
• MCP Client Boot Starter
• Model Context Protocol Specification
• Spring Boot Documentation