このバージョンはまだ開発中であり、まだ安定しているとは考えられていません。最新のスナップショットバージョンについては、Spring AI 1.0.3 を使用してください。

STDIO および SSE MCP サーバー

STDIO および SSE MCP サーバーは、それぞれ専用のスターターを持つ複数のトランスポートメカニズムをサポートします。

STDIO clients または SSE clients を使用して、STDIO および SSE サーバーに接続します。

STDIO MCP サーバー

STDIO サーバートランスポートによる完全な MCP サーバー機能のサポート。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server</artifactId>
</dependency>
  • コマンドラインおよびデスクトップツールに適しています

  • 追加の Web 依存関係は不要

  • 基本的なサーバーコンポーネントの構成

  • ツール、リソース、プロンプト仕様の取り扱い

  • サーバー機能と変更通知の管理

  • 同期サーバーと非同期サーバーの両方の実装をサポート

SSE WebMVC サーバー

Spring MVC に基づく SSE (Server-Sent Events) サーバートランスポートとオプションの STDIO トランスポートによる完全な MCP サーバー機能のサポート。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>
  • Spring MVC を使用した HTTP ベースのトランスポート (WebMvcSseServerTransportProvider)

  • 自動的に構成された SSE エンドポイント

  • オプションの STDIO トランスポート (spring.ai.mcp.server.stdio=true を設定することで有効になります)

  • spring-boot-starter-web および mcp-spring-webmvc の依存関係を含む

SSE WebFlux サーバー

Spring、WebFlux に基づく SSE (Server-Sent Events) サーバートランスポートとオプションの STDIO トランスポートによる完全な MCP サーバー機能のサポート。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>

スターターは、McpWebFluxServerAutoConfiguration および McpServerAutoConfiguration の自動構成をアクティブにして、次の機能を提供します。

  • Spring WebFlux を使用した反応輸送 (WebFluxSseServerTransportProvider)

  • 自動的に構成されたリアクティブ SSE エンドポイント

  • オプションの STDIO トランスポート (spring.ai.mcp.server.stdio=true を設定することで有効になります)

  • spring-boot-starter-webflux および mcp-spring-webflux の依存関係を含む

Spring Boot のデフォルトの動作により、クラスパス上に org.springframework.web.servlet.DispatcherServlet と org.springframework.web.reactive.DispatcherHandler の両方が存在する場合、Spring Boot は DispatcherServlet を優先します。そのため、プロジェクトで spring-boot-starter-web を使用している場合は、spring-ai-starter-mcp-server-webflux ではなく spring-ai-starter-mcp-server-webmvc を使用することをお勧めします。

プロパティの構成

共通プロパティ

すべての共通プロパティには spring.ai.mcp.server という接頭辞が付きます。

プロパティ 説明 デフォルト

enabled

MCP サーバーを有効 / 無効にする

true

tool-callback-converter

Spring AI ToolCallbacks から MCP ツール仕様への変換を有効 / 無効にする

true

stdio

STDIO トランスポートを有効 / 無効にする

false

name

識別用のサーバー名

mcp-server

version

サーバーバージョン

1.0.0

instructions

このサーバーと対話する方法についてクライアントにガイダンスを提供するためのオプションの指示

null

type

サーバーの種類 (SYNC/ASYNC)

SYNC

capabilities.resource

リソース機能を有効化 / 無効化

true

capabilities.tool

ツール機能を有効化 / 無効化

true

capabilities.prompt

プロンプト機能を有効 / 無効にする

true

capabilities.completion

補完機能を有効 / 無効にする

true

resource-change-notification

リソース変更通知を有効にする

true

prompt-change-notification

迅速な変更通知を有効にする

true

tool-change-notification

ツール変更通知を有効にする

true

tool-response-mime-type

ツール名ごとのオプションのレスポンス MIME 型。例: spring.ai.mcp.server.tool-response-mime-type.generateImage=image/png は image/png MIME 型を generateImage() ツール名に関連付けます

-

request-timeout

リクエストがタイムアウトするまでにサーバーからのレスポンスを待機する時間。ツール呼び出し、リソースアクセス、プロンプト操作など、クライアントを通じて行われるすべてのリクエストに適用されます。

20 seconds

MCP アノテーションプロパティ

MCP サーバーアノテーションは、Java アノテーションを使用して MCP サーバーハンドラーを実装するための宣言的な方法を提供します。

サーバーの mcp-annotations プロパティには spring.ai.mcp.server.annotation-scanner という接頭辞が付きます。

プロパティ 説明 デフォルト値

