MCP로 AI 에이전트에 CAPTCHA 해결 기능 추가하기

공식 @solvethree/sdk 다운로드에는 solvethree-mcp 실행 파일이 포함되어 있습니다. 아래 구성은 npx를 사용해 제공된 패키지 URL에서 이를 실행합니다. 입력할 호스팅 MCP 엔드포인트는 없습니다.

• MCP 호스트가 실행되는 환경에서 npx를 사용할 수 있도록 하세요.
• 호스트 환경에서 SOLVETHREE_API_KEY를 워크스페이스 API 키로 설정하세요. 브라우저 코드나 프롬프트에 넣지 마세요.
• 해당 환경에서 SOLVETHREE_PROXY를 설정하세요. reCAPTCHA 도구는 도구 요청이 아니라 이 변수에서 단일 프록시를 읽습니다.

JSON MCP 구성을 지원하는 호스트에서는 다음 서버 항목을 추가하세요.

{
  "mcpServers": {
    "solvethree": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz",
        "solvethree-mcp"
      ]
    }
  }
}

Codex에서는 대신 다음 TOML 구성을 사용하세요. env_vars 항목은 호스트 환경의 두 변수를 전달하며, 변수 값을 설정하지는 않습니다.

[mcp_servers.solvethree]
command = "npx"
args = ["--yes", "--package=https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz", "solvethree-mcp"]
env_vars = ["SOLVETHREE_API_KEY", "SOLVETHREE_PROXY"]
startup_timeout_sec = 60
tool_timeout_sec = 100

해당 환경 변수를 사용할 수 있는 상태에서 호스트를 시작하거나 다시 로드하세요. 호스트가 solvethree_capabilities, solvethree_create_recaptcha, solvethree_create_kasada, solvethree_create_tmpt, solvethree_get_task를 제공하는지 확인하세요.

reCAPTCHA 작업을 생성하기 전에 대상 사이트 프로필을 설정하고 워크스페이스에서 활성화되어 있는지 확인하세요. MCP를 통해 호스트 이름과 action을 보내는 것만으로는 해당 프로필이 생성되지 않습니다.

solvethree_capabilities로 사용 가능한 기능을 확인하세요. reCAPTCHA v3 Enterprise의 경우 다음 요청으로 solvethree_create_recaptcha를 호출하세요.

{
  "site": "accounts.example.com",
  "action": "login",
  "requestId": "agent-login-001",
  "waitMs": 0
}

accounts.example.com을 대상 사이트로, login을 애플리케이션에 필요한 action으로 바꾸세요. 이 논리적 작업에 사용할 requestId를 정하고 요청과 함께 보관하세요. waitMs가 0으로 설정되어 있으므로 이 호출에서 완료를 기다리지 말고 결과를 별도로 조회하세요.

기반 작업 API에서는 requestId 필드가 선택 사항이지만, 모든 MCP 생성 호출에는 필수입니다. ASCII 문자, 숫자, 밑줄 또는 하이픈을 1–64자 사용하세요.

1. 1.

   반환된 작업 ID 보관

   작업 생성 자체가 결과는 아닙니다. 에이전트가 동일한 작업을 조회할 수 있도록 작업 ID를 저장하세요.

2. 2.

   solvethree_get_task 호출

   생성 호출에서 반환된 작업 ID를 사용하세요. 상태가 pending 또는 solving이면 나중에 작업을 다시 조회하세요. 두 상태 모두 사용 가능한 솔루션을 포함하지 않습니다.

3. 3.

   최종 상태 처리

   ready 상태에서는 솔루션을 브라우저 또는 애플리케이션 연동에 전달하세요. failed 상태에서는 errorCode와 error를 확인하고 해당 작업의 폴링을 중단하세요.

reCAPTCHA의 경우 브라우저 또는 애플리케이션 요청을 통해 solution.token을 제출하세요. 반환된 userAgent와 secChUa로 요청의 User-Agent 및 sec-ch-ua 헤더를 설정하고, SOLVETHREE_PROXY에 구성된 프록시를 재사용하세요. 제공업체가 출구 IP를 순환시키는 경우 해당 프록시 세션을 고정하세요.

Kasada는 헤더를 반환하고 Ticketmaster TMPT는 원시 쿠키 값을 반환합니다. 요청한 작업에 맞는 출력을 적용하세요. 이 결과들은 서로 대체할 수 없습니다.

MCP 서버는 브라우저를 제어하거나 양식을 작성하지 않습니다. 호스트가 비공개 솔루션 데이터를 받고, 애플리케이션이 이를 제출합니다. 대상의 응답은 별도로 확인하세요. ready는 solvethree가 솔루션을 생성했다는 뜻이지, 대상이 이를 수락했다는 뜻은 아닙니다.

연결 시간 초과가 발생했다고 해서 작업 생성이 실패한 것은 아닙니다. 작업 ID를 받았다면 해당 작업을 조회하세요. 그렇지 않다면 동일한 requestId와 변경하지 않은 작업 입력으로 같은 생성 요청을 반복해 기존 작업을 복구하세요. 응답이 유실됐다는 이유만으로 새 ID를 생성하지 마세요.

같은 요청 ID를 다른 작업 입력과 함께 재사용하면 충돌이 발생합니다. 작업 자체가 실패했다면 무엇을 변경할지 결정하기 전에 오류를 확인하세요. 유효하지 않은 입력을 무작정 다시 제출해도 해결되지 않습니다. 요청 오류와 작업 실패의 차이는 CAPTCHA API 오류를 참고하세요.