GPT Image 2.5 is live — OpenAI's newest image model, targeted edits that leave the rest of the frame alone
すべてのガイド

· reAPI Team

MCPツール呼び出し:API切り替え後に失敗する理由

MCPツール呼び出しを、検出、モデル対応、実行、返却結果の各段階で追跡します。有料タスクを再試行または送信する前に、API移行の失敗を診断しましょう。

MCPツール呼び出し:API切り替え後に失敗する理由

MCPサーバーは「接続済み」と表示されます。それでもアシスタントは通常の文章で答えたり、結果を示さずにタスクを確認したと言ったりします。モデルAPIを変更した後に起き始めた場合は、プロンプトを再び変更する前に、新しい接続で何が渡されたかを調べてください。

接続されたツールサーバーと、ツールをリクエストできるモデルは、アプリケーション内の別々の要素です。MCPはツールの検出と呼び出しを定義します。その後ホストは、適切なツールをモデルに公開し、モデルがリクエストした許可済みの呼び出しを実行して、結果を返す必要があります。[1][2] 最初の段階が成功しても、最後の段階まで成功したことにはなりません。

クライアントが受け取ったリストからツールを探す

まず1つのツールを確認します。影響を受けたクライアントが実際に受け取った tools/list の結果を読み、該当する場合は後続ページも確認してください。名前、説明、入力スキーマを保持します。接続バッジを見ても、この特定のツールが検出されたかどうかは分かりません。

ツールがなければ、クライアントを実行しているプロセスで選択されたサーバー、対応するトランスポート、認証を確認します。現行のMCP仕様では、利用可能なツールは提供された認可情報によって変わる場合があります。[1] したがって、1つのツールが見えるからといって、同じ呼び出し元がそのサーバーのすべてのツールを見られる証明にはなりません。

reAPI接続について、ドキュメントに記載されたサーバーは、カスタムBearer認証ヘッダーを使うリモートStreamable HTTPを使用します。カスタムヘッダーなしのOAuthサインインしか提供しないクライアントは、この構成では接続できません。[3] モデルへの指示を繰り返しても、クライアントにないトランスポートや認証情報の仕組みは補えません。

調査では、モデルプロバイダーの認証情報とツールサーバーの認証情報を区別してください。それぞれ別の接続に属する場合があります。モデルAPIキーを交換しても、MCP接続に欠けている認証情報は修復されません。MCP認証情報を交換しても、モデルへの送信リクエストにツールが追加されるわけではありません。秘密情報そのものではなく、安全な構成識別子を記録してください。

検出されたスキーマとモデルが見る内容を比較する

例として、架空の読み取り専用ツールを使います。これはIDで既存のタスクを検索します。この断片は検出結果の例であり、完全なプロトコル応答でも、私たちがデプロイしたツールでもありません。

{
  "name": "inspect_task_example",
  "description": "Look up the status of an existing task.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "task_id": { "type": "string" }
    },
    "required": ["task_id"]
  }
}

次に、モデルへ送信されたシリアライズ済みリクエストを調べます。モデル用のツール形式はMCPの inputSchema 形式と異なる場合がありますが、名前、プロパティ、必須フィールドの意味は変換後も保たれなければなりません。ホストがツール名を送っても task_id プロパティや必須フィールド一覧を送っていなければ、モデルが受け取った契約は別のものです。

ここがアダプターを修正できる具体的な箇所です。モデルに「ツールを正しく使う」よう指示する長いプロンプトを追加しても、欠けたスキーマは復元されません。さらに指示を足したり、再びプロバイダーを変更したりする前に、2つのオブジェクトを比較してください。

この例では、task_id を3か所で比較します。検出されたプロパティ、モデル向けプロパティ、そしてホストが後でディスパッチする引数です。いずれも同じ必須文字列値を示している必要があります。変換器が一方で id に名前を変え、もう一方では task_id のままにすると、不一致が生じています。そのフィールドの名前、型、必須状態を保ちながら、モデルAPIがサポートする定義用ラッパーを使ってください。

古い定義も確認してください。サーバー上でツール名を変更しても、キャッシュされたクライアントリストには古い名前が残ることがあります。比較対象が別のドキュメントページにある最新スキーマではなく、モデルが実際に受け取った内容になるよう、失敗したリクエストで使われた定義を保存してください。

