mcp-server

MCP サーバー - Spring Boot 3

Spring Boot アプリケーションでは、Spring AI MCP サーバースターターを優先してください。MCP SDK の依存関係は Spring AI BOM に管理させ、スターターベースのアプリケーションにスタンドアロン SDK のバージョンを強制しないでください。

依存関係

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

Spring AI を使用しない SDK 単体のアプリケーションでは、現行の MCP Java SDK 2.x リリースを使用し、移行ガイドに従ってください。SDK 単体のサンプルが Spring AI 1.x で管理されるバージョンと一致するとは限りません。

<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp</artifactId>
    <version>2.0.0</version>
</dependency>

Spring AI 1.x のツールコールバック連携

Spring AI 1.0.x では、@Tool メソッドを公開するには MethodToolCallbackProvider を明示的に使用する必要があります。@Tool メソッドを持つだけの @Component では、何も登録されません。Spring AI 1.1.x では、org.springaicommunity.mcp.annotation からインポートした @McpTool／@McpToolParam と spring.ai.mcp.server.annotation-scanner.enabled=true の設定にも対応しています（Spring AI 2.0 では、これらは org.springframework.ai.mcp.annotation に移動しました）。ツールごとに、いずれか一方の登録方法を選んでください。

@Configuration
class McpToolsConfiguration {
    @Bean
    ToolCallbackProvider orderTools(OrderMcpTools tools) {
        return MethodToolCallbackProvider.builder()
            .toolObjects(tools)
            .build();
    }
}

@Component
final class OrderMcpTools {
    private final OrderService orderService;

    OrderMcpTools(OrderService orderService) {
        this.orderService = orderService;
    }

    @Tool(description = "Get an order by UUID with line items and status history")
    OrderResponse getOrder(
            @ToolParam(description = "Order UUID") String orderId) {
        return OrderResponse.from(orderService.findById(UUID.fromString(orderId)));
    }
}

• シリアライズされた JPA エンティティではなく、DTO を返してください。
• 各ツールオブジェクトは一度だけ登録してください。プロバイダーが重複すると、機能も重複して登録されます。
• クライアントやモデルが依存するため、ツール名と説明は安定させてください。
• 結果のサイズ、実行時間、下流への呼び出しに上限を設けてください。
• SDK 単体のコードでは、CallToolResult.builder() などのビルダーを使用してください。以前のコンストラクターは削除されています。

トランスポートの設定

spring:
  main:
    banner-mode: "off"
  ai:
    mcp:
      server:
        name: order-service-mcp
        version: 1.0.0
        type: SYNC
        stdio: true

ローカルクライアントが jar を起動する場合は、stdio を使用してください。リモートサーバーでは、選択した Spring AI 1.x リリースが対応している場合、対応する MVC または WebFlux スターターと Streamable HTTP を使用してください。stdio モードでは stdout が JSON-RPC フレームを運ぶため、stdout に余計な出力が混ざらないようにしてください。

セキュリティと検証

• リモート MCP エンドポイントと、その基盤となるすべてのドメイン操作に対して認証と認可を行ってください。
• 識別子、列挙値、ページネーション、結果の上限を検証してください。
• シークレット、スタックトレース、永続化エンティティ、制限のない管理用ツールを公開しないでください。
• 実際の MCP クライアントを使用して、検出、無効な引数、認可、タイムアウト、シャットダウンをテストしてください。
• 2.0 のアノテーション例をコピーする前に、選択した Spring AI 1.x リリースのリリースノートを確認してください。

例

• examples/OrderMcpTools.java、examples/good-order-tools.java、examples/bad-order-tools.java を参照してください。

公式情報源

• Spring AI MCP の概要：https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html
• MCP Java SDK のリリース：https://github.com/modelcontextprotocol/java-sdk/releases
• MCP Java SDK 2.0 の移行ガイド：https://github.com/modelcontextprotocol/java-sdk/blob/main/MIGRATION-2.0.md

注意点

• エージェントが Spring AI 1.x の MCP SDK を上書きする — Spring AI BOM に SDK を管理させてください。
• エージェントが Spring AI 2.0 の org.springframework.ai.mcp.annotation インポートを 1.1 プロジェクトにコピーする — 1.1 では org.springaicommunity.mcp.annotation を使用し、1.0 には MCP アノテーションがありません。
• エージェントが、通常の @Component 上の @Tool メソッドは 1.x で MCP ツールとして表示されると想定する — ToolCallbackProvider Bean を通じて登録してください。
• エージェントが --spring.ai.mcp.server.transport=stdio を渡す — このようなプロパティはありません。Boot は警告なく無視します。spring.ai.mcp.server.stdio=true を使用してください。
• エージェントが SDK 単体のコードで削除済みの new CallToolResult(...) コンストラクターを使用する — ビルダーを使用してください。
• エージェントが stdio モードで stdout にログを出力する — ログを stderr またはファイルに出力し、バナーを無効にしてください。
• エージェントが同じツールオブジェクトを二重に登録する — 機能ごとにコールバックプロバイダーを 1 つにしてください。
• エージェントがエンティティや上限のないコレクションを公開する — 上限を設けた DTO コントラクトを返してください。