MCPカタログのツール設計：数十のエンドポイントから大規模な操作セットへ

要点：本エンジニアリングノートは、なぜUnifAPI が大規模な操作カタログを3つのMCPツールを通じて公開するのか、そしてなぜSkills がそのカタログの上にあるユーザー向けのレイヤーなのかを説明します。

UnifAPI の最初のMCPカタログは73個のエンドポイントを公開していました。現在のカタログは、ライブな公開データAPI横断の大規模な操作セットを、list_operations、get_operation、call_api という3つのMCPツールを通じて公開しています。それをうまくやるのは見た目より難しいものです。モデルは依然として正しい操作を発見し、スキーマを検査し、きれいな呼び出しを行わなければなりません。本記事は、命名、説明、パラメータスキーマ、そして数十の操作がライブになるまで現れない失敗モードについて、私たちが学んだことです。

なぜ大規模な操作セットがプロダクトを変えるのか

5〜10個の操作なら、MCPは「ただ動く」だけです。モデルがカタログを検索し、1つを選び、呼び出します。20〜30個になると、操作の命名が効いてきます。モデルが時折、惜しいけれど誤ったパスを選ぶのが見られるようになります。50個以上になると、カタログそのものが負荷を支える構造になります。

数はこれからも増え続けますが、プロダクトの教訓はすでに明確です。操作数が増えるにつれて、Skills はより重要になります。なぜなら、Skills はカタログのナビゲーションをタスクの結果の裏に隠すからです。

操作の命名：人間向けではなく、エージェント向けに読めるように

私たちの操作ラベルは1つのパターンに従います。プラットフォーム、動詞、名詞です。TikTok search videos、Reddit get post、LinkedIn search people。冗長ですが、曖昧さがありません。名前がコード識別子ではなく文の断片のように読めるため、モデルは正しい操作を選びます。

私たちは早期に、より短い規約（tiktok.search、reddit.post）を試し、近いペアでモデルが誤って選ぶのを目にしました（ユーザーが「search」と言ったとき、TikTok の「search」とReddit の「search」のどちらを選ぶか）。操作タイトルにプラットフォームの接頭辞を付けることで、モデルが推論しなくても曖昧さが解消されます。

説明こそがプロンプト

各操作の説明は1〜2文です。モデルは発見と検査の際にそれらを目にします。トークンに見合う2つのパターンがあります。最初の12語以内で動詞＋目的語の要約を先頭に置くこと、そして「use-when（いつ使うか）」のヒントで締めくくることです。

良い例："Search TikTok for videos matching a keyword or hashtag. Use when the user wants short-video discovery on a topic." 悪い例："This endpoint allows you to query the TikTok platform and retrieve a paginated list of videos that match a search term, optionally filtered by various parameters including ..." 後者は技術的にはより完全ですが、大規模なカタログでは誤ったトレードオフです。

パラメータスキーマ：フラットに保つ

call_api はフラットなオブジェクトを取ります。path、method、query、body です。必須フィールドを先に、オプションを後に置きます。理由はシンプルです。ネストしたJSONスキーマはモデルのツール呼び出しジェネレーターを混乱させます。私たちは、Claude があるパラメータを正しく理解しておきながら、スキーマが枝分かれして見えたために、それを誤ったネストレベルで出力するのを目にしてきました。

ある操作が本当に多態的な入力（キーワード「または」ハッシュタグで検索）を必要とするときには、get_operation が具体的な呼び出し例を示す必要があります。具体的な例は、枝分かれしたスキーマに毎回勝ります。

私たちが間違えたこと

名前を挙げる価値のある3つの間違いです。第一に、私たちはTwitter とReddit のそれぞれの検索操作にほぼ同一の説明を許してしまい、ユーザーが明示的に一方を求めたときにモデルがもう一方を選び始めました。各説明の最初の文でプラットフォームを明示的に名指しすることで修正しました。

第二に、しばらくの間、ソースのエラーメッセージをそのまま通していました。その一部はモデルが理解しないプラットフォーム固有の概念を参照しており、エージェントは私たちのエンベロープが隠していた問題を直そうとしてループに陥っていました。エラーを、unauthorized、validation_error、invalid_id、not_found、rate_limited、upstream_unavailable といった閉じた語彙に正規化することで修正しました。

第三に、いくつかの操作でページネーションの文書化が不十分で、モデルが先に進む代わりに、ループのたびにカーソル0から再呼び出ししていました。ページネーションの契約を、仕様だけでなく検査される操作データそのものの中に明記することで修正しました。

未解決の問い

どの時点でカタログを分割するのか。大規模な操作セットは今日のところ1つのMCPサーバーの裏に収まりますが、カタログはいずれ、モデルが必要なものだけをロードできるように、カテゴリフィルターやカテゴリ別のサーバーを必要とするかもしれません。

正しい答えはまだ分かりません。もしあなたが今日、UnifAPI の操作を大量に消費するエージェントを出荷しているなら、あなたの側で操作選択のレイテンシがどう見えるかをぜひ聞かせてください。hello@unifapi.com までご一報を。

次に読むべきもの

統合レスポンスエンベロープ - ツールの発見をレスポンス契約と対にします。

UnifAPI MCP を接続する - オペレーター向けのセットアップ経路を示します。

開発者リソース - 機械可読な仕様とドキュメントをまとめます。