시작되지 않거나 작업을 해결하지 못하는 MCP 서버 문제 해결

MCP 호스트가 실행되는 컴퓨터의 터미널에서 제공된 실행기를 실행하세요. 조건을 통제해 재현하려면 Node.js 22와 여기에 포함된 npx를 사용하고, 별도로 설치된 이전 실행기가 선택되지 않았는지 확인하세요.

node --version
npx --yes --package=https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz solvethree-mcp
# The process waits for JSON-RPC on stdin. Silence is not a failed startup.
# Use the MCP host to initialize and list tools. Press Ctrl-C to stop this check.
# Never paste an API key or proxy password into troubleshooting logs.

아무것도 출력하지 않은 채 계속 실행 중인 프로세스가 반드시 멈춘 것은 아닙니다. 이 서버는 로컬 stdio 서버로, stdin에서 MCP JSON-RPC 메시지를 기다립니다. MCP 호스트를 사용해 연결을 초기화하고 도구 목록을 조회하세요. 실행 파일만 실행해서는 이 핸드셰이크가 수행되지 않습니다.

프로세스가 종료되면 먼저 실행 오류를 읽어 보세요. 실행 파일을 찾을 수 없다는 오류는 설치 또는 PATH 문제를 가리키며, 패키지 다운로드 오류는 작업 해결 전에 발생합니다. 어느 쪽도 API 키, 프록시 또는 사이트 프로필이 잘못되었다는 증거는 아닙니다.

solvethree를 원격 HTTP 엔드포인트가 아닌 로컬 stdio 서버로 등록하세요. 호스트는 실행기 예제에 표시된 인수로 npx를 실행해야 합니다. 호스팅된 MCP 엔드포인트는 없습니다.

호스트가 npx를 찾을 수 없습니다.

호스트의 PATH와 터미널의 PATH를 비교하세요. 데스크톱 애플리케이션은 셸 설정을 상속받지 않을 수 있습니다.

다음을 시도해 보세요: 호스트에서 npx가 있는 디렉터리에 접근할 수 있도록 하거나, 로컬에서 작동한 동일한 실행 파일의 절대 경로를 구성하세요.

호스트가 다른 버전의 Node.js 또는 npx를 실행합니다.

터미널에서 사용하는 버전만 보지 말고 호스트가 실제로 어떤 실행 파일을 찾는지 확인하세요.

다음을 시도해 보세요: 호스트가 테스트를 마친 설치본을 사용하도록 지정하세요. 환경을 변경한 후에는 호스트를 다시 시작하세요.

초기화 시 잘못된 형식의 JSON 또는 예상치 못한 출력이 보고됩니다.

stdout에 기록되는 셸 배너, 래퍼 메시지 또는 디버그 출력을 찾아보세요.

다음을 시도해 보세요: stdout은 MCP JSON-RPC 전용으로 유지하세요. 진단 출력은 stderr로 보내면 호스트가 이를 프로토콜 트래픽으로 취급하지 않고 수집할 수 있습니다.

시작 중 호스트가 대기를 중단합니다.

시작 로그를 살펴보고 실행이 느린 것인지, 프로세스가 이미 종료된 것인지 구분하세요.

다음을 시도해 보세요: Codex 스타일 구성에서는 문서에 명시된 startup_timeout_sec 값인 60을 사용하세요. 더 오래 기다려도 누락된 실행 파일이나 명시적인 실행 오류가 해결되지는 않습니다.

호스트가 solvethree 도구가 등록되지 않았다고 표시합니다.

서버가 초기화되었는지 확인하고 도구 검색으로 반환된 도구를 살펴보세요.

다음을 시도해 보세요: 서버 등록을 수정하거나 다시 연결해 도구를 다시 검색하세요. 도구 누락은 API 인증 오류나 해결 실패가 아닙니다.

서버는 solvethree_capabilities, solvethree_create_recaptcha, solvethree_create_kasada, solvethree_create_tmpt, solvethree_get_task를 제공합니다. 검색에는 성공했지만 호스트가 이 이름 중 하나를 호출할 수 없다면, 작업 요청을 보내기 전에 해당 불일치를 해결하세요.

1. 1.

   호스트 프로세스의 환경 확인

   호스트 환경을 통해 SOLVETHREE_API_KEY와 SOLVETHREE_PROXY를 제공하세요. 별도 터미널에서 변수를 내보냈다고 해서 호스트가 해당 변수를 읽을 수 있는 것은 아닙니다. Codex 방식의 설정에서는 env_vars에 두 이름을 모두 포함해야 합니다. 이 전달 목록 자체가 값을 제공하지는 않습니다. 키나 프록시 인증 정보를 출력하지 않고 값의 존재 여부를 확인하세요.

2. 2.

   도구가 실제로 읽는 위치에서 프록시 확인

   solvethree_create_recaptcha는 SOLVETHREE_PROXY에서 단일 프록시를 읽습니다. 환경 값이 누락되었을 때 이 도구에 proxy 인수를 추가하는 방식으로 해결하려 하지 마세요. 프록시 URL은 HTTP 또는 HTTPS를 사용해야 하며 경로, 쿼리, 프래그먼트가 없어야 합니다.

3. 3.

   reCAPTCHA 사이트 프로필 확인

   API 키로 식별되는 워크스페이스에는 요청한 사이트와 reCAPTCHA 유형에 대한 활성 프로필이 필요합니다. 캡처 액션도 확인하세요. 호스트 이름에 대한 일반 프로필 하나가 모든 액션을 처리하는 것은 아닙니다. 작업에 site와 action을 제공해도 프로필이 생성되지는 않습니다. 콘솔의 사이트 프로필 페이지나 프로필 설정 가이드를 통해 해결하세요.

4. 4.

   도구 입력값 확인

   solvethree_create_recaptcha에는 호스트 이름 형태의 site, action, requestId를 제공하세요. recaptchaType은 선택 사항이며 기본값은 enterprise-v3입니다. site 대신 페이지 URL을 넣거나 이 도구에 API의 다른 작업 유형을 추가하지 마세요.

기능 검색은 인증이나 프록시 액세스를 테스트하지 않습니다. capabilities 호출이 성공한 뒤 발생하는 인증 또는 요청 유효성 검사 오류는 실행기가 아니라 해결 요청의 문제입니다. 응답을 성공한 작업 페이로드로 취급하기 전에 성공이 아닌 HTTP 응답을 처리하세요.

호스트 시간 초과는 작업 상태가 아닙니다. Codex 방식의 설정은 tool_timeout_sec 값으로 100을 사용하지만, 응답을 받지 못했다고 해서 작업 생성이 실패했다고 단정할 수는 없습니다. 각 생성 도구에는 requestId가 필요하며 최대 하나의 작업을 생성합니다.

작업 ID를 받았다면 해당 작업을 조회하세요. 그렇지 않으면 동일한 requestId로 동일한 생성 요청을 반복해 기존 작업을 복구하세요. 호출 시간이 초과되었다는 이유만으로 새 requestId를 생성하지 마세요. 작업 입력값을 변경한 채 ID를 재사용하면 충돌이 발생합니다.

작업이 준비되면 반환된 브라우저 식별 정보와 성공한 프록시를 사용해 솔루션을 제출하세요. 이후 웹사이트에서 요청을 거부한다면 MCP 시작 과정이 아니라 해당 제출을 조사하세요. 솔루션 데이터는 비공개로 유지하세요. MCP 호스트가 이 데이터를 수신합니다.