---
title: MCP 오류 해결
description: OpenTester MCP 연결, 인증, 권한, 재시도 문제를 해결합니다.
---

# MCP 오류 해결 {#mcp-troubleshooting}

연결 오류는 **프로세스 시작 → API 통신 → 토큰 권한 → 도구 입력** 순서로 확인합니다. 토큰 원문을 진단 로그나 에이전트 대화에 붙여 넣지 마세요.

## 서버가 시작되지 않음 {#server-does-not-start}

| 확인 항목                          | 조치                                                                                         |
| ---------------------------------- | -------------------------------------------------------------------------------------------- |
| 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` 차이를 확인합니다.

## 도구가 보이지 않음 {#tools-do-not-appear}

Codex에서는 `codex mcp list` 또는 `/mcp`, Claude Code에서는 `claude mcp list` 또는 `/mcp`로 서버 상태를 확인합니다. 설정 파일을 수정했다면 호스트에서 서버를 다시 연결하세요.

원격 HTTP는 `https://mcp.opentester.app/mcp`와 앱별 토큰·앱 UUID 헤더를 사용합니다. 로컬 stdio는 [클라이언트 연결 예시](/ko/mcp/clients)의 실행 파일 설정을 사용합니다. 두 방식 모두 MCP OAuth 로그인은 지원하지 않습니다.

패키지 버전 `0.1.0`은 MCP SDK v2 stdio 진입점을 사용하며 현재 프로토콜과 2025 초기화 방식의 클라이언트를 지원합니다. 클라이언트가 다른 초기화 방식을 요구하면 호스트와 MCP 패키지 버전을 함께 확인하세요.

## 도구 오류 코드 {#tool-error-codes}

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 입력 검증에서 거절될 수도 있습니다. 이 경우 [도구 레퍼런스](/ko/mcp/tools)의 필드와 타입을 먼저 확인하세요.

## 목록은 읽히지만 작업을 만들 수 없음 {#reads-succeed-but-creation-fails}

`feedback:read`만 있는 토큰은 피드백만 조회할 수 있습니다. 작업 목록·상세는 `work-items:read`, 작업 생성·PR 연결은 `work-items:write`가 필요합니다. 필요한 범위로 [새 토큰을 발급](/ko/api/tokens)한 뒤 환경변수를 바꾸고 MCP를 다시 연결합니다.

## 작업 생성 후 응답을 받지 못함 {#no-response-after-creating-work}

네트워크가 끊겨도 서버에는 작업이 저장되었을 수 있습니다. 같은 `clientRequestId`와 원래 입력으로 재시도하면 기존 결과를 받을 수 있습니다. 새로운 요청 ID를 생성해 반복 호출하지 마세요.

동일한 내용이라도 다른 `clientRequestId`는 별도 작업이 됩니다. 이 식별자는 에이전트 간 작업 배정이나 잠금 기능이 아니므로, 시작 전에 기존 수정 작업을 조회하는 흐름을 유지합니다.

## PR을 연결했는데 피드백이 열려 있음 {#feedback-stays-open-after-linking-a-pr}

정상 동작입니다. PR 연결은 수정 작업의 상태를 `pr_linked`로 바꾸며, 피드백을 `fixed`로 처리하지 않습니다. GitHub PR의 실제 상태를 동기화하거나 Play Console에 배포하는 기능도 포함하지 않습니다. 코드 검증과 배포 후 개발자 콘솔에서 피드백 상태를 관리합니다.

## 리다이렉트와 로컬 네트워크 {#redirects-and-local-networks}

토큰이 다른 주소로 전달되지 않도록 서버는 API 리다이렉트를 따라가지 않습니다. HTTP에서 HTTPS로 이동시키는 주소라면 처음부터 최종 HTTPS 주소를 설정하세요.

평문 HTTP는 루프백 주소만 허용합니다. `http://192.168.…` 같은 LAN 주소나 공용 호스트를 사용하려면 HTTPS로 제공해야 합니다.