モデルはツールをリクエストしたのか、それとも使うと述べただけか?

モデル応答の構造を読みます。「タスクを確認します」という通常の文章は、構造化されたツール呼び出しではありません。拒否、通常の回答、不正な呼び出し、有効な呼び出しでは、HTTP応答がどれも成功していたとしても、次に取るべき手順は異なります。

リクエストに正しいスキーマが含まれていたのに呼び出しが返されなければ、モデルの対応状況、ツール選択設定、使用したルートを調べてください。自動ツール選択では通常の回答が返ることがあります。ツールを無効にする設定では選択されないことがあります。より厳密なツール選択値への対応状況もモデルによって異なります。[2] 呼び出しがないたびに、引数の形式不備だと判断しないでください。

仲介サービスがプロバイダーを選ぶ場合、ルーティングも関係します。OpenRouterは、すべてのリクエストパラメーターに対応するプロバイダーだけにルートを絞るための require_parameters を説明しています。ツールに関する設定を含む既定のパラメーター優先設定は、厳密なフィルタリングとは異なります。[4] フォールバックモデルと、リクエストを処理したルートを確認してください。そのプロバイダー固有のオプションを別のAPIにコピーし、同等に動作すると決めつけないでください。

構造化された呼び出しが届いた場合は、選択のデバッグを止めて、その呼び出しを追跡してください。モデルは操作をリクエストしましたが、アプリケーションはそれを実行する必要があります。OpenRouterのツール呼び出しチュートリアルでは、実行をモデルではなく呼び出し側の責任と明記しています。[2]

実行から結果返却まで同じ呼び出しIDを追跡する

次は、架空の例の続きで、Chat Completionsのメッセージ形式を使っています。IDと結果は作例です。これは確認用のメッセージ断片であり、リクエストを送信するスクリプトではありません。

[
  {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      {
        "id": "call_example_1",
        "type": "function",
        "function": {
          "name": "inspect_task_example",
          "arguments": "{\"task_id\":\"example_task_7\"}"
        }
      }
    ]
  },
  {
    "role": "tool",
    "tool_call_id": "call_example_1",
    "content": "{\"task_id\":\"example_task_7\",\"status\":\"processing\"}"
  }
]

この2つのメッセージの間で、ホストは許可された呼び出しをツールにディスパッチし、その結果を受け取る必要があります。モデル応答に call_example_1 が含まれていても、ディスパッチが行われた証拠にはなりません。対応する実行記録とサーバーの結果を確認してください。

実行が承認待ちなら、その状態を維持してください。ユーザーが拒否した場合、その操作の結果は拒否です。別のツールや再試行は、その判断を迂回する許可にはなりません。承認されたのにディスパッチされなかった場合は、ホストの実行ロジックを調べてください。

ディスパッチされたツール名と引数も、リクエストされた呼び出しと照合してください。この例では、検索には example_task_7 が渡される必要があります。ホストが誤って前のタスクIDを再利用すると、サーバーが有効な結果を返しても、別の検索を実行したことになります。モデルの呼び出しIDとツール呼び出し、返却内容の対応関係を保存してください。これにより、モデルが確信を持って回答に取り込む前に、誤ったタスクの結果に気付けます。ソースツールのスキーマを変更したり、アクセス範囲を広げたりせず、このローカルな対応付けを修正してください。

ストリーミング呼び出しでは、引数がすべて揃うまで待ちます。OpenRouterは、呼び出しインデックスごとに差分を集め、引数文字列が完成してから解析する方法を説明しています。[2] task_id の途中で終わる初期断片は、まだ有効なJSONではありません。これを、完全な文字列になっても無効な引数とは区別してください。

上の2番目のメッセージには、1番目と同じ呼び出しIDが含まれています。ドキュメントに記載されたChat Completionsのループでは、アシスタントのツール呼び出しターンの後に、要求された各呼び出しの結果メッセージが続きます。[2] 複数の呼び出しが返された場合は、それぞれの識別情報と結果を保ってください。すべてのIDに同じ結果を送ると、会話が完了したように見えても、要求された操作に誤ったデータが紐付くことがあります。

