MCP-Server als Apify-Actor – eine funktionierende Referenz

Dies ist die Quelle hinter renzomacar/multi-scraper-mcp, einem MCP-Server, der als Apify-Actor im Standby-Modus läuft und 16 Tools zur Lead-Generierung und zum Web-Scraping für KI-Clients wie Claude, Cursor und Windsurf bereitstellt.

Es ist als Referenz veröffentlicht, weil der interessante Teil nicht die Tool-Liste ist – sondern die drei Transportfehler, die echte Clients daran hinderten, sich zu verbinden, während jeder Lauf SUCCEEDED meldete.

Die drei Fehler, die dieser Code behebt

1. Eine veraltete Sitzungs-ID blockierte den Client dauerhaft

Sitzungen leben in einer In-Memory-Map, aber ein Standby-Lauf ist kein langlebiger Prozess – Apify recycelt ihn. Ein Client, der sich am Dienstag mit der Mcp-Session-Id von Montag wieder verbindet, trifft auf einen Prozess, der davon nie gehört hat.

Der Server antwortete früher mit 400. Die Spezifikation ist eindeutig, dass die Antwort 404 sein muss:

Der Server KANN die Sitzung jederzeit beenden, danach MUSS er auf Anfragen mit dieser Sitzungs-ID mit HTTP 404 Not Found antworten.

Wenn ein Client HTTP 404 [...] erhält, MUSS er eine neue Sitzung starten, indem er eine neue InitializeRequest ohne angehängte Sitzungs-ID sendet.

Der Wiederherstellungspfad des Clients ist an den Statuscode gekoppelt. 400 nimmt ihm die Fähigkeit, sich selbst zu heilen. Siehe sessionGone() in src/main.js.

2. Der Accept-Header lehnte Clients ab, bevor unser Code überhaupt lief

Die Spezifikation verlangt, dass Clients Accept: application/json, text/event-stream senden. Mehrere echte Clients senden nur eines oder gar nichts, und der Transport antwortet mit 406, bevor die Anfrage einen Handler erreicht – es gibt also nichts in den Logs und keinen fehlgeschlagenen Lauf in der Konsole.

normalizeAccept() akzeptiert sie trotzdem. Der Haken: Der Transport liest den Header aus req.rawHeaders, daher bewirkt das Patchen von req.headers allein nichts.

3. Ein langsames Tool ließ die Verbindung mitten in der Arbeit abbrechen

Diese Tools umschließen Scraper, die ein bis drei Minuten dauern. Ohne Bytes auf der Leitung verwirft das Standby-Gateway die Verbindung. Der Fix streamt alle 10 Sekunden eine notifications/message und löscht das Intervall in finally, damit eine frühe Fehlerrückgabe den Timer nicht leaken kann.

Related MCP server: ZapFetch MCP Server

Ehrliche Abrechnung

Actor.charge sitzt auf dem Pfad, der tatsächlich Daten zurückgab, nachdem die Elemente in der Hand sind – nicht am Anfang des Request-Handlers. Das Abrechnen bei Ankunft bedeutet, für Fehler zu berechnen.

Aufbau

Ausführen

npm install
npm start

Richten Sie dann einen MCP-Client auf http://localhost:4321/mcp. Auf der Apify-Plattform lautet die Standby-URL https://USERNAME--ACTOR-NAME.apify.actor/mcp – beachten Sie das Präfix USERNAME--; wenn Sie die URL ohne dieses veröffentlichen, schlägt jedes Kopieren und Einfügen fehl.

Ein Test, der sich lohnt

Sechs Anfragen, jede davon ein Fehler, der ausgeliefert wurde:

1. Handshake mit korrektem Accept-Header → 200

2. Handshake mit Accept: application/json → 200 (war 406)

3. Handshake ohne Accept-Header → 200 (war 406)

4. tools/list mit unbekannter Sitzungs-ID → 404 (war 400)

5. initialize während noch eine veraltete ID gehalten wird → 200 (war 400)

6. tools/list auf einer aktiven Sitzung → 200, vollständige Tool-Liste

Die Nummern 2 bis 5 waren alle in der Produktion defekt, während der Actor gesunde Läufe meldete.

Lizenz

MIT