モデルコンテキストプロトコル(MCP)
MCP クライアントは executeToolAsync(...) を使用して、スレッドをブロックせずにツールを実行できます。これは
非同期モードおよびリアクティブモードの AI サービスで使用されます。
ノンブロッキングとリアクティブを参照してください。
LangChain4j はモデルコンテキストプロトコル(MCP)をサポートしており、ツールを提供・実行できる MCP 準拠サーバーと通信できます。プロトコルの一般情報については MCP 公式サイトを参照してください。
Java で MCP サーバーを構築したい場合は? Java MCP サーバーの構築を参照してください。
プロトコルは 2 種類のトランスポートを規定しており、いずれもサポートされています。
- Streamable HTTP: クライアントが HTTP リクエストを送信し、サーバーは通常のレスポンスで応答するか、 時間をかけて複数のレスポンスを送る必要がある場合は SSE ストリームを開きます。
- stdio:クライアントは MCP サーバーをローカルのサブプロセスとして実行し、 標準入出力経由で直接通信できます。
仕様に加え、LangChain4j は WebSocket トランスポートも実装しています。このトランスポートは
標準化されておらず、現時点ではクライアント側が
Quarkus MCP Server 拡張の WebSocket トランスポートと
互換になるよう実装されています。WebSocket を公開していても
他のフレームワークで構築された MCP サーバーとの互換性は保証されません。
さらに LangChain4J は、コンテナイメージとして配布される stdio MCP サーバーを利用できる Docker stdio トランスポートもサポートしています。
チャットモデルや AI サービスに MCP サーバーが提供するツールを実行させるには、 MCP ツールプロバイダーのインスタンスを作成する必要があります。
MCP ツールプロバイダーの作成
MCP トランスポート
まず、MCP トランスポートのインスタンスが必要です。
stdio の場合 — この例では、NPM パッケージからサブプロセスとしてサーバーを起動する方法を示します:
McpTransport transport = StdioMcpTransport.builder()
.command(List.of("/usr/bin/npm", "exec", "@modelcontextprotocol/server-everything@0.6.2"))
.logEvents(true) // only if you want to see the traffic in the log
.build();
サーバーを特定のプロジェクトディレクトリで実行する必要がある場合は、stdio トランスポートのビルダーで
.workingDirectory(Path.of("/path/to/project")) を設定してください。
このディレクトリは、サーバーのサブプロセスの起動時と再起動時の両方に適用されます。
省略した場合、サブプロセスは現在のプロセスの作業ディレクトリを継承します。
Streamable HTTP トランスポートの場合は、サーバーの POST エンドポイントの URL を指定する必要があります:
McpTransport transport = StreamableHttpMcpTransport.builder()
.url("http://localhost:3001/mcp")
.logRequests(true) // if you want to see the traffic in the log
.logResponses(true)
.build();
注意:(レガシープロトコルのみ)Streamable HTTP トランスポートは、サーバー起点の通知やリクエストを受信するために、補助的な
GET ベースの SSE ストリームをオプションで開くことができます。ビルダーで .subsidiaryChannel(true) を指定して有効にします。
モダンプロトコル(2026-07-28)では、通知は代わりに subscriptions/listen 経由で受信されます。
デフォルトでは無効です。サーバーがサポートしていない場合、トランスポートは警告をログに記録し、そのチャネルなしで続行します。
確立後にストリームが切断された場合、トランスポートは自動的に再接続します(サーバーの retry 値に従い、デフォルトは 5 秒です)。
注意: サーバーから受信する 1 件のメッセージは、デフォルトで最大 20 MiB です。これは SSE ストリーム上の 1 つのイベントのデータ
(レスポンス内または補助チャネル上)、またはその他のレスポンスの本文全体(たとえば
JSON レスポンス)を指します。サーバーがそれより大きなメッセージを送信すると、トランスポートはストリームを閉じてメッセージを破棄します。
保留中のリクエストは失敗し、補助チャネルは再接続します。これにより、不正な動作をするサーバーがクライアントの
メモリを埋め尽くすのを 防ぎます。サイズは JSON テキストのものなので、base64 エンコードされる画像などのバイナリコンテンツは、
元のサイズより約 3 分の 1 大きくなります。上限を変更するには、ビルダーで設定します。たとえば
.maxMessageSize(50 * 1024 * 1024) で 50 MiB になります。
カスタム HTTP クライアント
デフォルトでは、ほかの HTTP クライアントがクラスパスにあっても、Streamable HTTP トランスポートは langchain4j-mcp が導入する JDK HTTP クライアント(langchain4j-http-client-jdk)を使用します。プロキシや TLS 設定を再利用する場合などは、ほかの HTTP クライアントの builder を渡せます。
McpTransport transport = StreamableHttpMcpTransport.builder()
.url("https://mcp.example.com/mcp")
.httpClientBuilder(OkHttpClient.builder()
.connectTimeout(Duration.ofSeconds(10))
.readTimeout(Duration.ZERO)) // no read timeout: MCP streams can stay idle for a long time
.build();
builder を渡さない場合、ほかのクライアントを使うのは次の二つの場合だけです。
- JVM システムプロパティ
langchain4j.http.clientBuilderFactoryでファクトリーを指定した場合。例:-Dlangchain4j.http.clientBuilderFactory=dev.langchain4j.http.client.okhttp.OkHttpClientBuilderFactory。application.propertiesに設定しても 効果はありません。このプロパティは HTTP クライアントを検出するすべてのモジュールに適用されます。 - 依存関係から
langchain4j-http-client-jdkを除外した場合。このときはクラスパスから選択します。
どちらの場合もトランスポートは接続タイムアウトを 60 秒に設定し(timeout(...) で変更可能)、長時間アイドル状態になり得る MCP ストリームのために読み取りタイムアウトを無効にします。
HTTP クライアントはストリーミングレスポンス(HttpClient.stream(request, parser))をサポートしている必要があります。
JDK、OkHttp、Apache のクライアントはサポートしています。Spring RestClient の統合は、
クラスパスに spring-webflux がある場合にのみサポートします。ストリーミングをサポートしないクライアントでは、
すべての MCP リクエストが失敗します。
独自の HTTP クライアントを使用する場合に知っておくべきこと:
- TLS、HTTP バージョン、リダイレクトは HTTP クライアントで設定します。トランスポートのオプション
sslContext(...)、setHttpVersion1_1()、followRedirects(true)は、デフォルトの JDK クライアントでのみ機能します。これらをhttpClientBuilder(...)、httpClient(...)、または上記の規則で選ばれた別のクライアントと組み合わせると、トランスポートの構築時に失敗します。 - リダイレクト: トランスポートはデフォルトではリダイレクトに従いませんが、OkHttp と Apache は従います。
リダイレクト時に、カスタムヘッダー(たとえば API キー)やリクエスト本文を
別のホストに送信してしまう可能性があります。リダイレクトが不要な場合は、クライアントで無効にしてください。たとえば
OkHttpClient.builder().okHttpClientBuilder(new okhttp3.OkHttpClient.Builder().followRedirects(false))です。 - タイムアウト: トランスポートの
timeout(...)は接続タイムアウトです。httpClientBuilder(...)を使う場合、 渡したビルダーに設定されます。使わない場合、クライアントは独自の接続タイムアウトを保持します。 トランスポートは読み取りタイムアウトを設定しないため、クライアント自身の読み取りタイムアウトが適用されます。MCP のレスポンスや 通知ストリームは長時間アイドル状態になることがあるため、読み取りタイムアウトを無効にするか、 長くしてください。OkHttp のデフォルトの読み取りタイムアウトはわずか 10 秒です。 - Executor: トランスポートの
executor(...)を設定した場合、レスポンスと通知はその上で処理されます。 補助チャネルの再接続のスケジューリングにも使用されます。HTTP クライアントは引き続き 自身のスレッドでリクエストを送信します。 - 遅いコールバック: デフォルトの JDK クライアントは、トランスポートが処理する速さでしかレスポンスを読み取らないため、
進捗や通知のコールバックが遅いと読み取りが一時停止します。独自の
JdkHttpClientビルダーを渡す場合は、同じ動作にするためにそれに対して.streamingBackpressure(true)を呼び出してください。 他のクライアントは 限られた数のイベントをバッファリングし、バッファがいっぱいになるとレスポンスを失敗させます。 - エラーレスポンス: サーバーがエラーステータス(たとえば期限切れのセッションに対する
404)で応答した場合、 JDK、OkHttp、Apache のクライアントはレスポンスヘッダーが届いた時点ですぐに報告します。 するとトランスポートは、ステータスコードを保持するHttpExceptionでリクエストを失敗させるか、 すぐに新しいセッションを開始します。他のクライアントは、レスポンス本文をすべて読み取った後にしか エラーを報告しない場合があります。プロトコル2026-07-28では、サーバーがクライアントエラーの ステータスと JSON 本文内の JSON-RPC エラーでリクエストを拒否することもあります。たとえば、知らないメソッドに対して エラーコード-32601とともに404を返す場合です。そのようなレスポンスでは、トランスポートは本文を読み取り、リクエストは サーバーの JSON-RPC エラーで失敗します。これはエラーがステータス200とともに返される場合と同じです。これは401、403、429を除くすべての4xxステータスに適用され、これら 3 つは常にそのステータスコードでリクエストを失敗させます。
トランスポートを閉じると、未完了のリクエストはキャンセルされます。httpClientBuilder(...) から構築されたクライアントは、
AutoCloseable を実装している場合(JDK クライアントは実装しています)、トランスポートとともに閉じられます。1 つのクラ イアントを
複数のトランスポートで共有するには、自分で構築して .httpClient(client) で渡してください。その場合トランスポートは
それを閉じることはなく、トランスポートに timeout(...) を設定することもできません。
呼び出しごとのコンテキスト
アプリケーションによっては、リクエストごとの情報をスレッドローカルのコンテキストに保持します。たとえばトレーシングスパン、 SLF4J MDC、セキュリティコンテキストなどです。Streamable HTTP トランスポートは、別のスレッドでリクエストを準備し、 レスポンスを処理するため、通常はこのコンテキストが失われてしまいます。
これを保持するには、captureContext() を実装した ExecutorProvider を登録します。詳細は
Executor の制御とコンテキストの伝播を参照してください。
するとトランスポートは、リクエストを送信した、または接続を初期化したスレッドのコンテキストをキャプチャします。そのコンテキストは、リクエストの準備中(
customHeaders(...) サプライヤーの呼び出しを含む)とレスポンスの処理中に復元されます。
このようなプロバイダーがない場合、何もキャプチャされません。
一部の処理は、あなたのリクエストによって開始されるものではありません。それらは接続の初期化時にキャプチャされ たコンテキストを使用します:
- 初期化後に送信される
notifications/initializedメッセージ - サーバーがセッションの期限切れ(404 レスポンス)を報告した後の自動再初期化
- 補助 SSE チャネルとその再接続
DefaultMcpClient は構築時に接続を初期化するため、単一のユーザーリクエストのコンテキストではなく、
接続全体にわたって有効なコンテキストで構築してください。
トランスポートは、自身の処理に対してのみコンテキストを復元します。カスタム HTTP クライアントは、自身が起動する すべてのスレッドにわたってそれを伝播させなければなりません。
WebSocket トランスポートの場合:
McpTransport transport = WebSocketMcpTransport.builder()
.url("ws://localhost:3001/mcp/ws")
.logResponses(true)
.logRequests(true)
.build();
注意: Streamable HTTP トランスポートと同様に、サーバーから受信する 1 件のメッセージはデフォルトで最大
20 MiB です。サーバーがそれより大きなメッセージを送信すると、トランスポートは接続を閉じ、保留中のすべての
リクエストが失敗します。上限を変更するには、ビルダーで設定します。たとえば .maxMessageSize(50 * 1024 * 1024) で 50 MiB になります。
Docker stdio トランスポートの場合は、まず pom.xml にモジュールを追加する必要があります:
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-mcp-docker</artifactId>
</dependency>
次に、Docker トランスポートを作成します:
McpTransport transport = DockerMcpTransport.builder()
.image("mcp/time")
.dockerHost("unix:///var/run/docker.sock")
.logEvents(true) // if you want to see the traffic in the log
.build();
MCP クライアント
トランスポートから MCP クライアントを作成するには:
McpClient mcpClient = DefaultMcpClient.builder()
.key("MyMCPClient")
.transport(transport)
.build();
クライアントキーは任意ですが、特に複数の MCP クライアントがあり、 それらを区別する必要がある場合は、設定すること をお勧めします。
クライアントの構築時にサーバーへ接続するため、サーバーに到達できないか応答が遅いと build() は例外をスローします。制限時間は initializationTimeout、プロトコルバージョンを自動検出する場合は protocolDetectionTimeout も適用されます(プロトコルバージョンを参照)。構築に失敗すると、クライアントはトランスポートを停止し、その試行で開始したサブプロセス、コンテナ、接続を解放します。トランスポートは引き続き呼び出し元が所有し、再試行または終了できます。構築に成功した場合のみクライアントがトランスポートを所有し、自身の終了時にそれを閉じます。カスタム McpTransport は start() で取得した資源を stop() で解放してください。デフォルトの stop() は何もしません。
プロトコルバージョン
MCP クライアントは、レガシープロトコル(2025-11-25)とモダンな ステートレスプロトコル(2026-07-28)の両方をサポートしています。デフォルトでは、クライアントはサーバーの プロトコルバージョンを自動検出し、サーバーがサポートしている場合は 2026-07-28 を優先します:
// Auto-detect (default behavior)
McpClient mcpClient = DefaultMcpClient.builder()
.transport(transport)
.build();
// Force modern protocol
McpClient mcpClient = DefaultMcpClient.builder()
.transport(transport)
.protocolVersion("2026-07-28")
.build();
// Force legacy protocol
McpClient mcpClient = DefaultMcpClient.builder()
.transport(transport)
.protocolVersion("2025-11-25")
.build();
検出には、クライアントの起動時に 1 回の追加往復が必要です。server/discover
リクエストを送信し、応答がエラーである場合、または protocolDetectionTimeout 内に
届かない場合は、そのサーバーをレガシーサーバーとして扱います。一部のエラーコードは異なる扱いになります。
サーバーが「サポートされないプロトコルバージョン」エラー(-32022)で応答した場合、クライアントは
そのエラーに列挙されたバージョンのいずれかで再度開始し、何も列挙されていなければ起動に失敗します。
サーバーが -32020 または -32021 で応答した場合、クライアントはそのエラーで起動に失敗します。
protocolDetectionTimeout のデフォルトは initializationTimeout(30 秒)です。サブプロセスとして
起動されたサーバーは、何かに応答できるようになる前に起動に時間がかかるため、早く
諦めすぎると、モダンなサーバーがレガシーサーバーのように見えてしまうからです。
エラー ではなく無応答が原因のフォールバックは警告としてログに記録されます。これは、
サーバーが誤って判断された可能性があるケースだからです。
McpClient mcpClient = DefaultMcpClient.builder()
.transport(transport)
.protocolDetectionTimeout(Duration.ofSeconds(5)) // servers you know answer quickly
.build();
protocolVersion を明示的に設定すると、検出が完全にスキップされます。
サーバーがどのプロトコルバージョンを話すかをすでに知っている場合は、そうする価値があります。また、
サーバーが認識しないメソッドを受け取ったときに不適切に反応する場合の回避策にもなります。古い MCP サーバーの
実装の中には、エラーで応答する代わりに、未知のリクエストで終了してしまうものがあります。
MCP ツール プロバイダー
最後に、クライアントから MCP ツールプロバイダーを作成します:
McpToolProvider toolProvider = McpToolProvider.builder()
.mcpClients(mcpClient)
.build();
1 つの MCP ツールプロバイダーは、複数のクライアントを同時に使用できる点に注意してください。
これを利用する場合は、特定のサーバーからのツール取得が失敗した場合の
ツールプロバイダーの動作も指定できます。これは
builder.failIfOneServerFails(boolean) メソッドで行います。デフォルトは false で、
ツールプロバイダーは 1 つのサーバーからのエラーを無視し、
他のサーバーで続行します。true に設定すると、いずれかの
サーバーで失敗した場合に、ツールプロバイダーが例外をスローします。
さらに、MCP サーバーは数十個のツールを提供することが多いのに対し、特定の AI サービスが
必要とするのはそのうちのわずかです。これは、不要なツールの使用を防ぐためと、
ハルシネーションの可能性を減らすためです。McpToolProvider では、
次のようにツールを名前でフィルタリングできます:
McpToolProvider toolProvider = McpToolProvider.builder()
.mcpClients(mcpClient)
.filterToolNames("get_issue", "get_issue_comments", "list_issues")
.build();
こうすると、この ToolProvider で構成された AI サービスは、
言及された 3 つのツールだけを使用でき、既存の issue を読み取れますが、
新しい issue を作成することはできません。より一般的には、ToolProvider では
BiPredicate<McpClient, ToolSpecification> を通じてツールをフィルタリングできます。これは、
複数の MCP クライアントが同じ名前で衝突するツールを公開している場合にも役立ちます。
たとえば、次の ToolProvider は 2 つの MCP クライアントからツールを取得しますが、
どちらにも echoInteger という名前のツールがあるため、キーが numeric-mcp の
MCP クライアントのものだけを取得します:
McpToolProvider toolProvider = McpToolProvider.builder()
.mcpClients(mcpClient1, mcpClient2)
.filter((mcpClient, tool) ->
!tool.name().startsWith("echoInteger") ||
mcpClient.key().equals("numeric-mcp"))
.build();
同じ McpToolProvider ビルダーで filter メソッドを複数回呼び出すと、
それらすべてのフィルターの論理積(AND)になる点に注意してください。
アプリケーションが実行時に MCP サーバーへ接続したり切断したりできるように、
既存の McpToolProvider インスタンスに対してクライアントやフィルターを動的に追加・削除することもできます。
ツールプロバイダーを AI サービスにバインドするには、AI サービスビルダーの toolProvider メソッドを使用するだけです:
Bot bot = AiServices.builder(Bot.class)
.chatModel(model)
.toolProvider(toolProvider)
.build();
あるいは、Map<ToolSpecification, ToolExecutor> を使ってツールを 提供することもできます。
Map<ToolSpecification, ToolExecutor> tools = mcpClient.listTools().stream().collect(Collectors.toMap(
tool -> tool,
tool -> new McpToolExecutor(mcpClient)
));
ツールを AI サービスにバインドするには、AI サービスビルダーの tools メソッドを使用するだけです:
Bot bot = AiServices.builder(Bot.class)
.chatModel(model)
.tools(tools)
.build();
LangChain4j のツールサポートの詳細については、こちらをご覧ください。
MCP ツール名のマッピング
複数の MCP サーバーを使用していて、それらが衝突する名前のツールを公開している場合(または単に不適切に選ばれた名前を
調整したい場合)、ツール名マッピング関数を適用すると便利です。
これは、McpToolProvider の作成時に BiFunction<McpClient, ToolSpecification, String> を指定することで行えます。
例:
McpToolProvider toolProvider = McpToolProvider.builder()
.mcpClients(mcpClient1, mcpClient2)
.toolNameMapper((client, toolSpec) -> {
// Prefix all tool names with the name of the MCP client and an underscore
return client.key() + "_" + toolSpec.name();
})
.build();
この後、ツールプロバイダーが返す ToolSpecification オブジェクトにはマッピング後の(論理)名が含まれますが、
生成される ToolExecutor オブジェクトは、ツールを呼び出す際にサーバーへ元の(物理)名を渡すように固定されます。
MCP ツール仕様のマッピング
上記の MCP ツールのマッピングと同様に、ToolSpecification 全体をマッピングすることもできます:
McpToolProvider toolProvider = McpToolProvider.builder()
.mcpClients(mcpClient)
.toolSpecificationMapper((client, toolSpec) -> {
// Prefix all tool names with "myprefix_" and convert the description to uppercase
return toolSpec.toBuilder()
.name("myprefix_" + toolSpec.name())
.description(toolSpec.description().toUpperCase())
.build();
})
.build();
MCP ツールのメタデータ
MCP プロトコルでは、サーバーが各ツールに対して、アノテーションの形式で、またはツール定義の _meta フィールドで、
追加のメタデータを提供できます。
LangChain4j は、これらすべてのメタデータを ToolSpecification.metadata() メソッド内に格納されたマップを通じて公開します。
アノテーションは、dev.langchain4j.mcp.client.McpToolMetadataKeys クラスの定数として見つかる
キーを使ってマップに格納されます。
_meta フィールドの内容は元のキーを使って格納され、JSON 値は
ネストされたマップとしてシリアライズされます。
MCP ツール定義に直接存在する title フィールドは、アノテーションから取得される title と区別するために、
メタデータマップの McpToolMetadataKeys.TITLE キーで公開されます。アノテーションから取得される title は
McpToolMetadataKeys.ANNOTATION_TITLE キーで公開されます。
ツールにアイコンがある場合、それらはメタデータマップの McpToolMetadataKeys.ICONS キーで公開されます。
MCP ツール結果のメタデータ
実際の結果に加えて、MCP サーバーはツール呼び出しのレスポンスに _meta オブジェクトを添付できます。
これは、アプリケーションには必要だが LLM には不要なデータ、たとえばツールが作成した
レコードの識別子や、UI でレンダリングすべきウィジェットなどに便利です。
_meta オブジェクトのエントリは、ToolExecutionResult.attributes() を通じて、元の
キーのまま、JSON 値をネストされたマップに変換して公開されます。これらが LLM に送信されることはありません。
io.modelcontextprotocol/serverInfo のような MCP 仕様で予約されているキーは、
ツール結果ではなくプロトコルのやり取りを記述するものなので、スキップされます。
クライアントでツールを直接呼び出す場合、属性は常に利用できます:
ToolExecutionResult result = mcpClient.executeTool(toolExecutionRequest);
Object widget = result.attributes().get("example.org/widget");
AI サービスによってツールが呼び出される場合、属性はデフォルトで破棄されます。
そのサイズと内容は MCP サーバーによって制御されるためです。
保持するには、ツールプロバイダーで returnToolResultAttributes を有効にします:
McpToolProvider toolProvider = McpToolProvider.builder()
.mcpClients(mcpClient)
.returnToolResultAttributes(true)
.build();
その後、結果のツール実行から読み取れます:
interface Assistant {
Result<String> chat(String userMessage);
}
Result<String> result = assistant.chat("What is the weather in Munich?");
for (ToolExecution toolExecution : result.toolExecutions()) {
Object widget = toolExecution.attributes().get("example.org/widget");
}
属性は ToolExecutionResultMessage にも伝播されるため、
メッセージとともにチャットメモリに保存されます。
チャットメモリを永続化する場合はこの点に留意してください。詳細は
ツール結果の属性を参照してください。
ツールがアプリケーションレベルのエラー(ツール結果の "isError": true)を返した場合、呼び出しは
ToolExecutionException のサブクラスである McpApplicationErrorException で終了し、失敗したレスポンスの _meta は
利用できません。それでも McpClientListener.afterExecuteTool() には渡され、そこでは完全な
生のレスポンスを受け取ります。
アプリケ ーションレベルのエラーは、MCP サーバーがツールが成功しなかったことをモデルに伝える方法であるため、そのテキストは
LLM 向けに書かれています。そのため McpApplicationErrorException は ToolErrorVisibleToLlm を実装しています。これを
尊重するツール実行エラーハンドラー(ToolExecutionErrorHandler.failInvocationUnlessVisibleToLlm() など)を使うと、
サーバーのテキストが LLM に送信され、LLM はそれに反応できます。そのハンドラーでは、プロトコルエラー(呼び出し自体が
うまくいかなかったことを意味します)は AI サービスの呼び出しを失敗させ、テキストのない
アプリケーションレベルのエラー(単なる ToolExecutionException)も同様です。
エラー処理を参照してください。
HTTP ヘッダーとして運ばれるツールパラメータ
Streamable HTTP 上の 2026-07-28 プロトコルでは、サーバーは、選択したツールの引数をリクエスト本文に加えて
HTTP ヘッダーとして送信するよう要求でき、これによりプロキシや
ゲートウェイは呼び出しを解析せずにルーティングや認可ができます。サーバーは、ツールの入力スキーマで
x-mcp-header を使ってそのようなパラメータを示します:
{
"name": "query_database",
"inputSchema": {
"type": "object",
"properties": {
"tenant": { "type": "string", "x-mcp-header": "X-Tenant-Id" },
"sql": { "type": "string" }
}
}
}
ツールが呼び出されると、クライアントは tenant の値をリクエスト本文と
Mcp-Param-X-Tenant-Id HTTP ヘッダーの両方で送信します。これは自動的に行われ、
設定は不要です。ヘッダーに入れるのが安全でない値、たとえば非 ASCII
文字を含む値は、プロトコルの要求に従って Base64 エンコードされます。
この方法で示せるのは string、integer、boolean のパラメータのみで、ヘッダー名は
有効な HTTP トークンでなければならず、同じヘッダー名を 2 回要求することはできません。定義が
これらのルールに違反するツールは listTools() から除外され、警告がログに記録されます。クライアントには、
そのような呼び出しがどのようにサーバーに届くことを意図していたのかがわからないためです。
ヘッダー名はツール定義から読み取られるため、クライアントはそれらを送信する前に
ツール一覧を把握し ている必要があります。一度もツールを一覧表示していないクライアントで executeTool() を呼び出すと、
ヘッダーは省略され、警告がログに記録されます。先に listTools() を呼び出してください。ツールプロバイダーは
これを自動的に行います。
_meta フィールドの提供
MCP プロトコルでは、クライアントがサーバーに送信するすべてのリクエストと通知の params に _meta オブジェクトを
添付できます。これは、
OpenTelemetry のトレースコンテキスト、カスタムのアプリケーションメタデータ、またはサーバーが必要とする可能性のある
その他の帯域外情報を渡すために使用できます。
_meta フィールドを提供するには、クライアントビルダーに McpMetaSupplier を登録します。
サプライヤーはすべてのリクエストまたは通知の前に呼び出され、返された
マップが params._meta に配置されます。HTTP ヘッダーとは異なり、これは
すべてのトランスポート(stdio、HTTP、WebSocket)で機能します。
McpClient mcpClient = DefaultMcpClient.builder()
.transport(transport)
.metaSupplier(context -> Map.of(
"traceparent", "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01",
"custom-key", "custom-value"))
.build();
サプライヤーは McpCallContext(null 許容)を受け取ります。これには、
送信されるメッセージと、該当する場合はそれをトリガーした
AI サービス呼び出しの InvocationContext が含まれます。これにより、サプライヤーは
どの操作が実行されているかに基づいて
メタデータを変えることができます。
ロギング
MCP プロトコルは、サーバーがクライアントにログメッセージを送信する方法も定義しています。
デフォルトでは、クライアントはこれらのログ
メッセージを変換し、SLF4J ロガーを使って記録します。この
動作を変更したい場合は、受信したログメッセージのコールバックとして機能する
dev.langchain4j.mcp.client.logging.McpLogMessageHandler という
インターフェースがあります。独自の
McpLogMessageHandler 実装を作成した場合は、MCP クライアントビルダーに渡します:
McpClient mcpClient = new DefaultMcpClient.Builder()
.transport(transport)
.logHandler(new MyLogMessageHandler())
.build();
MCP リスナー
MCP クライアントは、クラ イアントの存続期間中に発生するイベントを
リッスンできるリスナーをサポートしています。インターフェース
dev.langchain4j.mcp.client.McpClientListener が、リスナー実装の
基盤となります。1 つのクライアントに複数のリスナーを登録でき、
それらはすべて、ツール呼び出し、プロンプトのレンダリング、リソースへのアクセスのたびに、その前後で呼び出されます。リスナーの呼び出し時には、対応する
McpCallContext が注入されます。このオブジェクトには、
サーバーに送信される実際の MCP メッセージと、該当する場合の
InvocationContext のインスタンス(この
呼び出しが AI サービス呼び出しの一部として行われる場合のみ)が含まれます。
リスナーは 1 つずつ、またはまとめて追加できます:
McpClient mcpClient = DefaultMcpClient.builder()
.transport(transport)
.addListener(new MyFirstListener())
.addListener(new MySecondListener())
.addListeners(List.of(new MyThirdListener(), new MyFourthListener()))
.build();
リソース
リソースを扱う方法は 2 つあります。アプリケーションが MCP クライアントの リソース関連メソッドを呼び出してプログラムからリソースにアクセスするか、合成ツール(リソースの一覧を取得するツールと リソースの内容を取得するツールの 2 つ)を介してリソースを LLM 呼び出しに自動的に公開し、チャットモデルが自らリソースを参照できるようにするオプションがあります。
プログラムによるリソースアクセス
サーバー上の MCP リソースの一覧を取得するには、
client.listResources() を使用します。リソーステンプレートの場合は client.listResourceTemplates() を使用します。
これは McpResource オブジェクトのリスト(またはそれぞれ McpResourceTemplate)を返します。これらには
リソースのメタデータ、最も重要なものとして URI が含まれます。
リソースの実際の内容を取得するには、リソースの URI を指定して client.readResource(uri) を使用します。
これは McpReadResourceResult を返し、そこには McpResourceContents オブジェクトのリストが含まれます(1 つの URI に複数のリソースコンテンツがある場合があり、
たとえば URI がディレクトリを表す場合などです)。各 McpResourceContents オブジェクトは 、
バイナリ blob(McpBlobResourceContents)またはテキスト(McpTextResourceContents)のいずれかを表します。
合成ツールによるリソースの自動公開
McpToolProvider を構築する際に、ビルダーで McpResourcesAsToolsPresenter インスタンスを設定すると、
MCP ツールプロバイダーは provideTools メソッドの結果に 2 つの合成ツールを自動的に追加します。
これは、バックエンドの MCP サーバーがサポートする「通常の」ツールと並んで追加されます。1 つのツールはリソースの
一覧を取得するため、もう 1 つは特定のリソースを取得するためのものです。LangChain4j は、
これら 2 つのツールを追加する DefaultMcpResourcesAsToolsPresenter という名前のデフォルト実装を提供しています:
注意: このセクションの残りの部分では DefaultMcpResourcesAsToolsPresenter について説明します。異なる動作をする
独自の実装を差し込むこともできます。
list_resources:バックエンドの MCP サーバーが公開するすべてのリソースを一覧表示します。このツールは引数を取りません。get_resource:リソースの内容を読み取ります。このツールは、リソースを一意に識別する 2 つの引数を取ります: MCP サーバー名と URI です。
list_resources の出力は、次のような JSON 配列 です:
[ {
"mcpServer" : "alice",
"uri" : "file:///info",
"uriTemplate" : null,
"name" : "basicInfo",
"description" : "Basic information about Alice",
"mimeType" : "text/plain"
}, {
"mcpServer" : "bob",
"uri" : "file:///info",
"uriTemplate" : null,
"name" : "basicInfo",
"description" : "Basic information about Bob",
"mimeType" : "text/plain"
} ]
この配列内の各ドキュメントは 1 つのリソースを表します。各リソースは uri と mcpServer の組み合わせで識別され、
mcpServer は MCP クライアントの作成時に割り当てられた key の値です(DefaultMcpClient.Builder#key を参照)。
チャットモデルが list_resources ツールを呼び出すと、
このリソースの一覧を受け取り、その後 read_resource を呼び出すことを決定できます。list_resources
と get_resource ツールのデフォルトの説明は、ほとんどの状況で LLM にその使い方を説明するのに十分なはずです。ただし、
これらのツールとその引数の説明をカスタマイズする必要がある 場合は、
DefaultMcpResourcesAsToolsPresenter.Builder のメソッドを使ってオーバーライドします。
リソースのサブスクリプション
MCP プロトコルはリソースのサブスクリプションをサポートしており、 サーバー上のリソースが変更されたときにクライアントが通知を受け取れます。
レガシープロトコル(2025-11-25)
特定のリソースの更新をサブスクライブするには、client.subscribeToResource(uri) を使用します。
サーバーがリソースを更新すると、notifications/resources/updated 通知が送信されます。
これらの通知を処理するには、onResourceUpdated ビルダーメソッドでコールバックを登録します:
McpClient mcpClient = DefaultMcpClient.builder()
.transport(transport)
.onResourceUpdated((client, uri) -> {
// re-read the updated resource
McpReadResourceResult result = client.readResource(uri);
// process the updated contents...
})
.build();
// subscribe to a resource
mcpClient.subscribeToResource("file:///status");
// later, unsubscribe
mcpClient.unsubscribeFromResource("file:///status");
モダンプロトコル(2026-07-28)
モダンプロトコルでは、複数の URI を受け取り
サブスクリプション ID を返す subscribeToResources を使用します:
long subId = mcpClient.subscribeToResources(List.of("file:///status", "file:///config"));
// later, unsubscribe using the subscription ID
mcpClient.unsubscribeFromResources(subId);
サーバーは、サブスクリプション上で何かを送信する前に、それを確認しなければなりません。そのため、
subscribeToResources はその確認が届くまでブロックします。サーバーがサブスクリプションを拒否した場合、
要求された URI を拒否した場合、または無応答の場合、何も配信しないサブスクリプション ID を
返す代わりに、呼び出しは例外をスローします。クライアントが確認を待つ時間は
resourcesTimeout で制御します:
McpClient mcpClient = DefaultMcpClient.builder()
.transport(transport)
.resourcesTimeout(Duration.ofSeconds(10)) // default: 60 seconds
.build();
呼び出しはブロックするため、onResourceUpdated コールバックの内部から呼び出さないでください。
それらのコールバックは、サーバーからメッセージを読み取るスレッド上で実行されますが、これは確認を配信しなければならない
スレッドと同じだからです。
リスト変更通知(ツールリスト、プロンプトリスト、リソースリストの変更)については、 クライアントはデフォルトで自動的にサブスクライブします。これはビルダーの フラグで制御できます:
McpClient mcpClient = DefaultMcpClient.builder()
.transport(transport)
.subscribeToToolListChanges(true) // default: true
.subscribeToPromptListChanges(true) // default: true
.subscribeToResourceListChanges(true) // default: true
.build();
プロンプト
サーバーから MCP プロンプトの一覧を取得するには、
client.listPrompts() を使用します。このメソッドは McpPrompt の List を返します。McpPrompt には
プロンプトの名前と引数に関する情報が含まれます。
プロ ンプトの実際の内容をレンダリングするには、client.getPrompt(name, arguments) を使用します。レンダリングされたプロンプトには 1 つ以上の
メッセージが含まれ、これらは McpPromptMessage オブジェクトとして表されます。各 McpPromptMessage には、メッセージのロール(user、assistant など)
とメッセージの実際の内容が含まれます。現時点でサポートされているメッセージコンテンツタイプは、
McpTextContent、McpImageContent、McpEmbeddedResource です。
McpPromptMessage.toChatMessage() を使うと、それを LangChain4j コア API の汎用的な
dev.langchain4j.data.message.ChatMessage に変換できます。ただし、すべてのケースで可能なわけではありません。たとえば、
プロンプトメッセージの role が assistant でテキスト以外のコンテンツを含む場合は、例外がスローされます。
バイナリ blob コンテンツを含むメッセージの ChatMessage への変換は、ロールにかかわらずサポートされていません。
Docker 経由での GitHub MCP サーバーの利用
次に、モデルコンテキストプロトコル(MCP)を使って、AI モデルと外部ツールを標準化された方法で橋渡しする方法を見てみましょう。 次の例では、LangChain4j の MCP クライアントを通じて GitHub とやり取りし、公開 GitHub リポジトリの最新 のコミットを取得して要約します。 そのために、車輪の再発明をする必要はありません。MCP の GitHub リポジトリにある既存の GitHub MCP サーバー実装を使用できます。
アイデアは、Docker でローカル実行されている GitHub MCP サーバーに接続して最新のコミットを取得・要約する Java アプリケーションを構築することです。 この例では、MCP の stdio トランスポート機構を使って、Java アプリケーションと GitHub MCP サーバーの間で通信します。
Docker での GitHub MCP サーバーのパッケージングと実行
GitHub とやり取りするには、まず Docker で GitHub MCP サーバーをセットアップする必要があります。 GitHub MCP サーバーは、モデルコンテキストプロトコルを通じて GitHub とやり取りするための標準化されたインターフェースを提供します。 ファイル操作、リポジトリ管理、検索機能を可能にします。
GitHub MCP サーバーの Docker イメージをビルドするには、リポジトリをクローンするかコードをダウンロードして、MCP servers の GitHub リポジトリからコードを取得する必要があります。 その後、ルートディレクトリに移動して次の Docker コマンドを実行します:
docker build -t mcp/github -f src/github/Dockerfile .
Dockerfile は必要な環境をセットアップし、GitHub MCP サーバー実装をインストールします。
ビルドが完了すると、イメージは mcp/github としてローカルで利用可能になります。
docker image ls
REPOSITORY TAG IMAGE ID SIZE
mcp/github latest b141704170b1 173MB
ツールプロバイダーの開発
LangChain4j を使って GitHub MCP サーバーに接続する McpGithubToolsExample という Java クラスを作成しましょう。このクラスは次のことを行います:
- Docker コンテナで GitHub MCP サーバーを起動します(
dockerコマンドは/usr/local/bin/dockerにあります) - stdio トランスポートを使って接続を確立します
- LLM を使って LangChain4j の GitHub リポジトリの直近 3 件のコミットを要約します
注意:以下のコードでは、GitHub トークンを環境変数
GITHUB_PERSONAL_ACCESS_TOKENで渡しています。ただし、認証が不要な公開リポジトリに対する一部の操作では、これは任意です。
実装は次のとおりです:
public static void main(String[] args) throws Exception {
ChatModel model = OpenAiChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.logRequests(true)
.logResponses(true)
.build();
McpTransport transport = new StdioMcpTransport.Builder()
.command(List.of("/usr/local/bin/docker", "run", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "-i", "mcp/github"))
.logEvents(true)
.build();
McpClient mcpClient = new DefaultMcpClient.Builder()
.transport(transport)
.build();
ToolProvider toolProvider = McpToolProvider.builder()
.mcpClients(List.of(mcpClient))
.build();
Bot bot = AiServices.builder(Bot.class)
.chatModel(model)
.toolProvider(toolProvider)
.build();
try {
String response = bot.chat("Summarize the last 3 commits of the LangChain4j GitHub repository");
System.out.println("RESPONSE: " + response);
} finally {
mcpClient.close();
}
}
すべての LLM がツールを同じようによくサポートしているわけではありません。 ツールを理解し、選択し、正しく使用する能力は、特定のモデルとその機能に大きく依存します。 ツールをまったくサポートしないモデルもあれば、慎重なプロンプトエンジニアリングや 追加のシステム指示が必要なモデルもあります。
注意:この例は Docker を使用しているため、
/usr/local/bin/dockerにある Docker コマンドを実行します(パスはお使いの OS に合わせて変更してください)。Docker の代わりに Podman を使用したい場合は、コマンドを適宜変更してください。
コードの実行
例を実行するには、システムで Docker が起動して動作していることを確認してください。
また、環境変数 OPENAI_API_KEY に OpenAI API キーを設定してください。
その後、Java アプリケーションを実行します。LangChain4j の GitHub リポジトリの直近 3 件のコミットを要約したレスポンスが、たとえば次のように得られるはずです:
Here are the summaries of the last three commits in the LangChain4j GitHub repository:
1. **Commit [36951f9](https://github.com/langchain4j/langchain4j/commit/36951f9649c1beacd8b9fc2d910a2e23223e0d93)** (Date: 2025-02-05)
- **Author:** Dmytro Liubarskyi
- **Message:** Updated to `upload-pages-artifact@v3`.
- **Details:** This commit updates the GitHub Action used for uploading pages artifacts to version 3.
2. **Commit [6fcd19f](https://github.com/langchain4j/langchain4j/commit/6fcd19f50c8393729a0878d6125b0bb1967ac055)** (Date: 2025-02-05)
- **Author:** Dmytro Liubarskyi
- **Message:** Updated to `checkout@v4`, `deploy-pages@v4`, and `upload-pages-artifact@v4`.
- **Details:** This commit updates multiple GitHub Actions to their version 4.
3. **Commit [2e74049](https://github.com/langchain4j/langchain4j/commit/2e740495d2aa0f16ef1c05cfcc76f91aef6f6599)** (Date: 2025-02-05)
- **Author:** Dmytro Liubarskyi
- **Message:** Updated to `setup-node@v4` and `configure-pages@v4`.
- **Details:** This commit updates the `setup-node` and `configure-pages` GitHub Actions to version 4.
All commits were made by the same author, Dmytro Liubarskyi, on the same day, focusing on updating various GitHub Actions to newer versions.
AI サービスなしでの MCP の利用
前の例では、高レベルの AI Services API で MCP を使用する方法を示しました。ただし、低レベル API を通じて MCP を使用することもできます。
構築した DefaultMcpClient インスタンスを手動で使用して、サーバーに対してコマンドを実行できます。いくつかの例:
// obtain a list of tools from the server
List<ToolSpecification> toolSpecifications = mcpClient.listTools();
// build and execute a ChatRequest that has access to the MCP tools
ChatRequest chatRequest = ChatRequest.builder()
.messages(UserMessage.from("What will the weather be like in London tomorrow?"))
.toolSpecifications(toolSpecifications)
.build();
ChatResponse response = chatModel.chat(chatRequest);
AiMessage aiMessage = response.aiMessage();
// if the LLM requested to invoke a tool, forward it to the MCP server
if(aiMessage.hasToolExecutionRequests()) {
for (ToolExecutionRequest req : aiMessage.toolExecutionRequests()) {
String resultString = mcpClient.executeTool(req);
// prepare the result for adding it to the memory for the next ChatRequest...
ToolExecutionResultMessage resultMessage = ToolExecutionResultMessage.from(req.id(), req.name(), resultString);
}
}