Servidor MCP como un Actor de Apify — una referencia funcional

Este es el código fuente detrás de renzomacar/multi-scraper-mcp, un servidor MCP que se ejecuta como un Actor de Apify en modo Standby y expone 16 herramientas de generación de prospectos y extracción web a clientes de IA como Claude, Cursor y Windsurf.

Se publica como referencia porque la parte interesante no es la lista de herramientas — son los tres errores de transporte que impidieron que clientes reales se conectaran mientras cada ejecución reportaba SUCCEEDED.

Los tres fallos que este código corrige

1. Un ID de sesión obsoleto atascaba al cliente para siempre

Las sesiones viven en un Map en memoria, pero una ejecución en Standby no es un proceso de larga duración — Apify lo recicla. Un cliente que se reconecta el martes con el Mcp-Session-Id del lunes se encuentra con un proceso que nunca ha oído hablar de él.

El servidor solía responder 400. La especificación es explícita en que la respuesta debe ser 404:

El servidor PUEDE terminar la sesión en cualquier momento, después de lo cual DEBE responder a las solicitudes que contengan ese ID de sesión con HTTP 404 Not Found.

Cuando un cliente recibe HTTP 404 [...] DEBE iniciar una nueva sesión enviando una nueva InitializeRequest sin ID de sesión adjunto.

La ruta de recuperación del cliente está vinculada al código de estado. 400 elimina su capacidad de autocuración. Véase sessionGone() en src/main.js.

2. El encabezado Accept rechazaba a los clientes antes de que nuestro código se ejecutara

La especificación requiere que los clientes envíen Accept: application/json, text/event-stream. Varios clientes reales envían solo uno, o ninguno, y el transporte responde 406 antes de que la solicitud llegue a un manejador — por lo que no hay nada en los registros ni ninguna ejecución fallida en la consola.

normalizeAccept() los acepta de todas formas. El detalle: el transporte lee el encabezado de req.rawHeaders, así que modificar solo req.headers no hace nada.

3. Una herramienta lenta cortaba la conexión a mitad del trabajo

Estas herramientas envuelven scrapers que tardan de uno a tres minutos. Sin bytes en el cable, la puerta de enlace de Standby corta la conexión. La corrección transmite un notifications/message cada 10 segundos, y limpia el intervalo en finally para que un retorno temprano por error no pueda filtrar el temporizador.

Related MCP server: ZapFetch MCP Server

Cobrando con honestidad

Actor.charge se encuentra en la ruta que realmente devolvió datos, después de que los elementos están en mano — no al inicio del manejador de solicitudes. Cobrar al llegar significa cobrar por fallos.

Estructura

Cómo ejecutarlo

npm install
npm start

Luego apunta un cliente MCP a http://localhost:4321/mcp. En la plataforma de Apify la URL de Standby es https://USUARIO--NOMBRE-ACTOR.apify.actor/mcp — nota el prefijo USUARIO--; publicar la URL sin él hace que cada copiar-y-pegar falle.

Una verificación que vale la pena ejecutar

Seis solicitudes, cada una un error que se envió a producción:

1. handshake con un encabezado Accept correcto → 200

2. handshake con Accept: application/json → 200 (era 406)

3. handshake sin encabezado Accept → 200 (era 406)

4. tools/list con un ID de sesión desconocido → 404 (era 400)

5. initialize mientras aún se mantiene un ID obsoleto → 200 (era 400)

6. tools/list en una sesión activa → 200, lista completa de herramientas

Los números 2 a 5 estaban fallando en producción mientras el Actor reportaba ejecuciones saludables.

Licencia

MIT