mcp-worker-starter

Cloudflare Workers용 최소한의 Model Context Protocol 서버입니다. 의존성 없음, 파일 하나, 일반 POST만 사용합니다.

저는 인증된 도구를 통해 실시간 비즈니스 데이터를 Claude에 노출하는 MCP 서버를 프로덕션에서 운영하고 있습니다. 이 스타터는 그 서버에서 비즈니스 로직을 빼내고 흉터만 남긴 것입니다.

MCP 서버의 해피 패스는 약 40줄입니다. 공개할 가치가 있는 부분은 아래의 세 가지 함정입니다. 각 함정은 조용히 발생하며, 그중 하나는 제 제품 두 개를 중단시켰습니다.

장애를 부르는 405

MCP 클라이언트는 서버 푸시 메시지를 수신하기 위해 Accept: text/event-stream 헤더를 단 GET 요청을 엽니다. 서버가 SSE를 지원하지 않으면 프로토콜은 405로 응답하라고 요구합니다. 그 상태 코드는 다시 열지 말라는 신호입니다.

저는 200이 오류보다 더 도움이 될 것 같아서, 친절한 JSON 본문과 함께 200으로 응답했습니다.

클라이언트는 그 200을 종료된 스트림으로 해석하고 재연결했습니다. 즉시요. 백오프도 없이, 그리고 제가 눈여겨본 어디에서도 오류가 드러나지 않은 채로요.

하루 만에 201,936건의 요청. 그 바람에 Cloudflare 계정 전체의 일일 요청 할당량이 소진됐고, 그 계정을 공유하던 전혀 무관한 두 번째 제품이 함께 중단됐습니다. MCP 서버 자체는 오류를 하나도 기록하지 않았습니다. 서버 쪽에서는 아무 문제가 없었기 때문입니다. 201,936번의 모든 요청에 올바르게 응답하고 있었으니까요.

프로토콜이 405를 기대하는 자리에서의 200은 더 친절한 응답이 아닙니다. 예의 바른 무한 루프입니다.

if ((request.headers.get("accept") ?? "").includes("text/event-stream")) {
  return new Response(JSON.stringify({ error: "This server does not expose an SSE stream. Use POST." }), {
    status: 405,
    headers: { "content-type": "application/json; charset=utf-8", allow: "POST" },
  });
}

Related MCP server: Remote MCP Server (Authless)

알림에는 id가 없고, 본문도 없어야 한다

JSON-RPC 알림은 발사 후 망각(fire-and-forget)입니다. id 없이 도착하며 호출자는 응답을 기다리지 않습니다. 여기에 {"jsonrpc":"2.0","result":{}}로 답하면 엄격한 클라이언트는 이 교환을 잘못된 형식으로 간주합니다. 아무도 요청하지 않은 것에 응답했기 때문입니다.

202와 빈 본문이 '수신했습니다. 할 말은 없습니다'에 해당하는 올바른 응답입니다.

if (id === undefined || id === null) return new Response(null, { status: 202 });

클라이언트의 protocolVersion을 그대로 응답하기

initialize 시 클라이언트가 제시한 protocolVersion을 그대로 돌려보내고, 자신의 버전을 하드코딩하지 마세요. 하드코딩하면 오늘은 동작하지만 클라이언트가 업데이트되는 그 주에 조용히 동작을 멈추는 핸드셰이크가 됩니다. 클라이언트가 아무것도 지정하지 않았을 때만 기본값으로 폴백하세요.

사용하기

npm install
npx wrangler dev

curl -s http://localhost:8787 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq

배포:

npx wrangler deploy

그런 다음 배포된 URL을 클라이언트의 MCP 서버로 추가하세요. 이 서버는 POST로 통신합니다.

나만의 도구 추가

src/index.ts의 TOOLS 배열을 편집하세요. 보기보다 중요한 두 가지 규칙이 있습니다.

• description이 곧 프롬프트입니다. 모델은 그것을 읽고 도구를 선택합니다. 코드를 볼 수 없고 스키마를 두 번 읽지 않을 독자를 위해 작성하세요.

• 산문이 아니라 데이터를 반환하세요. 모델은 여러분이 JSON에 대해 어떤 말을 하려는지 추측하는 것보다, 여러분의 JSON을 더 잘 설명합니다.

인증과 속도 제한

둘 다 기본적으로 꺼져 있으므로 별도 설정 없이 스타터를 실행할 수 있습니다.

토큰 인증은 MCP_TOKEN을 설정하면 켜집니다. 이후 요청에는 Authorization: Bearer <token>을 포함해야 합니다.

npx wrangler secret put MCP_TOKEN

시간당 속도 제한은 KV 네임스페이스를 RATE_LIMIT으로 바인딩하면 켜집니다. 기본 상한선은 시간당 300건입니다. 프로덕션에서는 호출자를 식별하는 항목을 키로 사용해 전역이 아니라 테넌트별로 상한을 둡니다.

[[kv_namespaces]]
binding = "RATE_LIMIT"
id = "your-kv-namespace-id"

여기서 속도 제한은 과도한 의심이 아닙니다. 첫 번째 함정은 상한선이 있었다면 하루가 아니라 몇 분 만에 잡았을 실패의 형태와 정확히 일치합니다.

이것이 아닌 것

SDK도, 프레임워크도 아니고, 그렇게 되려고 하지도 않습니다. 모든 기능이 포함된 무언가를 원한다면 공식 TypeScript SDK나 Cloudflare의 Agents SDK를 사용하세요.

이것은 서버 전체를 한 번에 읽고 그것이 정확히 무엇을 하는지 알고 싶은 경우를 위한 것입니다.

테스트

npm test

핸드셰이크, 도구 왕복, 그리고 세 가지 함정 각각을 다룹니다. 어느 하나라도 회귀가 생기면 비용이 커질 때까지 보이지 않기 때문입니다.

라이선스

MIT