126個のMCPツールを構築。しかし、エージェントにとっての最適解ではない

これは、APIテストとAPIライフサイクル管理のためのコマンドラインツールであるApidog CLIをApidogがどのように開発したかを共有する10部構成のシリーズです。順に読むか、興味のある記事に直接ジャンプしてください：

MCPが業界のホットスポットとなったとき、私たちは126個の生成ツールを備えた完全なMCPサーバーを構築しました。何がうまくいかなかったのか、そしてなぜツールが多いことがより良いエージェントの有効化を意味しないのかを説明します。

MCPの誇大宣伝

2025年初頭、MCP（Model Context Protocol）は業界のホットスポットとなりました。

Anthropicがこのプロトコルを推進し、Cursor、Claude Code、Antigravity、様々なAgent IDE、そして数多くのSaaS製品がそれに続きました。このプロトコルは、AIエージェントが外部ツールやデータソースに接続するための標準化された方法を約束しました。

その期間中、APIを持つほぼすべての製品が同じ質問をされました。

「MCPに対応していますか？」

Apidogにとって、この選択は特に自然に思えました。

なぜMCPが解決策のように見えたのか

Apidog自体は、API開発機能の包括的なセットを蓄積していました：

• APIドキュメント
• スキーマ定義
• モックサーバー
• テストケース
• テストシナリオ
• テストスイート
• テストレポート
• インポート/エクスポートワークフロー
• ブランチコラボレーション
• その他多数

もしエージェントが新しいソフトウェアのエントリポイント、つまりユーザーが製品と対話する新しい方法となるのであれば、これらの機能をMCPを通じて公開することは、必要なチケットを切ることのように思われました。

私たちは、自社の機能をMCPツールとしてパッケージ化できれば、エージェントが以下のことができるようになると信じていました：

• APIドキュメントの照会
• テストケースの作成
• テストシナリオの実行
• プロジェクトデータのインポート/エクスポート
• 環境と変数の管理
• ブランチ間でのコラボレーション

その論理は単純でした：公開される機能が多いほど、エージェントの有効化が進む。

実際に構築したもの

私たちはこれを軽視しませんでした。

Apidog MCPは、いくつかの手書きのエンドポイントを持つ単純なデモではありませんでした。それは完全なMCPサーバーでした：

セッションシステム

MCPクライアントはまずセッションを初期化します。サーバーはsessionIdを生成し、Redisを通じてセッション状態を保存します。その後のリクエストはsessionIdを使用してアクセスし続けます。

つまり、これは単発のHTTP呼び出しではなく、プロトコルレベルのセッションシステムでした。

ツールカテゴリ

ツール層も、いくつかの固定エンドポイントで手書きされたものではありませんでした。Apidogのツールをいくつかのカテゴリに分類しました：

最後のカテゴリ：126個の生成されたツール。

各生成されたツールには以下がありました：

• ユニークな識別子
• 特定のAPIパス
• HTTPメソッド（GET、POST、PUT、DELETEなど）
• フィールドの説明、タイプ、列挙値を含む完全な入力スキーマ
• 定義された戻り構造

プログレッシブ開示

ツールの露出圧力を減らすため、動的発見層も構築しました：

エージェントは以下のことができました：

1. まず利用可能なエンドポイントツールを検索する（listOpenApiEndpoints）
2. 次に特定のツールのOpenAPI詳細を取得する（getOpenApiDetails）
3. 最後にツールIDで実際のHTTP呼び出しを実行する（executeOpenApi）

これはプログレッシブ開示の試みでした。私たちは単純にすべての基盤となるエンドポイントを直接的かつ明示的に公開したわけではありません。エージェントが最初に検索し、次に詳細を取得し、最後に実行することを期待していました。

ランダムなツールの壁

しかし、実際のタスクに入ると、すぐに問題が浮上しました。

簡単なユーザーリクエストを考えてみましょう。

「このエンドポイントのテストを追加して、検証を実行してください。」

実装の観点から見ると、これは合理的なリクエストです。Apidogには以下の機能があります。

• エンドポイントの検索
• テストケースの作成
• テストシナリオの実行
• レポートの生成

しかし、エージェントの観点から見ると、この単純なリクエストは実際には一連の連続した判断をトリガーします。

エージェントは単に適切なツールを見つけるだけでなく、ユーザーの問題を解決する前に、「どのツールを使うべきか」という問題を解決する必要があります。

実装の観点から見ると、これらの問題はすべてツールを通じて解決できます。エージェントの体験の観点から見ると、それらはランダムなツールの壁を形成します。

4つの構造的問題

実世界でのテストと内部フィードバックを通じて、MCPアプローチには4つの構造的問題があることが判明しました。

問題1: ツール発見コストが急速に上昇する

Apidogは、わずか12個のエンドポイントで説明できる製品ではありません。

ツールが10個から数十個、数百個に増えると、エージェントはユーザーの問題を解決し始める前に、「どのツールを使用すべきか」という問題を解決する必要があります。

私たちは、ワークフローをツールのdescription（AIエージェントにツールを公開するために使用されるフィールド）に書き込むことを試みました。例えば、ツールの説明には明示的に次のように記載されます。

「エンドポイントデータを照会する前に、まず別のツールでプロジェクトを確認し、次に3番目のツールでプロジェクトメタデータを取得し、最後に現在のツールを呼び出す必要があります。」

この方法は小規模なツールセットでは機能します。しかし、大規模なツールの壁では、description自体がモデルの注意を奪い合います。

説明に多くのガイダンスを書き込めば書き込むほど、消費されるトークンは増え、エージェントがそれを実際に読み、従う可能性は低くなりました。

