Apify Actor로서의 MCP 서버 — 동작하는 레퍼런스

이 문서는 renzomacar/multi-scraper-mcp의 소스입니다. Standby 모드의 Apify Actor로 실행되며 Claude, Cursor, Windsurf 같은 AI 클라이언트에 16개의 리드 생성 및 웹 스크래핑 도구를 제공하는 MCP 서버입니다.

레퍼런스로 공개된 이유는 흥미로운 부분이 도구 목록이 아니기 때문입니다. 모든 실행이 SUCCEEDED로 보고되는 동안 실제 클라이언트의 연결을 막았던 세 가지 전송(transport) 버그가 바로 그 핵심입니다.

이 코드가 해결하는 세 가지 실패

1. 오래된 세션 ID가 클라이언트를 영원히 멈추게 했던 문제

세션은 메모리 내 Map에 저장되지만, Standby 실행은 오래 지속되는 단일 프로세스가 아닙니다. Apify가 이를 재활용하기 때문입니다. 월요일의 Mcp-Session-Id로 화요일에 다시 연결하는 클라이언트는 그 ID를 전혀 모르는 프로세스를 만나게 됩니다.

서버는 이전에 400으로 응답했습니다. 스펙은 응답이 404여야 한다고 명시합니다:

서버는 언제든지 세션을 종료할 수 있으며(MAY), 이후 해당 세션 ID가 포함된 요청에는 HTTP 404 Not Found로 응답해야 합니다(MUST).

클라이언트가 HTTP 404 [...]를 수신하면 세션 ID를 첨부하지 않은 새 InitializeRequest를 보내 새 세션을 시작해야 합니다(MUST).

클라이언트의 복구 경로는 상태 코드에 따라 결정됩니다. 400은 클라이언트의 자가 복구 능력을 제거합니다. src/main.js의 sessionGone()을 참조하세요.

2. Accept 헤더가 우리 코드가 실행되기 전에 클라이언트를 거부했던 문제

스펙은 클라이언트가 Accept: application/json, text/event-stream을 보내도록 요구합니다. 실제 클라이언트 중 일부는 하나만 보내거나 아무것도 보내지 않으며, 전송 계층은 요청이 핸들러에 도달하기 전에 406으로 응답합니다. 따라서 로그에는 아무것도 남지 않고 콘솔에도 실패한 실행이 표시되지 않습니다.

normalizeAccept()는 어쨌든 이를 수락합니다. 문제는 전송 계층이 req.rawHeaders에서 헤더를 읽기 때문에 req.headers만 패치하는 것으로는 아무 효과가 없다는 점입니다.

3. 느린 도구가 작업 중에 연결을 끊었던 문제

이 도구들은 1~3분이 걸리는 스크래퍼를 감쌉니다. 전선 위에 바이트가 없으면 Standby 게이트웨이가 연결을 끊습니다. 수정은 10초마다 notifications/message를 스트리밍하고, finally에서 인터벌을 정리하여 조기 오류 반환이 타이머를 누출하지 못하게 합니다.

Related MCP server: ZapFetch MCP Server

정직한 과금

Actor.charge는 항목을 확보한 후 실제로 데이터를 반환한 경로에 위치하며, 요청 핸들러의 맨 위에 있지 않습니다. 도착 시 과금하는 것은 실패에 대해 과금하는 것을 의미합니다.

구조

실행 방법

npm install
npm start

그런 다음 MCP 클라이언트를 http://localhost:4321/mcp에 연결합니다. Apify 플랫폼에서 Standby URL은 https://USERNAME--ACTOR-NAME.apify.actor/mcp입니다. USERNAME-- 접두사를 주의하세요. 이 접두사 없이 URL을 공개하면 모든 복사-붙여넣기가 실패합니다.

실행해 볼 가치가 있는 검사

각각 배포된 버그에 해당하는 여섯 가지 요청:

1. 올바른 Accept 헤더로 핸드셰이크 → 200

2. Accept: application/json으로 핸드셰이크 → 200 (이전에는 406)

3. Accept 헤더 없이 핸드셰이크 → 200 (이전에는 406)

4. 알 수 없는 세션 ID로 tools/list → 404 (이전에는 400)

5. 오래된 ID를 유지한 채 initialize → 200 (이전에는 400)

6. 활성 세션에서 tools/list → 200, 전체 도구 목록

2번부터 5번까지는 Actor가 정상 실행을 보고하는 동안 프로덕션에서 모두 손상되어 있었습니다.

라이선스

MIT