MCP errors fall into transport, authentication, scope/plan, quota, and tool-call groups. Match the code below before changing client code.
What should you do when the service is unavailable?
A 503 response indicates a service availability problem. Confirm the public connection URL, pause calls, and retry later with bounded backoff. If it persists, contact support with the timestamp and redacted request ID.
Why do host or origin checks fail?
- Use
https://app.dureach.com/mcpexactly with an MCP client that supports streamable HTTP. - Complete OAuth consent for the intended workspace; keep credentials in the client’s protected credential store or a server-side secret manager.
- For a host or origin rejection, verify the configured connection URL and contact support. Do not remove or forge security headers to bypass a rejection.
- Keep the response
request_idfor troubleshooting; never include tokens or result rows in shared logs.
Why does authentication fail?
| Symptom | Meaning | Fix |
|---|---|---|
401, no request_id detail | Missing, expired, revoked, or wrong-audience token. | Complete OAuth consent again; confirm the audience is the /mcp resource (/.well-known/oauth-protected-resource/mcp); send Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN. |
REST API key accepted elsewhere, rejected on /mcp | API keys are not valid for MCP. | Use an OAuth bearer token. API keys remain valid only for their documented REST routes. |
workspace_context_required (403) | X-Workspace-ID does not match the token workspace. | Send the token workspace ID or omit the header. Tokens never cross workspaces. |
Why is a tool missing or rejected?
| Symptom | Meaning | Fix |
|---|---|---|
Tool absent from tools/list | Not available to this connection. | Review granted permissions and workspace access with an administrator. |
Unknown tool (INVALID_PARAMS) | Name lacks the dureach. prefix or is not one of the 14 tools. | Send the full name (for example, dureach.trade.search). The alias companies.list resolves to companies.search; other names are rejected. |
scope_required | Token lacks the tool scope. | Review and grant only the scope required by the tool. Do not broaden access merely to clear an error. |
plan_capability_required (403) | Workspace lacks the agent platform capability. | Ask an admin to enable the capability or change plan. |
invalid_arguments | Out-of-range value, short query, unknown field, or oversized SQL. | Compare against the tool table; queries need 3+ characters, pages and limits must stay in range, SQL must stay within 16 KiB and the read-only grammar. |
company_not_found | companies.read ID unknown. | Confirm the UUID came from companies.search in the same workspace. |
policy_not_found / policy_not_authorized | R3 send names an unknown, revoked, expired, or mismatched policy. | Pass the policy_id of an ACTIVE owner-reviewed policy bound to this OAuth client, run dry_run: true first, then retry with the same idempotency key. |
policy_budget_exceeded / policy_daily_cap_exceeded | Policy send caps reached. | Wait for the next day window or ask an owner to review caps; do not split sends across new policies to evade caps. |
recipient_suppressed / recipient_already_attempted | Recipient opted out, bounced, is not an active lead, or was already attempted under this policy. | Remove the recipient and review suppression state; never retry the same recipient under a new policy. |
result_too_large | Wire result over 1 MiB. | Narrow columns/filters or lower limit. |
quota_exceeded (429) | A minute, hour, or day budget is spent. | Honor Retry-After; details include limit_type, reset_at, retry_after. See MCP approvals, policies, and quotas. |
| Body rejected or truncated | Request over 256,000 bytes. | Shorten SQL or arguments; split the call. |
What should you send to support?
Include the request_id (or x-request-id), timestamp, tool name, page/limit or SQL shape (without customer identifiers where possible), HTTP status, and error code. Never include the bearer token, full contact rows, or webhook payloads.