Servidor MCP

Servidor MCP

Usa FourA desde cualquier cliente de Model Context Protocol (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) como cuatro herramientas nativas y seis prompts de flujo de trabajo. Sin código de integración, sin cliente HTTP personalizado.

Código abierto en GitHub; en npm como @fouradata/mcp. Versión actual: 0.8.3.

Obtén una key en foura.ai/dashboard#api-keys (un clic, formato pk_live_..., y Reveal muestra la key más adelante). Pega esto en la configuración de tu cliente MCP:

{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "@fouradata/mcp"],
      "env": { "FOURA_API_KEY": "pk_live_..." }
    }
  }
}

Advertencia sobre Claude Desktop: cierra completamente Claude Desktop (Cmd+Q en macOS) antes de editar el archivo de configuración. Si la aplicación sigue en ejecución, sobrescribirá tus cambios con su configuración en memoria al salir.

El comando npx descarga @fouradata/mcp en el primer inicio y lo ejecuta como un subproceso de tu cliente MCP. No requiere instalación global.

Cliente Dónde se encuentra la configuración
Claude Desktop (macOS) ~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows) %APPDATA%\Claude\claude_desktop_config.json
Claude Code claude mcp add foura -- npx -y @fouradata/mcp (define primero FOURA_API_KEY en env)
Cursor ~/.cursor/mcp.json
Windsurf ~/.codeium/windsurf/mcp_config.json
VS Code (extensión MCP) .vscode/mcp.json, bajo una clave raíz servers en lugar de mcpServers

Reinicia el cliente. Las herramientas (foura_auto, foura_single, foura_proxy, foura_browser) y seis prompts aparecerán en tu lista de herramientas.

Inicio rápido: alojado (Streamable HTTP)

Para los clientes compatibles con el transporte Streamable HTTP (Cursor, Windsurf, VS Code, Claude Code con --transport http), dirígelos al endpoint alojado en lugar de ejecutar un subproceso local:

{
  "mcpServers": {
    "foura": {
      "url": "https://mcp.foura.ai/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_..."
      }
    }
  }
}

Para Claude Desktop, usa la configuración stdio anterior o conecta el endpoint alojado a través de mcp-remote:

{
  "mcpServers": {
    "foura": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.foura.ai/mcp", "--header", "Authorization: Bearer pk_live_..."]
    }
  }
}

Referencia del endpoint alojado

Propiedad Valor
URL https://mcp.foura.ai/mcp
Transporte Streamable HTTP (POST /mcp, respuestas SSE)
Autenticación Authorization: Bearer pk_live_... por request. Una key directa en Authorization, o X-API-Key: pk_live_..., también funciona
MCP-Protocol-Version Según @modelcontextprotocol/sdk (actualmente 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05, 2024-10-07)
Desafío 401 WWW-Authenticate: Bearer realm="foura-mcp"

El desafío 401 no incluye el parámetro RFC 9728 resource_metadata de forma intencionada. Anunciarlo hace que un cliente compatible con OAuth inicie un flujo que este servidor no implementa. Envía tu key de pk_live_ como un token Bearer y el 401 desaparecerá.

El servidor alojado es stateless. Cada request incluye su propia key, la cual el servidor reenvía a la API de FourA como X-API-Key. Una sola key da acceso a las cuatro herramientas.

Para protegerse contra DNS-rebinding (CVE-2025-66414), el servidor valida el header Host (debe ser mcp.foura.ai o localhost) y el header Origin cuando está presente (en lista blanca: mcp.foura.ai, claude.ai, app.cursor.sh, app.cursor.com). Las llamadas server-to-server (curl, clientes MCP en modo de puente stdio) no envían Origin y pasan directamente.

Herramientas

Las cuatro herramientas están anotadas con readOnlyHint: true y openWorldHint: true según la especificación MCP 2025-06-18. Los clientes que autoaprueban herramientas de solo lectura de confianza las llaman sin mostrar una ventana modal de confirmación por request.

foura_auto es la opción predeterminada inteligente: proporciónale una URL y devolverá el contenido, eligiendo el método de obtención por ti. Las otras tres son las primitivas de nivel inferior que esta orquesta; utilízalas cuando quieras un control explícito.

foura_auto

Proporciónale una URL cuando quieras que FourA elija el método de request. Realiza intentos acotados a través de las rutas disponibles de HTTP, proxy y navegador. Pasa validate en destinos protegidos para que la respuesta deba contener contenido que identifique la página real. Si ningún intento cumple con la validación, la herramienta devuelve un error en lugar de presentar una página de desafío como un éxito.

