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

Name: tessl/maven-org-springframework-ai--spring-ai-mcp
Author: tessl

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

Component	Purpose	Documentation
SyncMcpToolCallback	Wrap individual MCP tools (blocking)	Reference
AsyncMcpToolCallback	Wrap individual MCP tools (reactive)	Reference
SyncMcpToolCallbackProvider	Auto-discover tools (blocking)	Reference
AsyncMcpToolCallbackProvider	Auto-discover tools (reactive)	Reference
McpToolUtils	Utility methods for conversions	Reference
McpToolFilter	Filter discovered tools	Reference
McpToolNamePrefixGenerator	Generate unique tool names	Reference
ToolContextToMcpMetaConverter	Convert context to metadata	Reference

Architecture Overview

The library provides three architectural layers:

Tool Callbacks - Wrap individual MCP tools as Spring AI ToolCallback instances
Tool Callback Providers - Automatically discover and manage tools from MCP servers
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

Feature	Sync	Async
Execution	Blocking	Non-blocking (Reactor)
Client Type	`McpSyncClient`	`McpAsyncClient`
Best For	Simple operations (< 5s)	Long operations (> 5s)
Concurrency	Thread-per-request	Event loop
Backpressure	No	Yes (Mono/Flux)
Thread Model	Blocking threads	Scheduler 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 MCP	Spring Boot	Java	MCP SDK
1.1.2	3.2+	17+	1.0+
1.1.x	3.1+	17+	1.0+
1.0.x	3.0+	17+	1.0+

Documentation Structure

Getting Started

Quick Start Guide - Step-by-step setup and first integration

Examples

Real-World Scenarios - Complete usage examples
Edge Cases - Advanced scenarios and corner cases

Reference Documentation

Architecture - Design patterns and execution models
Synchronous Tool Callbacks - SyncMcpToolCallback API
Asynchronous Tool Callbacks - AsyncMcpToolCallback API
Synchronous Tool Discovery - SyncMcpToolCallbackProvider API
Asynchronous Tool Discovery - AsyncMcpToolCallbackProvider API
MCP Tool Utilities - McpToolUtils API
Tool Filtering and Naming - Customization strategies
Context and Metadata Conversion - Context handling
Connection Information - McpConnectionInfo API
Event Handling - Event-driven updates
Client Customization - Client configuration
Server Integration - Exposing Spring AI functions as MCP tools
AOT and Native Image Support - GraalVM native compilation

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

docs

examples

guides

reference

index.md

tile.json