ツールが実際に processing を返したのに、次のモデルリクエストでツールメッセージが省かれたとします。実行は成功しましたが、モデルは結果を受け取っていません。あるいは、変換中にホストが結果を空文字列に置き換えたとします。モデルを変更しても、会話に同じ情報欠落が残ります。

実際のサーバー結果と、次に送信されるリクエストを比較してください。クライアントログの成功フラグだけでなく、関連する内容やエラーも保持します。モデルの最終的な表現は、与えられた結果に照らして評価してください。タスクを確認したという主張は、その記録の代わりにはなりません。

ツールのエラーを見える状態に保つ

MCPでは、プロトコルの問題とツール実行の失敗を区別します。不明なツールや形式の不正なプロトコルリクエストは、JSON-RPCエラーを生じることがあります。一方、ツールの実行失敗は isError: true として返されることがあります。[1] モデル向けに結果を変換する際は、この違いと関連メッセージを保持してください。

例の検索で、タスクにアクセスできないというエラーを、空の成功ステータスに変えてはいけません。モデルが空文字列しか受け取らなければ、失敗を説明したり適切な次の行動を選んだりするための情報が失われています。最終回答を責める前に、変換処理を確認してください。

有用なローカル確認方法は、保存済みまたは合成したメッセージをアダプターに渡すことです。通常の結果を1つ、実行エラーを1つ、異なるIDを持つ呼び出しを2つ用意します。内容、エラーの意味、識別情報が保たれることを確認してください。これはアダプターがそのテストデータをどう扱うかを検証するものであり、リモートモデルがツールを正しく選ぶことを証明するものではありません。選んだツールが読み取り専用でも、ライブモデル評価では推論料金が発生することがあります。

2つの合成結果を明確に異なる内容にして、リクエストと逆の順番で返してください。ホストは到着順ではなく、呼び出しの識別情報で対応付ける必要があります。同じテスト結果を使うと、入れ替えても次のモデル入力に見た目の違いがなく、この誤りを見逃すことがあります。

生成を送信する前に接続確認を終える

reAPIでは、問題に関係する、タスクを送信しないツールから始めてください。MCPリファレンスでは、モデル検出、スキーマ取得、見積もり、タスク状態、残高の操作はクレジットを消費しないと説明されています。submit_task は別で、タスクを作成する呼び出しにはそのタスクの料金がかかります。[3]

ドキュメントに記載されたサーバーはステートレスで、1回のHTTPリクエストにつきJSON-RPCメッセージを1つ受け付けます。バッチ配列には対応しません。メディア入力には、base64やdata URIではなく、公開HTTPまたはHTTPSのURLが必要です。[3] 実行段階で失敗した場合は、これらの実際のインターフェース要件を確認してください。接続確認として生成タスクを繰り返し送信しないでください。

返されたタスクIDを保持し、その既存タスクを照会してください。reAPIのドキュメントでは、タスク送信は冪等ではないと説明されています。作成リクエストを繰り返すと、別の課金対象タスクが作られる可能性があります。[3] 送信応答を失った場合は、何も起きなかったと決めつけず、受付確認を行ってください。

この架空の検索では、メッセージが最初に異なる箇所、つまり検出、モデル向け定義、構造化呼び出し、実行、返却結果のいずれかを示せれば、移行比較は完了です。その具体的な差異を修正し、同じ無害な確認をもう一度行ってください。サーバー、モデル、クライアントのバージョン、記録した呼び出しをまとめておけば、次の担当者は「接続済み」バッジに頼らず、何が確認されたかを把握できます。

参考資料

  1. Model Context Protocol、『Tools specification, revision 2026-07-28』。閲覧日:2026年11月16日。プロトコルのバージョンやサーバー実装は異なる場合があります。
  2. OpenRouter、「Tool Calling Across Any Model: Write the Loop Once, Swap the Model String」、公式チュートリアル、2026年9月24日更新。閲覧日:2026年11月16日。
  3. reAPI、『MCP Server documentation』。確認日:2026年11月16日。このガイドでは、ライブ生成やクライアント互換性のテストは行っていません。
  4. OpenRouter、「Provider Routing」、公式ドキュメントの「Requiring Providers to Support All Parameters」と「Default parameter preferences」。閲覧日:2026年11月16日。
すべてのガイド