La respuesta incluye detalles de finalización en meta y, por defecto, una session reutilizable con proxy, cookies y userAgent. Para un seguimiento simple, llama a foura_single con session.proxy como proxy, serializa las cookies como un header Cookie y envía session.userAgent como el header User-Agent. Para renderizado de JavaScript, pasa los valores de sesión a los campos foura_browser correspondientes.

Define exitClass: "premium" para permitir que Auto escale a una salida premium cuando el pool estándar no pueda acceder a la página. exitClass: "standard" y omitir el campo mantienen a Auto en el pool estándar, y solo una request que especifique una clase recibe exitClass de vuelta. Funciona igual que en foura_proxy: es una autorización, no una instrucción, se descuenta del tráfico premium de tu plan y se rechaza con code: "plan_limit_premium" en un plan sin salidas premium. El campo exitClass del resultado indica qué clase entregó la respuesta. Consulta exitClass en Smart Fetch.

foura_single

Una request HTTP, una response de vuelta. Refleja POST /api/single/ de forma directa.

Úsalo para páginas estáticas, APIs JSON y HTML renderizado en servidor.

Elegir qué navegador presentas

Una request presenta el último Google Chrome por defecto. Cuando un objetivo acepte un navegador y rechace otro, define browser (Chrome, Edge, Safari, Firefox o Tor), os (Windows, macOS, Android o iOS) o version, o pasa un id exacto de profile:

{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}

La versión más reciente prevalece cuando coinciden varios perfiles. Si una combinación no existe, devuelve un error enumerando las opciones disponibles, de modo que nunca se envía una request con un navegador que no hayas elegido. La selección requiere unblocker, que está activado por defecto. El catálogo se publica en GET /api/profiles y no necesita API key.

Los mismos cuatro campos se encuentran dentro del objeto request de foura_proxy.

foura_proxy

Enruta una request HTTP a través de proxies rotativos con reintento automático. Úsalo cuando foura_single esté bloqueado o el destino requiera un país de salida específico.

Configura exitCountries con una lista de permisos estricta de códigos de país de dos letras visibles para el destino, definidos por el usuario o por los requisitos del objetivo:

{
  "maxTries": 5,
  "exitCountries": ["CZ", "GB"],
  "request": {
    "method": "GET",
    "url": "https://example.com/pricing",
    "browser": "Chrome",
    "os": "Windows"
  }
}

Los valores se limpian de espacios, se convierten a mayúsculas y se deduplican. Las salidas del pool estándar con un país desconocido quedan excluidas, y el pool estándar nunca recurre a un país no solicitado. Una salida premium también se mantiene dentro de la lista: con exitClass: "premium", el pool estándar sigue teniendo prioridad, y una salida premium sale desde uno de tus países y lo especifica en exitCountry. La selección utiliza los metadatos de país visibles para el objetivo más recientes disponibles, normalmente actualizados en un plazo de diez minutos; no es una búsqueda de geolocalización en tiempo real durante la request. No deduzcas el país emisor a partir de la dirección del host del proxy.

Un resultado exitoso con alcance definido devuelve exitCountry y el ID reutilizable proxy. Comprueba que exitCountry pertenezca a la lista de permitidos solicitada. Si el pool actual no tiene coincidencias, la herramienta devuelve code: "no_eligible_proxy" con el alcance normalizado en details.exitCountries. Conserva ese alcance y reintenta más tarde. Cámbialo o amplíalo solo cuando el usuario modifique explícitamente el requisito. La delimitación por país se incluye a partir del plan Startup. En un plan que no la incluya, una llamada que envíe exitCountries se rechaza con un 403 y X-FourA-Limit: plan_limit_feature.

Si la página seleccionada necesita JavaScript más adelante, pasa el ID proxy devuelto a foura_browser.proxy para que el navegador reutilice la misma salida.

Establece exitClass: "premium" para un objetivo al que el pool estándar no pueda llegar sin importar cuántas salidas se intenten. Es una autorización, no una instrucción: el pool estándar sigue compitiendo por la respuesta y normalmente gana, y una request a la que responde antes de que se pruebe cualquier salida premium no consume tráfico premium. Un intento premium contabiliza el tráfico que transportó incluso cuando falla. La respuesta devuelve exitClass, premium o standard, para que puedas ver por request qué clase te atendió. standard también es la respuesta una vez que se agota el tráfico premium incluido en tu plan, y se trata de un resultado normal en lugar de un error. exitClass: "standard" prohíbe el escalado por completo. exitClass: "premium" en un plan sin salidas premium se rechaza con code: "plan_limit_premium". Consulta exitClass.

