MCPサーバーエラー

MCPサーバーのエラー

foura-mcp serverが返すエラーの処理方法。

4つのツール(foura_auto、foura_single、foura_proxy、foura_browser)からの各エラーレスポンスは構造化されています。LLMエージェントは文章を解析することなく、codeフィールドを読み取って再試行ロジックを処理できます。

エンベロープの形状

すべてのエラー(isError: true)にはstructuredContentブロックが含まれます。各エラーの最小フィールド:

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

HTTPステータスを伴うupstreamエラーの場合、statusも存在します。レート制限およびキャパシティーエラーの場合、エンベロープにはretryAfter、current.{concurrency, rpm}、limits.{maxConcurrency, maxRpm}が追加されます。これは基礎となるREST APIエラーと同じ形式です。

安定した`code`値

コード	HTTP	意味	再試行の安全性
`ssrf_blocked`	n/a	ターゲットIPがプライベートまたは予約済み範囲にある(RFC 5735、RFC 6598、IPv6予約済み)	いいえ、URLを変更してください
`upstream_non_json`	可変	upstreamが有効なJSONではないbodyを返した	おそらく可、調査が必要
`output_validation_failed`	n/a	MCPサーバーの`outputSchema`がupstreamのresponseを拒否した(サーバーのバグまたは予期しないupstreamの形式)	おそらく可、報告してください
`bad_request`	400	FourA APIによって入力形式が拒否された	いいえ、引数を修正してください
`auth_failed`	401	FourA APIキーが欠落している、無効である、または非アクティブ化されている(ターゲットサイトの認証情報に関するものではありません)	いいえ、FourAキーを修正してください
`forbidden`	403	ターゲットがrequestを拒否した(アンチボット、ジオブロック)	いいえ、または`foura_proxy`に切り替えてください
`not_found`	404	ターゲットURLまたはendpointが存在しない	いいえ
`rate_limited`	429	キーごとのRPM上限に達した	はい、`retryAfter`秒待機してください
`at_capacity`	503	同時実行数の上限に達した(`current.concurrency` > `limits.maxConcurrency`)	はい、`retryAfter`秒待機してください
`service_disabled`	503	アカウントのサービスが無効化されている(プランまたはメンテナンス)	サポートにお問い合わせください
`service_unavailable`	503	upstreamからの一般的な503	はい、短いバックオフ
`upstream_error`	500+	Upstreamの5xx	はい、指数関数的バックオフ
`upstream_client_error`	4xx	上記に含まれないその他の4xx	通常はいいえ
`upstream_unknown`	その他	防御的措置(実際には発生しないはずです)	調査が必要
`no_eligible_proxy`	n/a	厳格な`exitCountries`許可リストに一致するproxyがない(`details.exitCountries`には正規化されたスコープが含まれます)	後で再試行するか、スコープを明示的に変更してください

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

一部のエラーは、ツールが呼び出される前のMCPトランスポート層で発生します。これらは生のJSON-RPCエラーを返します(structuredContentはありません)。

HTTP	発生条件	表示内容
400	サポートされていない`MCP-Protocol-Version` header	`Unsupported MCP-Protocol-Version: <value>. Supported: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07.`
401	`Authorization` headerが欠落しているか不正な形式	JSON-RPCエラー + `WWW-Authenticate: Bearer realm="foura-mcp", resource_metadata="https://foura.ai/docs/mcp/server#auth"`
403	許可されていない`Origin`または`Host` header(DNSリバインディング防御、CVE-2025-66414)	`Origin <value> is not in the allowlist`または`Host <value> is not in the allowlist`
405	`/mcp`での`GET`または`DELETE`(ステートレスモード)	`Method not allowed in stateless mode. Use POST /mcp.`
413	Request body > 256 KB	Expressのデフォルトの413

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

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

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

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

再試行戦略

4つのカテゴリ:

待機して再試行: rate_limited、at_capacity、service_unavailable、upstream_error。retryAfterが存在する場合はそれに従います。存在しない場合はジッター付きのExponential Backoffを使用します。
スコープを保持して後で再試行: no_eligible_proxy。exitCountriesを削除したり、暗黙的に他の国で代用したりしないでください。ユーザーが明示的に要件を変更した場合にのみ、許可リストを変更または拡大します。
入力または認証情報が修正されるまで再試行しない: bad_request、auth_failed、not_found、ssrf_blocked。auth_failedについては、ターゲットサイトの認証情報ではなく、FourA APIキーを検証してください。
コンテンツが要求する場合にツールを切り替える: 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");
}