CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-springframework-ai--spring-ai-mcp

Spring Framework integration for Model Context Protocol (MCP), providing Spring AI function calling capabilities and Spring-friendly abstractions for MCP clients and MCP servers

Overview
Eval results
Files

Spring AI MCP

Spring AI MCP provides Spring Framework integration for the Model Context Protocol (MCP), enabling AI models to interact with external tools and resources through a standardized protocol.

Package Information

  • Package: spring-ai-mcp
  • Group ID: org.springframework.ai
  • Type: Maven
  • Language: Java 17+
  • Spring Boot: 3.x+

Installation

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp</artifactId>
    <version>1.1.2</version>
</dependency>
implementation 'org.springframework.ai:spring-ai-mcp:1.1.2'

Quick Start

Synchronous Tool Integration

import org.springframework.ai.mcp.SyncMcpToolCallbackProvider;

// Create provider
SyncMcpToolCallbackProvider provider = SyncMcpToolCallbackProvider.builder()
    .mcpClients(mcpClient)
    .build();

// Get tool callbacks
ToolCallback[] callbacks = provider.getToolCallbacks();

Asynchronous Tool Integration

import org.springframework.ai.mcp.AsyncMcpToolCallbackProvider;

// Create async provider
AsyncMcpToolCallbackProvider provider = AsyncMcpToolCallbackProvider.builder()
    .mcpClients(asyncClient)
    .build();

// Get tool callbacks
ToolCallback[] callbacks = provider.getToolCallbacks();

Core Components

ComponentPurposeDocumentation
SyncMcpToolCallbackWrap individual MCP tools (blocking)Reference
AsyncMcpToolCallbackWrap individual MCP tools (reactive)Reference
SyncMcpToolCallbackProviderAuto-discover tools (blocking)Reference
AsyncMcpToolCallbackProviderAuto-discover tools (reactive)Reference
McpToolUtilsUtility methods for conversionsReference
McpToolFilterFilter discovered toolsReference
McpToolNamePrefixGeneratorGenerate unique tool namesReference
ToolContextToMcpMetaConverterConvert context to metadataReference

Architecture Overview

The library provides three architectural layers:

  1. Tool Callbacks - Wrap individual MCP tools as Spring AI ToolCallback instances
  2. Tool Callback Providers - Automatically discover and manage tools from MCP servers
  3. Utilities & Strategies - Customization points for filtering, naming, and conversion

See Architecture Reference for details.

Core Imports

// Tool callbacks
import org.springframework.ai.mcp.SyncMcpToolCallback;
import org.springframework.ai.mcp.AsyncMcpToolCallback;

// Tool providers
import org.springframework.ai.mcp.SyncMcpToolCallbackProvider;
import org.springframework.ai.mcp.AsyncMcpToolCallbackProvider;

// Utilities and strategies
import org.springframework.ai.mcp.McpToolUtils;
import org.springframework.ai.mcp.McpToolFilter;
import org.springframework.ai.mcp.McpToolNamePrefixGenerator;
import org.springframework.ai.mcp.ToolContextToMcpMetaConverter;

// MCP SDK (required dependency)
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.client.McpAsyncClient;
import io.modelcontextprotocol.spec.McpSchema;

Key Capabilities

Tool Discovery & Management

  • Automatic tool discovery from MCP servers
  • Caching with manual and event-driven invalidation
  • Custom filtering and naming strategies
  • Multi-server support with name collision handling

Execution Models

  • Synchronous: Blocking execution for simple operations
  • Asynchronous: Reactive execution using Project Reactor for long-running operations

Integration Features

  • Spring Boot auto-configuration support
  • Event-driven tool updates via Spring events
  • Context propagation (reactive and standard)
  • GraalVM native image support

Server Capabilities

  • Expose Spring AI functions as MCP tools
  • Support for both sync and async server specifications
  • WebMVC and WebFlux integration options

Quick Reference: Builder Patterns

SyncMcpToolCallback

