CtrlK
CommunityDocumentationLog inGet started
Tessl Logo

tessl/maven-org-springframework-ai--spring-ai-starter-mcp-client-webflux

Spring Boot starter providing auto-configuration for Model Context Protocol (MCP) client with Spring WebFlux, enabling reactive AI applications to connect to MCP servers via SSE and Streamable HTTP transports

Overview
Eval results
Files

quick-start.mddocs/guides/

Quick Start Guide

Get started with Spring AI MCP Client WebFlux in 5 minutes.

Prerequisites

  • Spring Boot 3.x application
  • Java 17 or higher
  • Maven or Gradle

Step 1: Add Dependency

Maven (pom.xml):

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client-webflux</artifactId>
    <version>1.1.2</version>
</dependency>

Gradle (build.gradle):

implementation 'org.springframework.ai:spring-ai-starter-mcp-client-webflux:1.1.2'

Step 2: Configure Connection

Choose your transport type and configure connection.

Option A: SSE Transport (Remote Server)

spring.ai.mcp.client:
  sse:
    connections:
      my-server:
        url: http://localhost:8080

Option B: Streamable HTTP (Remote Server)

spring.ai.mcp.client:
  streamable-http:
    connections:
      my-server:
        url: http://localhost:9000

Option C: Stdio (Local Process)

spring.ai.mcp.client:
  stdio:
    connections:
      local-server:
        command: node
        args:
          - /path/to/mcp-server.js

Step 3: Use MCP Tools

Option A: With Spring AI (Recommended)

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Service;

@Service
public class AiService {
    private final ChatClient chatClient;
    
    public AiService(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }
    
    public String ask(String question) {
        // MCP tools automatically available to AI
        return chatClient.prompt()
            .user(question)
            .call()
            .content();
    }
}

Option B: Direct Client Usage

import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.spec.McpSchema;
import org.springframework.stereotype.Service;
import java.util.List;

@Service
public class McpService {
    private final List<McpSyncClient> clients;
    
    public McpService(List<McpSyncClient> clients) {
        this.clients = clients;
    }
    
    public void useTools() {
        if (!clients.isEmpty()) {
            McpSyncClient client = clients.get(0);
            
            // List available tools
            List<McpSchema.Tool> tools = client.listTools();
            
            // Execute a tool
            var request = McpSchema.CallToolRequest.builder()
                .name("tool-name")
                .arguments(Map.of("arg", "value"))
                .build();
            var result = client.callTool(request);
        }
    }
}

Step 4: Run Application

./mvnw spring-boot:run

MCP clients will:

  1. Connect to configured servers
  2. Initialize MCP protocol
  3. Discover available tools
  4. Make tools available to Spring AI

Common Configurations

Multiple Servers

spring.ai.mcp.client:
  sse:
    connections:
      weather:
        url: http://localhost:8080
      database:
        url: http://localhost:9000

Async Client

spring.ai.mcp.client:
  type: ASYNC
  sse:
    connections:
      my-server:
        url: http://localhost:8080

Then inject List<McpAsyncClient>:

@Service
public class AsyncService {
    private final List<McpAsyncClient> clients;
    
    public AsyncService(List<McpAsyncClient> clients) {
        this.clients = clients;
    }
    
    public Mono<List<Tool>> getTools() {
        return clients.get(0).listTools();
    }
}

Custom Timeout

spring.ai.mcp.client:
  request-timeout: 60s
  sse:
    connections:
      slow-server:
        url: http://localhost:8080

Mixed Transports

spring.ai.mcp.client:
  stdio:
    connections:
      local-tools:
        command: node
        args: [./local-server.js]
  sse:
    connections:
      remote-notifications:
        url: http://localhost:8080
  streamable-http:
    connections:
      remote-api:
        url: http://localhost:9000

Verification

Check Clients Are Created

@Component
public class StartupVerification {
    
    @EventListener(ApplicationReadyEvent.class)
    public void verifyClients(ApplicationReadyEvent event) {
        var clients = applicationContext.getBean(
            new ParameterizedTypeReference<List<McpSyncClient>>() {}
        );
        
        System.out.println("MCP Clients created: " + clients.size());
        
        clients.forEach(client -> {
            var info = client.getCurrentInitializationResult();
            System.out.println("Connected to: " + info.serverInfo().name());
        });
    }
}

Test Tool Execution

@SpringBootTest
class McpIntegrationTest {
    
    @Autowired
    private List<McpSyncClient> clients;
    
    @Test
    void testToolExecution() {
        assertFalse(clients.isEmpty(), "No MCP clients created");
        
        McpSyncClient client = clients.get(0);
        List<Tool> tools = client.listTools();
        
        assertFalse(tools.isEmpty(), "No tools available");
    }
}

Next Steps

  • Explore Examples: Real-World Scenarios
  • Learn Advanced Features: Edge Cases
  • Customize Behavior: Customization Guide
  • Configure Properties: Configuration Reference
  • Integrate with Spring AI: Tool Callbacks

Troubleshooting

Problem: No clients created

  • Solution: Check spring.ai.mcp.client.enabled=true and verify configuration syntax

Problem: Connection timeout

  • Solution: Increase spring.ai.mcp.client.request-timeout or check server availability

Problem: Tools not available to AI

  • Solution: Verify spring.ai.mcp.client.toolcallback.enabled=true

For detailed troubleshooting, see Reference Documentation.

tessl i tessl/maven-org-springframework-ai--spring-ai-starter-mcp-client-webflux@1.1.0

docs

guides

quick-start.md

index.md

tile.json