MCP Server エラー

foura-mcp server から返されるエラーの処理方法。

4つのツール（foura_auto、foura_single、foura_proxy、foura_browser）からのすべてのエラー response は構造化されています。LLM エージェントはテキストを解析することなく、リトライロジック用に code フィールドを読み取ることができます。

エンベロープの形式

すべてのエラー（isError: true）には structuredContent ブロックが含まれます。すべてのエラーにおける必須フィールドは以下の通りです:

{
  "service": "auto | single | proxy | browser",
  "code": "rate_limited",
  "error": "Rate limit exceeded"
}

HTTPステータスを伴うアップストリームエラーの場合、statusも含まれます。プラットフォームの共有割り当てによって呼び出しが拒否された場合、エンベロープにはretryAfter、current.{concurrency, rpm}、およびlimits.{maxConcurrency, maxRpm}が追加されます（基盤となるREST APIエラーと同じ形式です）。

ご契約プラン固有の制限によって呼び出しが拒否された場合、コードはその制限自体を示します: plan_limit_の後にcredits、bandwidth、rate、concurrency、browser_daily、premium、またはfeatureが続きます。待機によって解除される場合はretryAfterに待機時間が設定され、プランに含まれていない機能など、待機では解除されない制限の場合は省略されます。plan_limit_browser_dailyにもretryAfterは含まれません（UTC午前0時にリセットされます）。

foura_autoでは、ラダー内でプラン制限に達した場合、rate_limitedまたはforbiddenとして返され、reasonにプランのコードが含まれます。

安定版codeの値

MCPサーバーからのHTTPレベルエラー

一部のエラーは、ツールが呼び出される前のMCPトランスポート層で発生します。これらは生のJSON-RPCエラーを返します（structuredContentなし）:

403の許可リストは、セルフホスト環境向けにFOURA_MCP_ALLOWED_HOSTSおよびFOURA_MCP_ALLOWED_ORIGINSで環境変数から設定可能です。

拒否されたブラウザプロファイル

カタログが提供できないブラウザプロファイル、またはunblockerをfalseに設定して送信されたプロファイルは、errorに理由が含まれるアップストリームエラーとして返され、リクエストがFourAから送信されることはありません。メッセージには利用可能な組み合わせが示されるため、同一のリクエストではなく、リストされた組み合わせのいずれかで再試行してください。

これらはサービス停止ではなくリクエストの拒否です。同一のリクエストを再試行しても成功せず、他のブラウザが代用されることもありません。

リトライ戦略

5つの区分:

• ターゲットではなく自身のプランによる拒否: すべてのplan_limit_*コード。別のツール経由で同じ処理を実行しても同様に拒否されるため、endpointを切り替えても時間を浪費するだけです。retryAfterがある場合はその解除を待ち、ない場合はプランの変更が必要です。plan_limit_premiumは、exitClassを外すことで自ら解消できます。
• 待機して再試行: rate_limited、at_capacity、service_unavailable、upstream_error。retryAfterが存在する場合はそれに従ってください。存在しない場合は、ジッター付きの指数バックオフを使用します。キュー内のすべてのツール呼び出しを一度に再実行するのではなく、並行実行数を減らして対処してください。
• スコープを維持して後で再試行: no_eligible_proxy。exitCountriesを削除したり、別の国へ勝手に置き換えたりしないでください。ユーザーが明示的に要件を変更した場合にのみ、許可リストを変更または拡張します。
• 入力または認証情報が修正されるまで再試行しない: bad_request、auth_failed、not_found、ssrf_blocked。auth_failedについては、ターゲットサイトの認証情報ではなくFourAのAPI keyを確認してください。
• コンテンツに応じてツールを切り替える: foura_singleでのforbiddenは、回数を制限したfoura_proxyの試行を正当化する理由になります。目的のコンテンツにJavaScriptが必要な場合はfoura_browserを使用します。proxyの選択が成功した後は、新しく選択を開始するのではなく、返されたproxy IDをfoura_browser.proxyに渡してください。

リトライの実装例 (TypeScript、MCP側)

async function callWithRetry(call: () => Promise<any>, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const r = await call();
    if (!r.isError) return r;

    const code = r.structuredContent?.code;
    const wait = r.structuredContent?.retryAfter ?? Math.min(2 ** attempt, 30);

    if (["rate_limited", "at_capacity", "service_unavailable", "upstream_error"].includes(code)) {
      await new Promise((res) => setTimeout(res, wait * 1000));
      continue;
    }
    // Non-retryable, surface to caller
    throw new Error(`${code}: ${r.structuredContent?.error}`);
  }
  throw new Error("max retries exceeded");
}

関連ドキュメント

• MCP Server: 4つのツールとそのスキーマ
• MCP Recipes: サーバーに同梱されているワークフロープロンプト
• API Errors: 基盤となるREST API層での共通エンベロープ
• Rate Limits: rate_limitedおよびat_capacityの背後にあるアカウントおよびプラットフォームの制限