Cuando la rotación tuvo que cambiar a otro navegador para obtener una respuesta, una respuesta exitosa incluye profile: el ID de perfil del catálogo en el que se estabilizó. Pásalo como profile en la siguiente llamada para presentar el mismo navegador.

Una rotación fallida incluye attemptReport junto al error: una frase en summary, además de recuentos que desglosan las salidas que nunca respondieron (noResponse), las salidas que una comprobación de bots rechazó (defense, con los proveedores en vendors), las páginas que llegaron y fueron rechazadas solo por tu propio validate.data (contentRejected), statusRejected y other. profilesTried enumera los navegadores que envió la tarea, en orden de primer uso, donde default significa que la request salió exactamente como se escribió. Un valor alto de contentRejected significa que FourA entregó páginas reales y tu propia regla las descartó. Consulta Por qué una solicitud de proxy agotó los intentos.

foura_browser

Sesión de navegador completa. JavaScript se ejecuta, el DOM se renderiza y las cookies se devuelven. Refleja POST /api/browser/.

Úsalo para aplicaciones de página única (SPA), contenido cargado de forma diferida o páginas con verificaciones que requieren un navegador real para completarse.

Para conocer las estructuras de entrada, los valores predeterminados y las reglas de validación de cada herramienta, consulta la referencia de endpoints REST. Los esquemas de las herramientas coinciden con la API REST, más la opción de inclusión offload_large exclusiva de MCP (ver más abajo), con dos excepciones: foura_browser no tiene el campo lean, y foura_proxy aún no tiene los campos de ubicación de salida. Un valor enviado bajo esos nombres nunca llega a la API. Para configurar uno, llama directamente a POST /api/browser/ o POST /api/proxy/.

Cuando un objetivo ejecuta una verificación de bots

foura_single y foura_proxy devuelven defense cuando el objetivo ejecutó una verificación de bots antes de entregar el body. defense.solved: true significa que la verificación se superó y data es la página real; false significa que el body puede ser una página de desafío (challenge). Reintenta con un browser, os o version diferente, o escala a foura_proxy o foura_browser, en lugar de procesar la página de desafío como contenido.

Respuestas tipadas

La respuesta de cada herramienta incluye tanto content (resumen de texto legible por humanos) como structuredContent (JSON tipado validado contra el outputSchema de la herramienta). Cada herramienta tiene su propia estructura única:

  • foura_auto: { status, headers, data } con estructura simple más meta ({ rung, solved, attempts, credits, attemptsByEngine, browserRequests }, siempre presente, donde rung es uno de cache, probe, proxy, browser, warmup, fail) y, por defecto, session ({ proxy, cookies, userAgent }) para reproducir la solicitud a través de herramientas de nivel inferior; una request que especificó una clase también incluye exitClass. meta.attemptsByEngine cuenta las requests que la llamada envió a Single, Proxy y Browser, y meta.browserRequests cuenta las que consumieron tu cuota diaria de Browser. Un fallo también incluye attemptReport. No incluye total_time.
  • foura_single: { status, headers, data, total_time, ... } (headers es un array, una entrada por cada salto de redirección)
  • foura_proxy: igual que single más { proxy, total }; un éxito con ámbito (scoped) también incluye exitCountry, una request que especificó una clase incluye exitClass, una rotación que cambió la familia de navegador incluye profile, y un fallo incluye attemptReport
  • foura_browser: estructura distinta { status, headers: object, body, cookies, userAgent } (nota: body puede ser un string o un objeto según el content-type)

Cada herramienta también informa el costo de la llamada y cómo rastrearla, leído desde los headers de respuesta de la API:

  • credits: créditos consumidos por esta llamada. También aparece en fallos, ya que el trabajo se realizó de todos modos. Solo se te factura si la llamada es exitosa, por lo que un fallo muestra sus créditos aquí pero no te cuesta nada.
  • request_id: ID de FourA para la llamada. Indícalo en solicitudes de soporte.
  • exitClass: premium cuando una salida premium atendió la llamada. En foura_single y foura_browser, esto sucede cuando proxy reproduce una salida premium que foura_proxy o foura_auto encontraron.

Cada uno está ausente cuando la API no reportó nada, de modo que un cliente escrito para una versión anterior sigue funcionando sin cambios. Los mismos valores están documentados en Response Headers.

