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

概要

このスキルを使用して、Model Context Protocol (MCP) と LangChain4j の統合を設計・実装します。

主な関心事は以下の通りです：

• クリーンなツール、リソース、プロンプトの表面設計
• 適切なトランスポートとブートストラップモデルの選択
• エージェントまたはアプリケーションに公開する前に、安全でない機能をフィルタリング

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. 復元力とセキュリティコントロールを追加する

最小限の構成：

• 外部呼び出しの実行時間を制限する
• 各障害についてサーバーとツールの ID をログに記録する
• 外部リソースから返されたコンテンツをダウンストリームで使用する前にサニタイズする
• 許可リスト、修飾子、またはロールチェックの背後に特権ツールを隔離する

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: MCP ツールを LangChain4j AI サービスに公開し、フィルタリングを行う

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