Errores del servidor de MCP

Cómo manejar los errores devueltos por el servidor foura-mcp.

Cada respuesta de error de cualquiera de las cuatro herramientas (foura_auto, foura_single, foura_proxy, foura_browser) está estructurada. Los agentes LLM pueden leer el campo code para la lógica de reintento sin analizar el texto.

Estructura del envoltorio

Cada error (isError: true) lleva un bloque structuredContent. Campos mínimos en cada error:

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

En errores del upstream con estado HTTP, status también está presente. En errores de rate limit y capacidad, la envoltura añade retryAfter, current.{concurrency, rpm} y limits.{maxConcurrency, maxRpm}, con la misma estructura que los errores subyacentes de la API REST.

Valores code estables

Errores a nivel HTTP del servidor MCP

Algunos fallos ocurren en la capa de transporte del MCP, antes de que se llame a cualquier herramienta. Estos devuelven errores JSON-RPC crudos (sin structuredContent):

Las allowlists para 403 se pueden configurar por variables de entorno para hostings propios vía FOURA_MCP_ALLOWED_HOSTS y FOURA_MCP_ALLOWED_ORIGINS.

Perfiles de navegador rechazados

Un perfil de navegador que el catálogo no puede presentar, o un perfil enviado con unblocker establecido en false, vuelve como un fallo upstream con el motivo en error y la request nunca abandona FourA. El mensaje nombra lo que está disponible, así que reintenta con una de las combinaciones listadas en lugar de usar la misma.

Estos son rechazos, no cortes de servicio: reintentar la request idéntica no puede tener éxito, y no se usó ningún otro navegador en su lugar.

Estrategia de reintentos

Cuatro categorías:

• Esperar y reintentar: rate_limited, at_capacity, service_unavailable, upstream_error. Respeta retryAfter cuando esté presente. Usa retroceso exponencial (exponential backoff) con jitter cuando esté ausente.
• Preservar el scope y reintentar más tarde: no_eligible_proxy. No elimines exitCountries ni sustituyas otro país de forma silenciosa. Cambia o amplía la allowlist solo cuando el usuario cambie explícitamente el requisito.
• No reintentar hasta que se corrija el input o la credencial: bad_request, auth_failed, not_found, ssrf_blocked. Para auth_failed, verifica la API key de FourA, no las credenciales del sitio de destino.
• Cambiar de herramienta cuando el contenido lo requiera: forbidden en foura_single puede justificar un intento limitado de foura_proxy. Usa foura_browser cuando el contenido deseado necesite JavaScript. Después de una selección de proxy exitosa, pasa el ID de proxy devuelto a foura_browser.proxy en lugar de iniciar una nueva selección.

Ejemplo de reintento (TypeScript, lado del 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");
}

Relacionado

• Servidor MCP, las cuatro herramientas y sus esquemas
• Recetas de MCP, prompts de flujo de trabajo incluidos con el servidor
• Errores de la API, mismo sobre en la capa subyacente de la API REST