MCP-Server-Fehler

So behandelst du Fehler, die vom foura-mcp-Server zurückgegeben werden.

Jede Fehlerantwort von einem der vier Tools (foura_auto, foura_single, foura_proxy, foura_browser) ist strukturiert. LLM-Agenten können das Feld code für die Retry-Logik lesen, ohne Fließtext zu parsen.

Envelope-Struktur

Jeder Fehler (isError: true) enthält einen structuredContent-Block. Mindestfelder bei jedem Fehler:

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

Bei Upstream-Fehlern mit HTTP-Status ist auch status vorhanden. Bei Rate-Limit- und Kapazitätsfehlern fügt der Envelope retryAfter, current.{concurrency, rpm} und limits.{maxConcurrency, maxRpm} hinzu, mit derselben Struktur wie die zugrunde liegenden REST-API-Fehler.

Stabile code-Werte

HTTP-Fehler vom MCP-Server

Einige Fehler treten auf der MCP-Transportschicht auf, bevor ein Tool aufgerufen wird. Diese geben unformatierte JSON-RPC-Fehler zurück (kein structuredContent):

Die Allowlists für 403 sind für Self-Hoster über FOURA_MCP_ALLOWED_HOSTS und FOURA_MCP_ALLOWED_ORIGINS umgebungskonfigurierbar.

Abgelehnte Browser-Profile

Ein Browser-Profil, das der Katalog nicht bereitstellen kann, oder ein Profil, das mit unblocker auf false gesendet wird, kommt als Upstream-Fehler mit dem Grund in error zurück und der Request verlässt FourA niemals. Die Nachricht nennt die verfügbaren Optionen, wiederhole den Vorgang also mit einer der aufgelisteten Kombinationen statt mit derselben.

Dies sind Ablehnungen, keine Ausfälle: Ein erneuter Versuch mit dem identischen Request kann nicht erfolgreich sein, und es wurde kein anderer Browser an dessen Stelle verwendet.

Retry-Strategie

Vier Kategorien:

• Warten und erneut versuchen: rate_limited, at_capacity, service_unavailable, upstream_error. Beachte retryAfter, falls vorhanden. Nutze exponentielles Backoff mit Jitter, falls es fehlt.
• Scope beibehalten und später erneut versuchen: no_eligible_proxy. Entferne nicht exitCountries und ersetze ein Land nicht stillschweigend durch ein anderes. Ändere oder erweitere die Allowlist nur, wenn der Benutzer die Anforderung explizit ändert.
• Nicht erneut versuchen, bis Eingabe oder Credential korrigiert sind: bad_request, auth_failed, not_found, ssrf_blocked. Überprüfe bei auth_failed den FourA API-Schlüssel, nicht die Credentials der Zielseite.
• Tool wechseln, wenn der Inhalt es erfordert: forbidden auf foura_single kann einen begrenzten foura_proxy-Versuch rechtfertigen. Nutze foura_browser, wenn der gewünschte Inhalt JavaScript benötigt. Übergib nach erfolgreicher Proxy-Auswahl die zurückgegebene proxy ID an foura_browser.proxy, anstatt eine neue Auswahl zu starten.

Retry-Beispiel (TypeScript, MCP-seitig)

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

Verwandte Themen

• MCP Server, die vier Tools und ihre Schemas
• MCP Recipes, mit dem Server gelieferte Workflow-Prompts
• API Errors, gleicher Envelope auf der zugrunde liegenden REST API-Schicht