Los clientes compatibles con structuredContent pueden pasar el objeto tipado directamente al LLM en lugar de exigirle que analice JSON a partir de texto libre.

Headers de respuesta con múltiples valores

Los headers que aparecen varias veces (Set-Cookie, Link, WWW-Authenticate) se devuelven como arrays:

{
  "headers": [
    {
      "result": { "version": "HTTP/2", "code": 200, "reason": "" },
      "content-type": "text/html",
      "set-cookie": ["a=1; Path=/", "b=2; Path=/"]
    }
  ]
}

Esto es importante para los sitios que configuran cookies de sesión + rastreo + consentimiento en una sola response (la mayor parte del comercio electrónico).

Responses grandes: offload_large (por defecto: inline)

Por defecto (desde v0.2.0), los cuerpos de response completos se devuelven inline en structuredContent sin importar el tamaño. Esto funciona de forma predeterminada en cualquier cliente MCP.

Si tu cliente admite MCP resources/read Y quieres ahorrar tokens en páginas grandes, pasa offload_large: true por cada llamada a la herramienta. Las responses >= 50 KB se escriben luego en el disco, se devuelven como un resource_link y tu cliente obtiene el body solo cuando realmente lo necesita. En el servidor alojado, los payloads en caché caducan después de 1 hora. En tu propia instancia nada elimina los payloads almacenados: borra tú mismo los archivos con más de una hora del directorio de payloads.

Un resultado descargado incluye offloaded_resource_uri y size_bytes en lugar del body. Un resultado descargado también omite defense y profile en foura_proxy, por lo que debes omitir offload_large en una llamada que lea esos campos.

{
  "method": "GET",
  "url": "https://en.wikipedia.org/wiki/Web_scraping",
  "offload_large": true
}
Cliente offload_large: true
Claude Desktop todavía no, deja el valor por defecto false
Claude Code, Cursor, Windsurf compatible
Extensión MCP para VS Code compatible

Aislamiento por tenant: cada API key obtiene su propio espacio de nombres (sha256(apiKey)[:16]). Solo la key que almacenó un payload puede volver a leerlo. Las lecturas entre tenants devuelven Payload not found sin filtrar información sobre su existencia.

Prompts integrados

Seis plantillas de flujo de trabajo aparecen bajo /prompts en cualquier cliente MCP. Cada una acepta argumentos con nombre y devuelve un mensaje de usuario estructurado que orquesta una o más herramientas.

Prompt Argumentos Qué hace
smart_fetch url, opcional must_contain, extract Auto fetch (elige el método, gestiona la protección antibot), luego devuelve o extrae el contenido
scrape_product_page url Browser fetch, luego extrae el título del producto, precio, imagen, stock y SKU en formato JSON
extract_article url Single con fallback a proxy, luego elimina navegación y anuncios, devolviendo un JSON limpio del artículo
monitor_pricing url, opcional target_price Proxy fetch, extrae el precio actual y lo compara con el objetivo
check_endpoint_health url, opcional expected_text Single con validación estricta, devuelve accesibilidad y tiempos
bulk_fetch_urls urls (separadas por comas) Single en paralelo, fallback automático a proxy por cada URL, devuelve solo metadatos

Los prompts consumen cero tokens en reposo. Solo los prompts invocados ingresan al contexto del LLM.

Texto completo y prompts manuales de respaldo: Recetas de MCP.

Envoltorio de error

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

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

En errores de upstream con estado HTTP, status también está presente. En errores de rate limit y capacidad, el sobre de upstream agrega retryAfter, current.{concurrency, rpm} y limits.{maxConcurrency, maxRpm}. Consulta Errores de API para ver la estructura REST subyacente.

Valores estables de code:

Código HTTP Significado ¿Es seguro reintentar?
ssrf_blocked n/d El destino es una dirección privada o reservada (RFC 5735, 6598, IPv6 reservada), la URL no es http(s) o su nombre de host no se resolvió No, verifica la URL. Una resolución que falló brevemente se puede reintentar
upstream_non_json varía El upstream devolvió un cuerpo con formato incorrecto Quizás, investiga
output_validation_failed n/d El outputSchema del servidor MCP rechazó la respuesta de upstream, o la herramienta no pudo completar la llamada (no hay API key configurada, API inaccesible) Quizás: verifica la configuración y luego reporta
bad_request 400 Estructura de entrada rechazada, la URL de destino apunta a la propia API de FourA en lugar de a una página (solo se puede consultar /inspect allí), o la URL contiene un espacio sin codificar (codifícalo como %20) No, corrige los argumentos
auth_failed 401 Clave ausente, no válida o desactivada No, corrige la clave
forbidden 403 El destino respondió 403 y tu validate lo rechazó (una verificación del sitio, una restricción de país) No, o cambia a foura_proxy
not_found 404 Destino o endpoint no encontrado No
rate_limited 429 Límite de RPM alcanzado Sí, espera retryAfter
at_capacity 503 Límite de concurrencia alcanzado, o el servicio está desactivado por mantenimiento (error muestra Service disabled) Sí, espera retryAfter
service_disabled 503 Reservado. Un servicio desactivado por mantenimiento llega hoy como at_capacity, y una herramienta que tu plan no incluye devuelve plan_limit_feature Contacta a soporte
service_unavailable 503 503 genérico Sí, backoff corto
upstream_error 500+ o 0 El destino respondió con un error de servidor, o en foura_proxy, foura_browser y foura_auto nunca respondieron Sí, backoff exponencial
upstream_client_error 4xx Otro 4xx Por lo general no
upstream_unknown otro La solicitud se ejecutó pero no produjo una respuesta aceptada: en foura_single el destino nunca respondió (timeout, conexión rechazada), y en cualquier herramienta tu validate rechazó una respuesta 2xx o 3xx. Lee status y error Investiga
no_eligible_proxy n/d Ningún proxy coincide con el alcance estricto de exitCountries Reintenta más tarde; cambia el alcance solo de forma explícita
plan_limit_* 403 o 429 Uno de los límites de tu plan rechazó la llamada: plan_limit_ seguido de feature, premium, concurrency, rate, browser_daily, credits o bandwidth. Consulta Errores del servidor MCP Espera retryAfter cuando esté presente; de lo contrario, no hasta que el límite se reinicie o el plan cambie

Los agentes LLM pueden leer code directamente para la lógica de reintento sin analizar texto en prosa. Guía paso a paso de autenticación: Authentication.

Límites

  • Body inline de forma predeterminada. Con offload_large: true, las respuestas >= 50 KB se guardan en disco + resource_link (por tenant, TTL de 1 hora).
  • Los destinos privados se rechazan (RFC 5735, RFC 6598, bloques reservados de IPv6) en la capa MCP. Solo se reenvían hosts públicos.
  • Límite de body de request de 256 KB en requests /mcp entrantes (los payloads reales de MCP son < 4 KB).
  • La API de FourA aplica los rate limits por servicio. Consulta Rate Limits.

Autohospedaje

El código fuente completo del servidor es público en GitHub bajo @fouradata/mcp. Clona el repositorio, ejecuta npm install, npm run build y ejecuta node dist/http.js para levantar tu propia instancia. Se ejecuta sin estado en un único contenedor detrás de cualquier balanceador de carga.

Entorno configurable:

Variable Predeterminado Propósito
PORT 3076 Puerto de escucha HTTP
FOURA_API_BASE https://api.foura.ai/api URL base upstream de la API REST de FourA
FOURA_MCP_PAYLOADS_DIR una carpeta foura-mcp-payloads en el directorio temporal del sistema (el archivo Docker Compose incluido establece /data/payloads) Dónde se almacenan en caché en disco las respuestas >= 50 KB (con offload_large: true)
FOURA_MCP_ALLOWED_HOSTS mcp.foura.ai,localhost,127.0.0.1,[::1] Lista de permitidos de hostnames para el header Host (defensa contra DNS-rebinding)
FOURA_MCP_ALLOWED_ORIGINS https://mcp.foura.ai,https://claude.ai,https://app.cursor.sh,https://app.cursor.com Lista de permitidos de origen para llamadas desde el navegador

El contenedor oficial se ejecuta como uid 1001 (no root). El archivo Docker Compose incluido mantiene /data/payloads en un volumen con nombre; un bind mount del host en esa ruta debe tener permisos de escritura para ese uid.

Escala horizontalmente detrás de cualquier balanceador de carga. Los clientes proporcionan su token en cada request, por lo que no hay sesiones persistentes (sticky sessions). Con offload_large, apunta FOURA_MCP_PAYLOADS_DIR a un almacenamiento compartido por todas las instancias, ya que un payload almacenado reside en el disco de la instancia que lo escribió. GET /healthz responde con ok, name y version, lo que permite a un balanceador de carga sondear una instancia.

Actualizado: 13 de noviembre de 2026