enabled

MCP サーバーアノテーションの自動スキャンを有効 / 無効にする

true

SSE プロパティ

All SSE properties are prefixed with spring.ai.mcp.server:

プロパティ 説明 デフォルト

sse-message-endpoint

Custom SSE message endpoint path for web transport to be used by the client to send messages

/mcp/message

sse-endpoint

Web トランスポートのカスタム SSE エンドポイントパス

/sse

base-url

Optional URL prefix. For example, base-url=/api/v1 means that the client should access the SSE endpoint at /api/v1 + sse-endpoint and the message endpoint is /api/v1 + sse-message-endpoint

-

keep-alive-interval

接続キープアライブ間隔

null (無効)

For backward compatibility reasons, the SSE properties do not have additional suffix (like .sse).

機能と性能

The MCP Server Boot Starter allows servers to expose tools, resources, and prompts to clients. It automatically converts custom capability handlers registered as Spring beans to sync/async specifications based on the server type:

ツール (英語)

サーバーが言語モデルによって呼び出すことができるツールを公開できるようにします。MCP サーバー Boot スターターは以下を提供します。

  • 変更通知のサポート

  • Spring AI ツール are automatically converted to sync/async specifications based on the server type

  • Spring Bean による自動ツール仕様:

@Bean
public ToolCallbackProvider myTools(...) {
    List<ToolCallback> tools = ...
    return ToolCallbackProvider.from(tools);
}

または低レベル API を使用する:

@Bean
public List<McpServerFeatures.SyncToolSpecification> myTools(...) {
    List<McpServerFeatures.SyncToolSpecification> tools = ...
    return tools;
}

The auto-configuration will automatically detect and register all tool callbacks from:

  • Individual ToolCallback beans

  • Lists of ToolCallback beans

  • ToolCallbackProvider Bean

ツールは名前によって重複が排除され、各ツール名の最初のものが使用されます。

You can disable the automatic detection and registration of all tool callbacks by setting the tool-callback-converter to false.

ツールコンテキストのサポート

ToolContext がサポートされており、ツール呼び出しにコンテキスト情報を渡すことができます。exchange キーに McpSyncServerExchange インスタンスが含まれており、McpToolUtils.getMcpExchange(toolContext) を介してアクセスできます。exchange.loggingNotification(…​) と exchange.createMessage(…​) のデモはこちらの例 [GitHub] (英語) を参照してください。

リソース (英語)

サーバーがクライアントにリソースを公開するための標準化された方法を提供します。

  • 静的および動的リソース仕様

  • オプションの変更通知

  • リソーステンプレートのサポート

  • 同期 / 非同期リソース仕様間の自動変換

  • Spring Bean による自動リソース指定:

@Bean
public List<McpServerFeatures.SyncResourceSpecification> myResources(...) {
    var systemInfoResource = new McpSchema.Resource(...);
    var resourceSpecification = new McpServerFeatures.SyncResourceSpecification(systemInfoResource, (exchange, request) -> {
        try {
            var systemInfo = Map.of(...);
            String jsonContent = new ObjectMapper().writeValueAsString(systemInfo);
            return new McpSchema.ReadResourceResult(
                    List.of(new McpSchema.TextResourceContents(request.uri(), "application/json", jsonContent)));
        }
        catch (Exception e) {
            throw new RuntimeException("Failed to generate system info", e);
        }
    });

    return List.of(resourceSpecification);
}

プロンプト (英語)

サーバーがプロンプトテンプレートをクライアントに公開するための標準化された方法を提供します。

  • 変更通知のサポート

  • テンプレートのバージョン管理

  • 同期 / 非同期プロンプト仕様間の自動変換

  • Spring Bean による自動プロンプト指定:

@Bean
public List<McpServerFeatures.SyncPromptSpecification> myPrompts() {
    var prompt = new McpSchema.Prompt("greeting", "A friendly greeting prompt",
        List.of(new McpSchema.PromptArgument("name", "The name to greet", true)));

    var promptSpecification = new McpServerFeatures.SyncPromptSpecification(prompt, (exchange, getPromptRequest) -> {
        String nameArgument = (String) getPromptRequest.arguments().get("name");
        if (nameArgument == null) { nameArgument = "friend"; }
        var userMessage = new PromptMessage(Role.USER, new TextContent("Hello " + nameArgument + "! How can I assist you today?"));
        return new GetPromptResult("A personalized greeting message", List.of(userMessage));
    });

    return List.of(promptSpecification);
}

補完 (英語)

