MCP クライアント Boot スターター

Spring AI MCP (モデルコンテキストプロトコル) クライアント Boot スターターは、Spring Boot アプリケーションの MCP クライアント機能の自動構成を提供します。さまざまなトランスポートオプションを使用して、同期クライアント実装と非同期クライアント実装の両方をサポートします。

MCP クライアント Boot スターターは以下を提供します。

  • 複数のクライアントインスタンスの管理

  • 自動クライアント初期化 (有効な場合)

  • 複数の名前付きトランスポートのサポート

  • Spring AI のツール実行フレームワークとの統合

  • アプリケーションコンテキストが閉じられたときにリソースを自動的にクリーンアップする適切なライフサイクル管理

  • カスタマイザーによるカスタマイズ可能なクライアント作成

スターター

Spring AI 自動構成、スターターモジュールのアーティファクト名に大きな変更がありました。詳細については、アップグレードノートを参照してください。

標準 MCP クライアント

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

標準スターターは、STDIO (インプロセス) および / または SSE (リモート) トランスポートを介して 1 つ以上の MCP サーバーに同時に接続します。SSE 接続は、HttpClient ベースのトランスポート実装を使用します。MCP サーバーへの接続ごとに、新しい MCP クライアントインスタンスが作成されます。SYNC または ASYNC MCP クライアントのいずれかを選択できます (注: 同期クライアントと非同期クライアントを混在させることはできません)。本番環境の デプロイでは、spring-ai-starter-mcp-client-webflux を使用した WebFlux ベースの SSE 接続を使用することをお勧めします。

WebFlux クライアント

WebFlux スターターは標準スターターと同様の機能を提供しますが、WebFlux ベースの SSE トランスポート実装を使用します。

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

プロパティの構成

共通プロパティ

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

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

enabled

MCP クライアントを有効 / 無効にする

true

name

MCP クライアントインスタンスの名前 (互換性チェックに使用)

spring-ai-mcp-client

version

MCP クライアントインスタンスのバージョン

1.0.0

initialized

作成時にクライアントを初期化するかどうか

true

request-timeout

MCP クライアントリクエストのタイムアウト期間

20s

type

クライアント型(SYNC または ASYNC)。すべてのクライアントは同期または非同期のいずれかである必要があります。混在はサポートされていません

SYNC

root-change-notification

すべてのクライアントのルート変更通知を有効 / 無効にする

true

toolcallback.enabled

Spring AI のツール実行フレームワークとの MCP ツールコールバック統合を有効 / 無効にする

false

Stdio トランスポートプロパティ

標準 I/O トランスポートのプロパティには spring.ai.mcp.client.stdio というプレフィックスが付きます。

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

servers-configuration

JSON 形式の MCP サーバー構成を含むリソース

-

connections

名前付き stdio 接続構成のマップ

-

connections.[name].command

MCP サーバーに対して実行するコマンド

-

connections.[name].args

コマンド引数のリスト

-

connections.[name].env

サーバープロセスの環境変数のマップ

-

構成例:

spring:
  ai:
    mcp:
      client:
        stdio:
          root-change-notification: true
          connections:
            server1:
              command: /path/to/server
              args:
                - --port=8080
                - --mode=production
              env:
                API_KEY: your-api-key
                DEBUG: "true"

あるいは、Claude デスクトップ形式 (英語) を使用して外部 JSON ファイルを使用して stdio 接続を構成することもできます。

spring:
  ai:
    mcp:
      client:
        stdio:
          servers-configuration: classpath:mcp-servers.json

Claude デスクトップ形式は次のようになります。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

現在、Claude デスクトップフォーマットは STDIO 接続型のみをサポートしています。

SSE トランスポートプロパティ

サーバー送信イベント (SSE) トランスポートのプロパティには、spring.ai.mcp.client.sse というプレフィックスが付きます。

プロパティ 説明

connections

名前付き SSE 接続構成のマップ

connections.[name].url

MCP サーバーとの SSE 通信の URL エンドポイント

構成例:

spring:
  ai:
    mcp:
      client:
        sse:
          connections:
            server1:
              url: http://localhost:8080
            server2:
              url: http://otherserver:8081

機能

同期 / 非同期クライアントの種類

スターターは 2 種類のクライアントをサポートします。

  • 同期 - デフォルトのクライアント型。ブロッキング操作を伴う従来のリクエスト / レスポンスパターンに適しています

  • 非同期 - spring.ai.mcp.client.type=ASYNC を使用して構成された、ノンブロッキング操作を伴うリアクティブアプリケーションに適しています。

クライアントのカスタマイズ

自動構成は、コールバックインターフェースを通じて広範なクライアント仕様のカスタマイズ機能を提供します。これらのカスタマイザーを使用すると、リクエストのタイムアウトからイベント処理やメッセージ処理まで、MCP クライアントの動作のさまざまなアスペクトを構成できます。

カスタマイズの種類

