MCP Server Errors

How to handle errors returned by the foura-mcp server.

Every error response from any of the four tools (foura_auto, foura_single, foura_proxy, foura_browser) is structured. LLM agents can read the code field for retry logic without parsing prose.

Envelope shape

Every error (isError: true) carries a structuredContent block. Minimum fields on every error:

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

On upstream errors with HTTP status, status is also present. When the platform's shared allowance refuses a call, the envelope adds retryAfter, current.{concurrency, rpm}, and limits.{maxConcurrency, maxRpm}, same shape as the underlying REST API errors.

When one of your plan's own limits refuses a call, the code IS that limit: plan_limit_ followed by credits, bandwidth, rate, concurrency, browser_daily, premium or feature. retryAfter carries the wait where a wait clears it, and is absent for a limit that a wait cannot clear, such as a feature the plan does not include. plan_limit_browser_daily carries no retryAfter either: it clears at midnight UTC.

On foura_auto, a plan limit met inside its ladder comes back as rate_limited or forbidden, with the plan's code in reason.

Stable code values

HTTP-level errors from the MCP server

Some failures happen at the MCP transport layer, before any tool is called. These return raw JSON-RPC errors (no structuredContent):

The allowlists for 403 are env-configurable for self-hosters via FOURA_MCP_ALLOWED_HOSTS and FOURA_MCP_ALLOWED_ORIGINS.

Refused browser profiles

A browser profile that the catalogue cannot present, or a profile sent with unblocker set to false, comes back as an upstream failure with the reason in error and the request never leaves FourA. The message names what is available, so retry with one of the listed combinations rather than the same one.

These are refusals, not outages: retrying the identical request cannot succeed, and no other browser was used in its place.

Retry strategy

Five buckets:

• Your own plan refused it, not the target: any plan_limit_* code. The same work through another tool is refused as well, so switching endpoints spends nothing but time. Wait out retryAfter where there is one; otherwise the plan has to change. plan_limit_premium is the one you can clear yourself, by dropping exitClass.
• Wait and retry: rate_limited, at_capacity, service_unavailable, upstream_error. Honour retryAfter when present. Use exponential backoff with jitter when it isn't there. Don't answer it by re-issuing every queued tool call at once: cut how many you run in parallel instead.
• Preserve scope and retry later: no_eligible_proxy. Do not remove exitCountries or substitute another country silently. Change or widen the allowlist only when the user explicitly changes the requirement.
• Do not retry until the input or credential is fixed: bad_request, auth_failed, not_found, ssrf_blocked. For auth_failed, verify the FourA API key, not target-site credentials.
• Switch tool when the content requires it: forbidden on foura_single can justify a bounded foura_proxy attempt. Use foura_browser when the desired content needs JavaScript. After a successful proxy selection, pass the returned proxy ID into foura_browser.proxy instead of starting a new selection.

Retry example (TypeScript, MCP-side)

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");
}

Related

• MCP Server, the four tools and their schemas
• MCP Recipes, workflow prompts shipped with the server
• API Errors, same envelope at the underlying REST API layer
• Rate Limits, the account and platform limits behind rate_limited and at_capacity