MCPエラーは転送、認証、スコープ／プラン、クォータ、ツール呼び出しの種類に分類されます。クライアントコードを変更する前に以下のコードと照合してください。
サービスを利用できない場合はどうすればよいですか？
503 はサービスの可用性に関する問題を示します。公開接続先を確認し、呼び出しを停止してから、回数を制限して待機時間を延ばしながら再試行してください。解消しない場合は時刻と機密情報を除いたリクエスト ID をサポートに伝えてください。
ホストまたはオリジン確認が失敗する理由は何ですか
- streamable HTTP に対応する MCP クライアントで
https://app.dureach.com/mcpを正確に指定してください。 - 対象ワークスペースの OAuth 同意を完了し、認証情報はクライアントの保護された認証情報ストアまたはサーバー側のシークレット管理サービスに保存してください。
- ホストやオリジンが拒否された場合は接続先 URL を確認し、サポートに連絡してください。拒否を回避するためにセキュリティヘッダーを削除したり偽装したりしないでください。
- 調査のために応答の
request_idを保存し、共有ログにトークンや結果行を含めないでください。
認証が失敗する理由は何ですか
| 症状 | 意味 | 対処 |
|---|---|---|
401、request_id詳細なし | トークンの不足、有効期限切れ、取り消し、オーディエンス不一致。 | OAuth同意を再度完了します。オーディエンスが/mcpリソース（/.well-known/oauth-protected-resource/mcp）であることを確認し、Authorization: Bearer YOUR_OAUTH_ACCESS_TOKENを送信します。 |
他の場所では有効なREST APIキーが/mcpで拒否される | APIキーはMCPでは有効ではありません。 | OAuthベアラートークンを使用してください。APIキーは文書化されたREST経路でのみ有効です。 |
workspace_context_required（403） | X-Workspace-IDがトークンのワークスペースと一致しません。 | トークンのワークスペースIDを送信するか、ヘッダーを省略してください。トークンを別のワークスペースで使うことはできません。 |
ツールが不足または拒否される理由は何ですか
| 症状 | 意味 | 対処 |
|---|---|---|
tools/listにツールがない | この接続では利用できません。 | 付与された権限とワークスペースの利用資格を管理者に確認してください。 |
Unknown tool（INVALID_PARAMS） | 名前にdureach.接頭辞がないか、14ツールのいずれでもありません。 | 完全名を送信します（たとえばdureach.trade.search）。エイリアスcompanies.listはcompanies.searchに解決されます。他の名前は拒否されます。 |
scope_required | トークンにツールスコープがありません。 | ツールに必要な権限だけを確認して付与してください。エラーを解消するためだけにアクセスを拡大しないでください。 |
plan_capability_required（403） | ワークスペースにエージェントプラットフォーム機能がありません。 | 管理者に機能有効化またはプラン変更を依頼します。 |
invalid_arguments | 範囲外の値、短いクエリ、未知のフィールド、過大なSQLです。 | ツールの一覧表と照合してください。クエリは3文字以上、ページと上限は範囲内、SQLは16 KiB以内かつ読み取り専用文法にしてください。 |
company_not_found | companies.readのIDが不明です。 | UUIDが同一ワークスペースのcompanies.search由来であることを確認します。 |
policy_not_found／policy_not_authorized | R3送信が不明、取り消し済み、有効期限切れ、または不一致のポリシーを指定しています。 | このOAuthクライアントに紐付いたACTIVEな所有者が確認したポリシーのpolicy_idを渡し、最初にドライラン（dry_run: true）を実行してから同じ冪等キーで再試行してください。 |
policy_budget_exceeded／policy_daily_cap_exceeded | ポリシーの送信上限に達しました。 | 翌日の期間を待つか、所有者に上限の見直しを依頼します。上限回避のため送信を新規ポリシーに分割しないでください。 |
recipient_suppressed／recipient_already_attempted | 宛先が配信停止、バウンス、非有効リード、またはこのポリシーで試行済みです。 | 宛先を除外し、除外状態を確認します。同一宛先を新規ポリシーで再試行しないでください。 |
result_too_large | 送信用結果が1 MiB超です。 | 列／絞り込みを狭めるかlimitを下げます。 |
quota_exceeded（429） | 分、時間、日いずれかの予算を使い切りました。 | Retry-Afterに従ってください。詳細にはlimit_type、reset_at、retry_afterが含まれます。MCPの承認、ポリシー、クォータを参照してください。 |
| 本文の拒否または切り詰め | リクエストが256,000バイト超です。 | SQLまたは引数を短縮するか、呼び出しを分割してください。 |
サポートに送るべき内容は何ですか
request_id（またはx-request-id）、タイムスタンプ、ツール名、page／limitまたはSQL形式（可能な範囲で顧客識別子を除きます）、HTTPステータス、エラーコードを含めてください。ベアラートークン、完全な担当者レコード、Webhookペイロードは含めないでください。