MCP 서버에서 429 대신 402를 반환하는 방법

지난주 저는 sentry-mcp 이슈 #844를 읽으면서 제가 계속해서 겪고 있는 고통을 정확히 설명하는 한 사람을 보았습니다. 그는 Cursor를 사용하여 Sentry MCP에 대해 병렬 자동화 (parallel automation)를 실행했고, 몇 초 만에 분당 60회 요청 제한 (60-request-per-minute bucket)을 가득 채웠으며, Retry-After 헤더가 없는 429 상태 코드를 받았습니다. 그의 에이전트 (agent)는 그저 거기 멈춰 서 있었습니다. 백오프 (backoff) 힌트도, 탈출 경로도 없었으며, 실행을 실패하고 사람이 직접 관리하도록 요청하는 것 외에는 할 수 있는 게 아무것도 없었습니다.

같은 주에 awslabs/mcp #2949 이슈가 발생했는데, 여기서는 tools/list가 두 번째 호출에서 429를 발생시켜 MCP 핸드셰이크 (handshake) 자체가 실패하고 있었습니다. 또한 GLips/Figma-Context-MCP #258에서는 사람들이 MCP가 고장 났다고 확신했지만, 실제로는 그들의 병렬 호출이 공유 자격 증명 (shared credentials)에 대한 Figma의 토큰당 제한 (per-token limit)을 초과했을 뿐이었습니다.

매번 같은 형태입니다. 서버가 에이전트가 활용할 수 없는 방식으로

유료 액세스의 경우:

HTTP/1.1 402 Payment Required
WWW-Authenticate: L402 macaroon="...", invoice="lnbc30n1p..."

두 방식 모두 결정론적 (deterministic)입니다. 에이전트는 챌린지 (challenge)를 읽고, 작업(CPU 사이클 또는 Lightning 결제)을 수행한 뒤, 정답을 제출하여 토큰을 얻습니다. 사람의 개입 (human in the loop)은 필요 없습니다. 백오프 (backoff) 간격을 추측할 필요도 없습니다. 서버가 에이전트에게 정확히 무엇을 해야 할지 알려주었기 때문입니다.

기존 MCP 서버 래핑하기 (Wrapping)

@powforge/captcha-mcp는 암호 기술을 직접 작성하지 않고 이를 구현할 수 있는 한 가지 방법입니다. 이 패키지는 challenge, verify, status라는 세 가지 도구 (tools)를 노출합니다. 이 패키지는 captcha.powforge.dev를 백엔드로 래핑하므로 퍼즐 서비스를 직접 호스팅할 필요가 없습니다.

Claude Code 또는 Cursor 설정에 다음과 같이 추가하세요:

{
  "mcpServers": {
    "powforge-captcha": {
...

그 다음 여러분의 백엔드에서 호출자가 속도 제한 (rate-limited)이 걸린 엔드포인트에 접속하면, verify 경로를 가리키는 402 응답을 반환합니다. 에이전트가 퍼즐을 풀고 토큰을 얻으면, 백엔드에서 이를 확인합니다:

curl -X POST https://captcha.powforge.dev/api/token/verify \
  -H "Content-Type: application/json" \
  -d '{"token":"<verify-tool에서 받은 토큰>"}'

토큰이 유효하면 요청이 통과됩니다. 토큰이 잘못되었거나 만료되었다면, 새로운 챌린지와 함께 다시 402를 반환합니다.

에이전트가 보는 모습

에이전트의 관점에서 루프 (loop)는 짧습니다:

1. 도구를 호출합니다. 챌린지가 포함된 402 응답을 받습니다.
2. challenge 도구를 호출하여 새로운 퍼즐을 얻습니다 (또는 402에서 직접 받은 것을 사용합니다).
3. 14개의 선행 제로 비트 (leading zero bits)를 가진 SHA-256 해시를 생성하는 논스 (nonce)를 찾기 위해 5~10초 동안 CPU를 사용합니다.
4. 논스와 함께 verify를 호출합니다. 5분간 유효한 HMAC 서명된 액세스 토큰 (access token)을 받습니다.
5. 토큰을 사용하여 원래 호출을 재시도합니다. 실제 응답을 얻습니다.

에이전트는 사람에게 물어볼 필요가 없었습니다. 재시도 간격을 추측할 필요도 없었습니다. CPU 사이클로 액세스 비용을 지불하고 통과한 것입니다.

PoW 또는 Lightning

호출자가 누구인지에 따라 선택하십시오. PoW (무료 티어, SHA-256, 14비트 선행 제로 기준 약 5~10초의 CPU 소요)는 간헐적인 에이전트 (agents), 탐색 실행 (exploration runs), 그리고 무료 티어 사용자들에게 매우 효과적입니다. 비용은 실제적이지만 작으며, 호출자가 자원을 얼마나 원하는지에 따라 확장됩니다.

Lightning을 통한 L402 (유료 티어, 기본적으로 호출당 3 sats)는 CPU를 소모하기보다 현금을 지불하는 것을 선호하는 대량 호출자들에게 더 합리적입니다. 대부분의 에이전트 운영자들은 퍼즐을 건너뛰기 위해 기꺼이 몇 satoshi를 지불할 것입니다.

동일한 엔드포인트에서 두 가지 방식을 모두 제공할 수 있습니다. 402 응답은 에이전트에게 무엇을 사용할 수 있는지 알려주며, 에이전트는 자신의 제약 조건에 따라 선택합니다.

직접 시도해보기

npx -y @powforge/captcha-mcp

패키지 및 문서: https://www.npmjs.com/package/@powforge/captcha-mcp

현재 429 응답을 반환하고 있는 MCP 서버를 운영 중이라면, 응답을 실제 챌린지 (challenge)가 포함된 402로 교체하십시오. 여러분의 에이전트 호출자들은 읽을 수 없는 Wait 헤더에서 멈춰 있는 대신, 실제로 실행을 완료함으로써 여러분에게 감사할 것입니다.