SyncMcpToolCallback.builder()
    .mcpClient(McpSyncClient)           // required
    .tool(McpSchema.Tool)               // required
    .prefixedToolName(String)           // optional
    .toolContextToMcpMetaConverter(...) // optional
    .build();

AsyncMcpToolCallback

AsyncMcpToolCallback.builder()
    .mcpClient(McpAsyncClient)          // required
    .tool(McpSchema.Tool)               // required
    .prefixedToolName(String)           // optional
    .toolContextToMcpMetaConverter(...) // optional
    .build();

SyncMcpToolCallbackProvider

SyncMcpToolCallbackProvider.builder()
    .mcpClients(List<McpSyncClient>)    // required
    .toolFilter(McpToolFilter)          // optional
    .toolNamePrefixGenerator(...)       // optional
    .toolContextToMcpMetaConverter(...) // optional
    .build();

AsyncMcpToolCallbackProvider

AsyncMcpToolCallbackProvider.builder()
    .mcpClients(List<McpAsyncClient>)   // required
    .toolFilter(McpToolFilter)          // optional
    .toolNamePrefixGenerator(...)       // optional
    .toolContextToMcpMetaConverter(...) // optional
    .build();

Comparison: Sync vs Async

FeatureSyncAsync
ExecutionBlockingNon-blocking (Reactor)
Client TypeMcpSyncClientMcpAsyncClient
Best ForSimple operations (< 5s)Long operations (> 5s)
ConcurrencyThread-per-requestEvent loop
BackpressureNoYes (Mono/Flux)
Thread ModelBlocking threadsScheduler threads

Common Usage Patterns

Multiple MCP Servers

SyncMcpToolCallbackProvider provider = SyncMcpToolCallbackProvider.builder()
    .mcpClients(client1, client2, client3)
    .toolNamePrefixGenerator(new DefaultMcpToolNamePrefixGenerator())
    .build();

Tool Filtering

McpToolFilter filter = (connectionInfo, tool) ->
    !tool.name().startsWith("internal_") &&
    !tool.description().contains("deprecated");

provider = SyncMcpToolCallbackProvider.builder()
    .mcpClients(client)
    .toolFilter(filter)
    .build();

Cache Invalidation

provider.invalidateCache();  // Force re-discovery
ToolCallback[] updated = provider.getToolCallbacks();

Event-Driven Updates

// Automatic cache invalidation on tool changes
eventPublisher.publishEvent(
    new McpToolsChangedEvent("serverName", tools)
);

Error Handling

All tool execution errors are wrapped in ToolExecutionException:

try {
    String result = callback.call(input);
} catch (ToolExecutionException e) {
    ToolDefinition failedTool = e.getToolDefinition();
    System.err.println("Tool failed: " + e.getMessage());
}

Thread Safety

  • Tool Callbacks: Immutable, fully thread-safe
  • Tool Providers: Thread-safe caching with proper synchronization
  • Utilities: Stateless static methods, inherently thread-safe

Dependencies

<!-- MCP SDK (required) -->
<dependency>
    <groupId>io.modelcontextprotocol</groupId>
    <artifactId>mcp-client</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- Spring AI Core -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-core</artifactId>
    <version>1.0.0</version>
</dependency>

<!-- Project Reactor (for async) -->
<dependency>
    <groupId>io.projectreactor</groupId>
    <artifactId>reactor-core</artifactId>
</dependency>

Version Compatibility

Spring AI MCPSpring BootJavaMCP SDK
1.1.23.2+17+1.0+
1.1.x3.1+17+1.0+
1.0.x3.0+17+1.0+

Documentation Structure

Getting Started

Examples

Reference Documentation

Related Packages

spring-ai-mcp-annotations: Annotation-based MCP server creation (separate artifact)

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-annotations</artifactId>
    <version>1.1.2</version>
</dependency>

Install with Tessl CLI

npx tessl i tessl/maven-org-springframework-ai--spring-ai-mcp@1.1.0
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.springframework.ai/spring-ai-mcp@1.1.x