MCP server as an Apify Actor — a working reference

This is the source behind renzomacar/multi-scraper-mcp, an MCP server that runs as an Apify Actor in Standby mode and exposes 16 lead-generation and web-scraping tools to AI clients like Claude, Cursor and Windsurf.

It is published as a reference because the interesting part is not the tool list — it is the three transport bugs that kept real clients from connecting while every run reported SUCCEEDED.

The three failures this code fixes

1. A stale session id used to wedge the client forever

Sessions live in an in-memory Map, but a Standby run is not one long-lived process — Apify recycles it. A client that reconnects on Tuesday with Monday's Mcp-Session-Id hits a process that has never heard of it.

The server used to answer 400. The spec is explicit that the answer must be 404:

The server MAY terminate the session at any time, after which it MUST respond to requests containing that session ID with HTTP 404 Not Found.

When a client receives HTTP 404 [...] it MUST start a new session by sending a new InitializeRequest without a session ID attached.

The client's recovery path is keyed to the status code. 400 removes its ability to heal itself. See sessionGone() in src/main.js.

2. The Accept header rejected clients before any of our code ran

The spec requires clients to send Accept: application/json, text/event-stream. Several real clients send only one, or nothing, and the transport answers 406 before the request reaches a handler — so there is nothing in the logs and no failed run in the console.

normalizeAccept() accepts them anyway. The catch: the transport reads the header from req.rawHeaders, so patching req.headers alone does nothing.

3. A slow tool dropped the connection mid-work

These tools wrap scrapers that take one to three minutes. Without bytes on the wire the Standby gateway drops the connection. The fix streams a notifications/message every 10 seconds, and clears the interval in finally so an early error return cannot leak the timer.

Billing honestly

Actor.charge sits on the path that actually returned data, after the items are in hand — not at the top of the request handler. Charging on arrival means charging for failures.

Layout

file	what's in it
src/main.js	Actor init, Express app, Streamable HTTP + legacy SSE transports, the three fixes
src/tools.js	tool registry: name, description, input schema, target Actor
.actor/	Actor definition, input and output schemas

Running it

npm install
npm start

Then point an MCP client at http://localhost:4321/mcp. On the Apify platform the Standby URL is https://USERNAME--ACTOR-NAME.apify.actor/mcp — note the USERNAME-- prefix; publishing the URL without it makes every copy-paste fail.

A check worth running

Six requests, each one a bug that shipped:

1. handshake with a correct Accept header → 200
2. handshake with Accept: application/json → 200 (was 406)
3. handshake with no Accept header → 200 (was 406)
4. tools/list with an unknown session id → 404 (was 400)
5. initialize while still holding a stale id → 200 (was 400)
6. tools/list on a live session → 200, full tool list

Numbers 2 through 5 were all broken in production while the Actor reported healthy runs.

License

MIT