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.
Inicio rápido: stdio local (recomendado para Claude Desktop)
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+Qen 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ásmeta({ rung, solved, attempts, credits, attemptsByEngine, browserRequests }, siempre presente, donderunges uno decache,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 incluyeexitClass.meta.attemptsByEnginecuenta las requests que la llamada envió a Single, Proxy y Browser, ymeta.browserRequestscuenta las que consumieron tu cuota diaria de Browser. Un fallo también incluyeattemptReport. No incluyetotal_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 incluyeexitCountry, una request que especificó una clase incluyeexitClass, una rotación que cambió la familia de navegador incluyeprofile, y un fallo incluyeattemptReportfoura_browser: estructura distinta{ status, headers: object, body, cookies, userAgent }(nota:bodypuede 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:premiumcuando una salida premium atendió la llamada. Enfoura_singleyfoura_browser, esto sucede cuandoproxyreproduce una salida premium quefoura_proxyofoura_autoencontraron.
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
/mcpentrantes (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.