問題2: ビジネススキーマがコンテキストを侵害する

各MCPツールは単なるツール名ではありません。

すべてのツールの背後には以下があります：

• description（ツールの機能）
• input schema（パラメータ、タイプ、必須/オプション）
• フィールドの説明（ネストされた構造、制約）
• 列挙値（許可されるオプション）
• 戻り構造（レスポンス形式、エラー処理）

控えめに見積もってみましょう：

ユーザーの質問はわずか50文字かもしれません。しかし、モデルは、たった1つのMCPサーバーのために、まず50,000トークンのツール説明を導入せざるを得ません。

これは理論ではありません。業界データがそれを裏付けています。

Cursorの公式ブログ投稿「Dynamic Context Discovery」は貴重な参照データを提供しました。MCPツールの説明、ターミナルセッション、および長い会話をオンデマンドで読み込み可能なコンテキストに変換することで、ランタイムトークン消費が46.9%削減されました。

Traeのアプローチはより直接的でした。MCPツール数と単一ツールの説明長を制限しています。

• ツール数の上限：40
• 単一ツールの説明の制限：8000文字

実際、初期の内部テスト中、多くのチームはApidog MCPがTraeで一部のツールを呼び出すことができない問題があると報告しました。エージェントは限られたモデルコンテキストのためにトレードオフを強いられ、外部ツールが最初に「カット」されました。

これらの解決策はすべて同じ事実を指し示しています。

ツールの説明は無限にモデルコンテキストに入力することはできません。

問題3: プロトコルセッションが実行チェーンを重くする

Apidog MCPサーバーは以下を処理する必要があります：

簡単なツール呼び出しの場合、これらのコストは許容できます。しかし、多数の呼び出しと頻繁な探索を伴うエージェントタスクの場合、これらの状態管理要件はサーバー側とクライアント側の両方で複雑さを増します。

Apidog MCPを実装する際、チームはさまざまなエージェントクライアント（Cursor、Claude Code、Antigravity、Traeなど）のトラブルシューティングと適応に多大なエネルギーを消費しました。しかし、プロトコル互換性の問題は残り、公式のMCPプロトコルは新しいバージョンでパッチが当てられ続けました。

すべての関係者が多大な苦痛を経験しました。

問題4: アトミックなツールでは製品のセマンティクスを自然に表現できない

Apidogのテストシナリオでは、単純なsteps配列表現だけではありません。

テストシナリオには以下が含まれます：

これらを複数のMCPツールに分割した後でも、エージェントはテストオーケストレーション作業自体を実行しなければなりません。

ツールがアトミックであればあるほど、モデルは製品の内部セマンティクスを理解する必要があります。

• なぜインポートには読み戻しが必要なのか？
• なぜ内部ケースには異なる更新マーカーがあるのか？
• なぜアサーションには特定の比較演算子が必要なのか？
• なぜ変数抽出には型制約があるのか？

これは明らかにモデルの能力範囲を超えています。

Apidogチームは、内部製品のセマンティクスに合わせて技術的なエンジニアリング調整を積極的に行うことを強いられました。アトミックなエンドポイントは、単一のMCPツール層ディスパッチに適応するためだけに、受動的に変換層を追加しました。

エンジニアリングの課題と保守後のコストは、間違いなく困難なものです。

根本原因

これら4つの問題の根本原因は同じです。

MCPはツールを接続するのに優れていますが、複雑なR&Dタスクには、ツールの接続以上のもの、つまり実行可能なエンジニアリングプロセスが必要です。

明確に定義された12個程度の操作を持つシンプルな製品の場合、MCPはうまく機能します。エージェントは適切なツールを合理的に推測し、呼び出し、結果を得ることができます。

Apidogのような製品、つまり数十のモジュール、数百の操作、ネストされた構造、隠れたワークフロー、製品固有のセマンティクスを持つ製品の場合、MCPだけでは、エージェントがナビゲートに苦労するランダムなツールの壁を生み出します。

私たちが学んだこと

転換点

この認識から、私たちは異なる質問をすることになりました。

もしMCPがエージェントの有効化の答えではないなら、何が答えなのか？

私たちはMCPの価値を放棄したわけではありません。それは標準化された接続を提供し、エコシステムにとって重要です。しかし、私たちは以下のことができるものが必要でした。

• ツールだけでなく、ワークフローを表現できるもの
• エージェントをシーケンスに沿ってガイドできるもの
• 書き込む前に検証できるもの
• エンジニアリングの品質ゲートを強制できるもの
• 複雑さをシステムに吸収できるもの

私たちがたどり着いた答えは、CLI + SKILLでした。

次の記事「なぜ私たちは全く新しいApidog CLIを開発したのか」では、複雑さがモデルコンテキストからエンジニアリングシステムへと移行したアーキテクチャの変更点、そしてそれがエージェントの有効化にすべてを変える理由について探ります。

主なポイント

• MCPは「エージェントがツールにどう接続するか」という業界の答えとなった
• 私たちは、ツールが多いほど有効化が向上すると考えて、126個のMCPツールを構築した
• 実際のタスクでは、発見コスト、コンテキストの侵害、セッションオーバーヘッド、製品セマンティクスという4つの構造的問題が明らかになった
• 根本原因：MCPはツールを接続するが、複雑なタスクには実行可能なプロセスが必要である
• ツール説明がコンテキストを消費する場合、ツールの増加はメリットではなくコストである

Apidogをダウンロードして、1つのワークスペースでAPIの設計、モック、テスト、ドキュメント化を行いましょう。コマンドラインAPIテスト、CI自動化、AIエージェントワークフローのためのApidog CLIについて詳しく学びましょう。