MCP ツール設計とAI向け品質改善

MCP サーバーを配布対応する前に、ツールの入力品質ゲートをサーバー側へ寄せると、クライアント差異に左右されず品質を保ちやすい。特に知識保存系では、tool description、input schema、validation error に規約を埋め込み、prompt/resource は補助にする。ゲートは hard error、warning、normalized proposal に分けると、品質と UX を両立しやすい。

MCP ツールを設計するときは、HTTP API の CRUD 境界をそのまま露出するより、AI が安全に判断できる操作境界を優先する。read、write、delete は混ぜず、add/update の違いだけが迷いを生む場合は upsert 化する。一方で、異なる編集対象を巨大な manage ツールにまとめると入力設計の迷いが増えるため、対象ごとに意図ベースの少数ツールへ整理するのがよい。

低レベルの MCP Server API ではツール一覧に JSON Schema が必要な場合でも、各ツールに手書き JSON Schema を分散させず、zod schema を単一の定義元にして登録時に JSON Schema へ変換すると保守しやすい。全ツールに生成 schema が存在することを起動時に検証すれば、手書き fallback への戻りや schema 漏れを早期に検出できる。

MCPサーバーでツールを削除したか確認する際は、handlerディレクトリやtool.tsファイルの存在だけで判断せず、実際にListToolsへ渡す登録配列を一次情報として確認する。未登録のhandler、input schema、型、APIクライアント関数が残ると、公開ツールではなくても保守上は削除漏れに見えるため、登録元・schema・型・サービス関数をセットで棚卸しする。

MCPサーバーで全ツールのテストを追加する場合、各handlerの文言テストだけで網羅性を担保しようとすると保守負荷が高くなる。登録済みツール一覧を取得する関数を用意し、その一覧を基準にツール名、inputSchema生成、annotations、handlerファイルとの一致を検証すると、未登録ツールやschema漏れを低コストで検出できる。

MCPツールのAIからの使いやすさを改善する場合、descriptionの意図ベース化とstructuredContentの標準化は同時に設計するとよい。descriptionはAIがツール選択するための情報、structuredContentは実行結果を後続処理で扱うための情報なので、read系は安定したキーで返し、write系も成功時にsuccess/action/対象IDや対象データを返すと判断と連携が安定する。

MCPサーバーをディレクトリ掲載や複数AIクライアント向けに整える場合、tool description だけでなく inputSchema の説明、handler の成功・エラー文、README、setup 用スキル文面まで同じ言語に統一する。AI が読む schema とユーザーが見る text response の言語が混在すると、ツール選択や後続処理の一貫性が落ちるため、残存チェックをテストや grep で検出できるようにすると保守しやすい。