langchain4j-mcp-server-patterns

LangChain4j MCP サーバーの実装パターン

概要

このスキルを使用して、LangChain4j で Model Context Protocol（MCP）との連携を設計、実装します。

主な検討事項は次のとおりです。

• 明確なツール、リソース、プロンプトのインターフェースを定義する
• 適切なトランスポートと起動方法を選択する
• エージェントやアプリケーションに公開する前に、安全でない機能をフィルタリングする

SKILL.md は実装の流れに焦点を当ててください。詳しい例や API レベルの詳細については、同梱のリファレンスを参照してください。

使用する場面

次の場合にこのスキルを使用します。

• ツール、リソース、プロンプトを公開する Java MCP サーバーを構築する
• LangChain4j を 1 つ以上の外部 MCP サーバーと連携させる
• Spring Boot アプリケーションに MCP サポートを組み込む
• テナント、ユーザーロール、実行時コンテキストに応じて利用可能なツールをフィルタリングする
• MCP とのやり取りに可観測性、レジリエンス、安全なエラー処理を追加する
• MCP 連携におけるプロンプトインジェクションや副作用のリスクを確認する

典型的なトリガーフレーズには、langchain4j mcp、java mcp server、mcp tool provider、spring boot mcp、connect langchain4j to mcp があります。

手順

1. コードを書く前に MCP のインターフェースを設計する

サーバーで公開する内容を決めます。

• 入力と副作用が明確なアクション向けのツール
• 読み取り専用または構造化データへのアクセス向けのリソース
• 再利用可能なテンプレートが実際に価値を加える場合に限り、プロンプトを使用する

名前は安定させ、説明は具体的にし、クライアントやモデルがすばやく理解できる程度にスキーマを小さく保ちます。

2. 責務を限定してプロバイダーを実装する

各責務には別々のクラスを使用します。

• 実行可能な関数を扱うツールプロバイダー
• 検出可能で読み取り可能なデータを扱うリソースプロバイダー
• 再利用可能なプロンプトテンプレートを扱うプロンプトプロバイダー

実行前に引数を検証し、入力が無効な場合や依存関係が利用できない場合は、明確なエラーメッセージを返します。

3. 意図を持ってトランスポートを選択する

次を使用します。

• ローカル連携、CLI ツール、サイドカープロセスには stdio
• リモートまたは共有サービスには HTTP または SSE

外部サーバーのバージョンを固定し、プロセスの起動、認証、監視方法を文書化します。

4. MCP を LangChain4j に慎重に接続する

LangChain4j から MCP サーバーを利用する場合は、次の点に注意します。

• アプリケーションの起動時にクライアントを初期化する
• 古いメタデータが許容される場合に限り、ツール一覧をキャッシュする
• 信頼レベル、環境、ユーザー権限に応じてツールをフィルタリングする
• 危険なツールについては、デフォルトですべて公開するのではなく、フェイルクローズする

5. レジリエンスとセキュリティ制御を追加する

最低限、次の対策を講じます。

• 外部呼び出しの実行時間に上限を設ける
• 各障害についてサーバーとツールの識別情報をログに記録する
• 外部リソースから返されたコンテンツを、後続処理で使用する前にサニタイズする
• 特権ツールを許可リスト、クオリファイア、ロールチェックで分離する

6. ワークフロー全体を検証する

リリース前に、次の点を確認します。

• 実際の MCP クライアントを使って、ツールの検出と呼び出しを検証する
• サーバーが切断された場合や応答が遅い場合の動作をテストする
• ツールのフィルタリングが意図した認可モデルに合致していることを確認する
• プロンプトやリソースから秘密情報や危険な指示が漏れないことを確認する

例

例 1：最小構成のツールプロバイダーと stdio サーバーの起動

class WeatherToolProvider implements ToolProvider {

    @Override
    public List<ToolSpecification> listTools() {
        return List.of(
            ToolSpecification.builder()
                .name("get_weather")
                .description("Return the current weather for a city")
                .inputSchema(Map.of(
                    "type", "object",
                    "properties", Map.of(
                        "city", Map.of("type", "string")
                    ),
                    "required", List.of("city")
                ))
                .build()
        );
    }

    @Override
    public String executeTool(String name, String arguments) {
        return weatherService.lookup(arguments);
    }
}

MCPServer server = MCPServer.builder()
    .server(new StdioServer.Builder())
    .addToolProvider(new WeatherToolProvider())
    .build();

server.start();

ローカルでのツール実行や、別のアプリケーションが起動するサイドカープロセスには、このパターンを使用します。

例 2：フィルタリングを適用して LangChain4j の AI サービスに MCP ツールを公開する

McpToolProvider toolProvider = McpToolProvider.builder()
    .mcpClients(mcpClients)
    .failIfOneServerFails(false)
    .filter((client, tool) -> !tool.name().startsWith("admin_"))
    .build();

Assistant assistant = AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .toolProvider(toolProvider)
    .build();

信頼境界を維持しながら LangChain4j で外部 MCP サーバーを利用する場合は、このパターンを使用します。

ベストプラクティス

• 各ツールの目的を絞り、決定的で、説明を明確にします。
• 自由形式の文字列引数より、明示的なスキーマを優先します。
• 読み取り専用のリソースと、副作用のあるツールを分離します。
• 特権ツールはデフォルトでフィルタリングするか、無効にします。
• 外部 MCP サーバーのパッケージまたはコンテナのバージョンを固定します。
• 接続失敗、呼び出しのレイテンシ、ツールのエラー率に関するメトリクスを記録します。
• プロトコルの詳細やフレームワーク固有の配線に関する詳しい情報は、SKILL.md を際限なく拡張するのではなく、references/ に保存します。

制約と警告

• 外部 MCP サーバーは信頼できない統合境界であり、悪意のあるコンテンツや誤解を招くコンテンツを公開する可能性があります。
• 検証せずに、リソースの生コンテンツを自律的なツール実行に直接渡さないでください。
• LangChain4j と MCP の一部の API は急速に変更されるため、プロジェクトですでに使用されているバージョンに合わせて、クラス名とビルダーを調整してください。
• 長時間実行されるツールや状態を保持するツールには、明示的なタイムアウト、キャンセル、クリーンアップの動作が必要です。
• Stdio ベースのサーバーには、プロセスのライフサイクル管理と堅牢なログ記録が必要です。

参考資料

• references/examples.md
• references/api-reference.md

関連スキル

• prompt-engineering
• spring-ai
• clean-architecture