サーバーがクライアントに補完機能を公開するための標準化された方法を提供します。

  • 同期と非同期の両方の完了仕様をサポート

  • Spring Bean による自動登録:

@Bean
public List<McpServerFeatures.SyncCompletionSpecification> myCompletions() {
    var completion = new McpServerFeatures.SyncCompletionSpecification(
        new McpSchema.PromptReference(
					"ref/prompt", "code-completion", "Provides code completion suggestions"),
        (exchange, request) -> {
            // Implementation that returns completion suggestions
            return new McpSchema.CompleteResult(List.of("python", "pytorch", "pyside"), 10, true);
        }
    );

    return List.of(completion);
}

ログ (英語)

Provides a standardized way for servers to send structured log messages to clients. From within the tool, resource, prompt or completion call handler use the provided McpSyncServerExchange/McpAsyncServerExchange exchange object to send logging messages:

(exchange, request) -> {
        exchange.loggingNotification(LoggingMessageNotification.builder()
            .level(LoggingLevel.INFO)
            .logger("test-logger")
            .data("This is a test log message")
            .build());
}

On the MCP client you can register logging consumers to handle these messages:

mcpClientSpec.loggingConsumer((McpSchema.LoggingMessageNotification log) -> {
    // Handle log messages
});

進行状況 (英語)

Provides a standardized way for servers to send progress updates to clients. From within the tool, resource, prompt or completion call handler use the provided McpSyncServerExchange/McpAsyncServerExchange exchange object to send progress notifications:

(exchange, request) -> {
        exchange.progressNotification(ProgressNotification.builder()
            .progressToken("test-progress-token")
            .progress(0.25)
            .total(1.0)
            .message("tool call in progress")
            .build());
}

The Mcp Client can receive progress notifications and update its UI accordingly. For this it needs to register a progress consumer.

mcpClientSpec.progressConsumer((McpSchema.ProgressNotification progress) -> {
    // Handle progress notifications
});

Root List Changes (英語)

When roots change, clients that support listChanged send a root change notification.

  • ルート変更の監視のサポート

  • リアクティブアプリケーション用の非同期コンシューマーへの自動変換

  • Spring Bean によるオプション登録

@Bean
public BiConsumer<McpSyncServerExchange, List<McpSchema.Root>> rootsChangeHandler() {
    return (exchange, roots) -> {
        logger.info("Registering root resources: {}", roots);
    };
}

Ping (英語)

Ping mechanism for the server to verify that its clients are still alive. From within the tool, resource, prompt or completion call handler use the provided McpSyncServerExchange/McpAsyncServerExchange exchange object to send ping messages:

(exchange, request) -> {
        exchange.ping();
}

キープアライブ

Server can optionally, periodically issue pings to connected clients to verify connection health.

By default, keep-alive is disabled. To enable keep-alive, set the keep-alive-interval property in your configuration:

spring:
  ai:
    mcp:
      server:
        keep-alive-interval: 30s

使用例

標準 STDIO サーバー構成

# Using spring-ai-starter-mcp-server
spring:
  ai:
    mcp:
      server:
        name: stdio-mcp-server
        version: 1.0.0
        type: SYNC

WebMVC サーバー構成

# Using spring-ai-starter-mcp-server-webmvc
spring:
  ai:
    mcp:
      server:
        name: webmvc-mcp-server
        version: 1.0.0
        type: SYNC
        instructions: "This server provides weather information tools and resources"
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true
        # sse properties
        sse-message-endpoint: /mcp/messages
        keep-alive-interval: 30s

WebFlux サーバー構成

# Using spring-ai-starter-mcp-server-webflux
spring:
  ai:
    mcp:
      server:
        name: webflux-mcp-server
        version: 1.0.0
        type: ASYNC  # Recommended for reactive applications
        instructions: "This reactive server provides weather information tools and resources"
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true
        # sse properties
        sse-message-endpoint: /mcp/messages
        keep-alive-interval: 30s

MCP サーバーを使用した Spring Boot アプリケーションの作成

@Service
public class WeatherService {

    @Tool(description = "Get weather information by city name")
    public String getWeather(String cityName) {
        // Implementation
    }
}

@SpringBootApplication
public class McpServerApplication {

    private static final Logger logger = LoggerFactory.getLogger(McpServerApplication.class);

    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }

	@Bean
	public ToolCallbackProvider weatherTools(WeatherService weatherService) {
		return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
	}
}

The auto-configuration will automatically register the tool callbacks as MCP tools. You can have multiple beans producing ToolCallbacks, and the auto-configuration will merge them.

アプリケーション例