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 接続を使用することをお勧めします。
プロパティの構成
共通プロパティ
共通プロパティには spring.ai.mcp.client
という接頭辞が付きます。
プロパティ | 説明 | デフォルト値 |
---|---|---|
| MCP クライアントを有効 / 無効にする |
|
| MCP クライアントインスタンスの名前 (互換性チェックに使用) |
|
| MCP クライアントインスタンスのバージョン |
|
| 作成時にクライアントを初期化するかどうか |
|
| MCP クライアントリクエストのタイムアウト期間 |
|
| クライアント型(SYNC または ASYNC)。すべてのクライアントは同期または非同期のいずれかである必要があります。混在はサポートされていません |
|
| すべてのクライアントのルート変更通知を有効 / 無効にする |
|
| Spring AI のツール実行フレームワークとの MCP ツールコールバック統合を有効 / 無効にする |
|
Stdio トランスポートプロパティ
標準 I/O トランスポートのプロパティには spring.ai.mcp.client.stdio
というプレフィックスが付きます。
プロパティ | 説明 | デフォルト値 |
---|---|---|
| JSON 形式の MCP サーバー構成を含むリソース | - |
| 名前付き stdio 接続構成のマップ | - |
| MCP サーバーに対して実行するコマンド | - |
| コマンド引数のリスト | - |
| サーバープロセスの環境変数のマップ | - |
構成例:
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
というプレフィックスが付きます。
プロパティ | 説明 |
---|---|
| 名前付き SSE 接続構成のマップ |
| 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 クライアントの自動構成は、アプリケーションコンテキストで見つかったカスタマイザーを自動的に検出して適用します。
使用例
適切なスターター依存関係をプロジェクトに追加し、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
アプリケーション例
Brave ウェットサーチチャットボット [GitHub] (英語) - モデルコンテキストプロトコルを使用して Web 検索サーバーと対話するチャットボット。
デフォルトの MCP クライアントスターター [GitHub] (英語) - デフォルトの
spring-ai-starter-mcp-client
MCP クライアント Boot スターターを使用する簡単な例。WebFlux MCP クライアントスターター [GitHub] (英語) - MCP クライアント Boot スターター
spring-ai-starter-mcp-client-webflux
を使用する簡単な例。