次のカスタマイズオプションが利用可能です。

  • リクエスト構成 - カスタムリクエストタイムアウトを設定する

  • カスタムサンプリングハンドラー (英語) - サーバーがクライアント経由で LLM に LLM サンプリング (completions または generations) をリクエストするための標準化された方法。このフローにより、クライアントはモデルのアクセス、選択、権限を制御しながら、サーバーが AI 機能を活用できるようになります。サーバー API キーは必要ありません。

  • ファイルシステム(ルート)アクセス (英語) - クライアントがファイルシステム roots をサーバーに公開するための標準化された方法。ルートは、ファイルシステム内でサーバーが操作できる範囲の境界を定義し、サーバーがアクセスできるディレクトリとファイルを理解できるようにします。サーバーは、サポートしているクライアントからルートのリストをリクエストし、そのリストが変更されたときに通知を受け取ることができます。

  • イベントハンドラー - 特定のサーバーイベントが発生したときに通知されるクライアントのハンドラー:

    • ツール変更通知 - 利用可能なサーバーツールのリストが変更されたとき

    • リソース変更通知 - 利用可能なサーバーリソースのリストが変更されたとき。

    • プロンプト変更通知 - 利用可能なサーバープロンプトのリストが変更されたとき。

  • ログハンドラー (英語) - サーバーが構造化されたログメッセージをクライアントに送信する標準化された方法。クライアントは最小ログレベルを設定することでログの詳細度を制御できます

アプリケーションのニーズに応じて、同期クライアント用の McpSyncClientCustomizer または非同期クライアント用の McpAsyncClientCustomizer のいずれかを実装できます。

  • 同期化

  • 非同期

@Component
public class CustomMcpSyncClientCustomizer implements McpSyncClientCustomizer {
    @Override
    public void customize(String serverConfigurationName, McpClient.SyncSpec spec) {

        // Customize the request configuration
        spec.requestTimeout(Duration.ofSeconds(30));

        // Sets the root URIs that the server connecto this client can access.
        spec.roots(roots);

        // Sets a custom sampling handler for processing message creation requests.
        spec.sampling((CreateMessageRequest messageRequest) -> {
            // Handle sampling
            CreateMessageResult result = ...
            return result;
        });

        // Adds a consumer to be notified when the available tools change, such as tools
        // being added or removed.
        spec.toolsChangeConsumer((List<McpSchema.Tool> tools) -> {
            // Handle tools change
        });

        // Adds a consumer to be notified when the available resources change, such as resources
        // being added or removed.
        spec.resourcesChangeConsumer((List<McpSchema.Resource> resources) -> {
            // Handle resources change
        });

        // Adds a consumer to be notified when the available prompts change, such as prompts
        // being added or removed.
        spec.promptsChangeConsumer((List<McpSchema.Prompt> prompts) -> {
            // Handle prompts change
        });

        // Adds a consumer to be notified when logging messages are received from the server.
        spec.loggingConsumer((McpSchema.LoggingMessageNotification log) -> {
            // Handle log messages
        });
    }
}
@Component
public class CustomMcpAsyncClientCustomizer implements McpAsyncClientCustomizer {
    @Override
    public void customize(String serverConfigurationName, McpClient.AsyncSpec spec) {
        // Customize the async client configuration
        spec.requestTimeout(Duration.ofSeconds(30));
    }
}

serverConfigurationName パラメーターは、カスタマイザが適用され、MCP クライアントが作成されるサーバー構成の名前です。

MCP クライアントの自動構成は、アプリケーションコンテキストで見つかったカスタマイザーを自動的に検出して適用します。

輸送サポート

自動構成では、複数のトランスポート型がサポートされます。

  • 標準 I/O (スタジオ) (spring-ai-starter-mcp-client によって活性化される)

  • SSE HTTP (spring-ai-starter-mcp-client によって活性化される)

  • 南東 WebFlux (spring-ai-starter-mcp-client-webflux によって活性化される)

Spring AI との統合

スターターは、Spring AI のツール実行フレームワークと統合するツールコールバックを構成して、MCP ツールを AI インタラクションの一部として使用できるようにします。この統合はオプトインであり、spring.ai.mcp.client.toolcallback.enabled=true プロパティで明示的に有効にする必要があります。

使用例

適切なスターター依存関係をプロジェクトに追加し、application.properties または application.yml でクライアントを構成します。

spring:
  ai:
    mcp:
      client:
        enabled: true
        name: my-mcp-client
        version: 1.0.0
        request-timeout: 30s
        type: SYNC  # or ASYNC for reactive applications
        sse:
          connections:
            server1:
              url: http://localhost:8080
            server2:
              url: http://otherserver:8081
        stdio:
          root-change-notification: false
          connections:
            server1:
              command: /path/to/server
              args:
                - --port=8080
                - --mode=production
              env:
                API_KEY: your-api-key
                DEBUG: "true"

MCP クライアント Bean は自動的に構成され、注入に使用できるようになります。

@Autowired
private List<McpSyncClient> mcpSyncClients;  // For sync client

// OR

@Autowired
private List<McpAsyncClient> mcpAsyncClients;  // For async client

ツールコールバックが有効になっている場合、すべての MCP クライアントに登録された MCP ツールが ToolCallbackProvider インスタンスとして提供されます。

@Autowired
private SyncMcpToolCallbackProvider toolCallbackProvider;
ToolCallback[] toolCallbacks = toolCallbackProvider.getToolCallbacks();

ツールのコールバック機能はデフォルトでは無効になっており、次のように明示的に有効にする必要があることに注意してください。

spring:
  ai:
    mcp:
      client:
        toolcallback:
          enabled: true

アプリケーション例