테마
MCP 오류 해결
연결 오류는 프로세스 시작 → API 통신 → 토큰 권한 → 도구 입력 순서로 확인합니다. 토큰 원문을 진단 로그나 에이전트 대화에 붙여 넣지 마세요.
서버가 시작되지 않음
| 확인 항목 | 조치 |
|---|---|
| Node 실행 파일을 찾지 못함 | Node.js 22 이상을 설치하고 호스트 설정의 command를 실제 실행 파일 경로로 지정 |
dist/index.js를 찾지 못함 | 저장소 루트에서 npm ci, npm run build 실행 후 args의 절대 경로 확인 |
OPENTESTER_API_URL 설정 오류 | 절대 URL, /api/v1 접미사, HTTPS 여부 확인. URL의 인증 정보·쿼리·해시 제거 |
OPENTESTER_APP_ID 설정 오류 | 앱 이름이나 Android 패키지 이름 대신 콘솔의 앱 UUID 사용 |
OPENTESTER_AGENT_TOKEN 설정 오류 | 앱에서 발급한 에이전트 토큰 사용. SDK 토큰이나 웹 세션 쿠키는 사용할 수 없음 |
.env 파일이 있어도 서버는 자동으로 읽지 않습니다. MCP 호스트가 세 환경변수를 실제 자식 프로세스에 전달해야 합니다. 데스크톱 앱에서만 실패한다면 터미널과 앱의 환경변수·PATH 차이를 확인합니다.
도구가 보이지 않음
Codex에서는 codex mcp list 또는 /mcp, Claude Code에서는 claude mcp list 또는 /mcp로 서버 상태를 확인합니다. 설정 파일을 수정했다면 호스트에서 서버를 다시 연결하세요.
OpenTester MCP는 로컬 stdio 서버입니다. HTTP MCP 주소를 입력하거나 OAuth 로그인을 시작하는 설정과는 맞지 않습니다. 클라이언트 연결 예시의 실행 파일 기반 설정을 사용합니다.
패키지 버전 0.1.0은 MCP SDK v2 stdio 진입점을 사용하며 현재 프로토콜과 2025 초기화 방식의 클라이언트를 지원합니다. 클라이언트가 다른 초기화 방식을 요구하면 호스트와 MCP 패키지 버전을 함께 확인하세요.
도구 오류 코드
API·통신 오류는 MCP 결과에 isError: true로 표시됩니다. 아래는 structuredContent 예시입니다.
json
{
"error": {
"code": "forbidden",
"message": "This token cannot perform this action for this app. Check its scopes and app ownership.",
"status": 403
}
}HTTP 응답을 받은 오류에만 status가 포함됩니다. API 오류 본문은 그대로 전달하지 않고 고정된 오류 메시지를 반환합니다.
| 코드 | 원인 · 조치 |
|---|---|
invalid_request | API가 입력을 거절함. UUID, 문자열 길이, 중복 피드백 ID와 허용 필드 확인 |
unauthenticated | 토큰이 잘못되었거나 만료·철회됨. 콘솔에서 새 토큰을 발급하고 서버 재연결 |
forbidden | 앱 범위·권한·소유권 불일치. 토큰의 앱과 OPENTESTER_APP_ID, 필요한 scope 확인 |
not_found | 해당 앱에 피드백 또는 수정 작업이 없음. 목록에서 실제 ID 재확인 |
conflict | 같은 요청 ID의 내용이 달라졌거나 작업에 다른 PR이 연결됨. 저장된 작업 조회 |
request_too_large | API 요청 크기 제한 초과. 긴 설명을 줄이거나 작업 분리 |
rate_limited | 요청 제한 초과. 잠시 기다린 후 재시도 |
api_unavailable | API가 요청을 완료하지 못함. 서비스 상태를 확인하고 재시도 |
timeout | API 요청이 15초 안에 완료되지 않음. 쓰기가 성공했을 수 있으므로 같은 ID·입력으로 재시도 |
connection_failed | API에 연결할 수 없음. API 주소, 실행 상태, 네트워크 확인 |
redirect_refused | API가 다른 주소로 이동시킴. 최종 API 주소를 직접 설정 |
response_too_large | 응답이 4 MiB 초과. 목록의 limit을 줄임 |
invalid_response | API 응답이 비었거나 JSON 객체가 아님. 로그인 페이지·프록시 주소 대신 실제 API인지 확인 |
internal_error | 예상하지 못한 서버 오류. 실행 환경과 서비스 상태 확인 |
잘못된 도구 입력은 API 호출 전에 MCP 입력 검증에서 거절될 수도 있습니다. 이 경우 도구 레퍼런스의 필드와 타입을 먼저 확인하세요.
목록은 읽히지만 작업을 만들 수 없음
feedback:read만 있는 토큰은 피드백만 조회할 수 있습니다. 작업 목록·상세는 work-items:read, 작업 생성·PR 연결은 work-items:write가 필요합니다. 필요한 범위로 새 토큰을 발급한 뒤 환경변수를 바꾸고 MCP를 다시 연결합니다.
작업 생성 후 응답을 받지 못함
네트워크가 끊겨도 서버에는 작업이 저장되었을 수 있습니다. 같은 clientRequestId와 원래 입력으로 재시도하면 기존 결과를 받을 수 있습니다. 새로운 요청 ID를 생성해 반복 호출하지 마세요.
동일한 내용이라도 다른 clientRequestId는 별도 작업이 됩니다. 이 식별자는 에이전트 간 작업 배정이나 잠금 기능이 아니므로, 시작 전에 기존 수정 작업을 조회하는 흐름을 유지합니다.
PR을 연결했는데 피드백이 열려 있음
정상 동작입니다. PR 연결은 수정 작업의 상태를 pr_linked로 바꾸며, 피드백을 fixed로 처리하지 않습니다. GitHub PR의 실제 상태를 동기화하거나 Play Console에 배포하는 기능도 포함하지 않습니다. 코드 검증과 배포 후 개발자 콘솔에서 피드백 상태를 관리합니다.
리다이렉트와 로컬 네트워크
토큰이 다른 주소로 전달되지 않도록 서버는 API 리다이렉트를 따라가지 않습니다. HTTP에서 HTTPS로 이동시키는 주소라면 처음부터 최종 HTTPS 주소를 설정하세요.
평문 HTTP는 루프백 주소만 허용합니다. http://192.168.… 같은 LAN 주소나 공용 호스트를 사용하려면 HTTPS로 제공해야 합니다.