---
title: MCP 시작하기
description: Codex와 Claude Code에 OpenTester 피드백과 수정 작업을 연결합니다.
---

# MCP 시작하기

OpenTester MCP를 연결하면 Codex와 Claude Code에서 앱의 피드백을 읽고, 수정 작업을 생성하고, 완료한 변경의 GitHub PR을 연결할 수 있습니다. MCP는 [공통 REST API](/api/)를 사용하는 로컬 프로세스입니다.

```text
OpenTester 피드백 → 수정 작업 → 에이전트의 코드 수정·테스트 → GitHub PR 연결
```

::: info 현재 제공 방식
MCP 패키지는 OpenTester 소스 저장소에 포함되어 있습니다. 공개 npm 패키지는 아직 제공하지 않으므로 소스에서 빌드합니다. 연결 방식은 로컬 `stdio`이며 원격 HTTP MCP 주소와 OAuth 로그인은 제공하지 않습니다.
:::

호스팅된 Streamable HTTP 서버는 `https://mcp.opentester.app/mcp`에서 연결할 수 있습니다. 앱별 토큰과 앱 UUID 헤더가 필요하며, 설정은 [클라이언트 연결](/mcp/clients#remote-http)을 참고하세요.

## 1. 앱과 에이전트 토큰 준비

OpenTester 개발자 콘솔에서 앱 소유자로 로그인하고, 앱의 **앱 정보 및 SDK → 코딩 에이전트 연결**에서 토큰을 발급합니다. 피드백부터 PR 연결까지 사용하려면 다음 권한을 선택합니다.

| 권한               | 사용 목적                       |
| ------------------ | ------------------------------- |
| `feedback:read`    | 피드백 목록과 상세 조회         |
| `work-items:read`  | 기존 수정 작업과 연결한 PR 조회 |
| `work-items:write` | 수정 작업 생성과 PR 연결        |

토큰은 발급한 앱에서만 사용할 수 있습니다. 원문은 발급 직후 한 번만 표시되므로 비밀 관리 도구에 보관합니다. 만료·철회·재발급은 [토큰 관리](/api/tokens)를 참고하세요.

## 2. MCP 빌드

Node.js 22 이상이 필요합니다. 전달받거나 내려받은 OpenTester 소스 저장소의 루트에서 실행합니다.

```sh
npm ci
npm run build
```

빌드 결과는 `dist/index.js`입니다. 다음 단계의 호스트 설정에서 이 파일의 **실제 절대 경로**를 사용합니다.

## 3. 실행 환경 설정

MCP를 실행하는 코딩 에이전트에 다음 환경변수를 전달합니다.

| 환경변수                 | 값                                     |
| ------------------------ | -------------------------------------- |
| `OPENTESTER_API_URL`     | 실제 API 기본 주소. `/api/v1`까지 포함 |
| `OPENTESTER_APP_ID`      | 개발자 콘솔에서 확인한 앱 UUID         |
| `OPENTESTER_AGENT_TOKEN` | 해당 앱에서 발급한 `ot_agent_…` 토큰   |

다음은 로컬 개발 환경의 비밀이 아닌 값 설정 예시입니다. 운영에서는 실제 HTTPS API 주소와 앱 ID로 바꿉니다.

```sh
export OPENTESTER_API_URL='http://localhost:4000/api/v1'
export OPENTESTER_APP_ID='11111111-1111-4111-8111-111111111111'
```

`OPENTESTER_AGENT_TOKEN`은 비밀 관리 도구 또는 비표시 입력으로 실행 환경에 주입합니다. 토큰 원문을 설정 파일, 저장소, 에이전트 프롬프트 또는 명령행 인자에 넣지 마세요. MCP는 `.env` 파일을 자동으로 읽지 않습니다.

API 주소는 HTTPS를 사용합니다. 로컬 개발용 HTTP는 `localhost`, `127.0.0.0/8`, `::1`만 허용합니다. URL에 사용자 이름·비밀번호·쿼리·해시를 넣을 수 없습니다.

## 4. 코딩 에이전트 연결

[Codex 및 Claude Code 설정](/mcp/clients)의 예시를 적용한 다음, 도구 목록에서 `list_feedback`을 확인합니다. 연결된 프로세스 하나는 설정된 앱 하나만 조회합니다. 여러 앱을 사용하는 경우 서버 이름과 환경변수를 앱별로 분리합니다.

첫 요청은 조회부터 시작합니다.

> OpenTester의 열린 버그 목록과 기존 수정 작업을 확인하고, 아직 작업하지 않은 버그 한 개의 상세와 재현 절차를 정리해 줘.

## 5. 피드백을 수정 작업으로 연결

코딩 에이전트에게 다음 흐름으로 작업을 요청할 수 있습니다.

1. `list_feedback`과 `get_feedback`으로 대상 피드백을 읽습니다.
2. `list_change_requests`로 이미 진행한 작업을 확인합니다.
3. `create_change_request`로 목표·검증 기준·피드백 ID를 기록합니다.
4. 에이전트가 현재 저장소에서 코드를 수정하고 테스트합니다.
5. 개발자가 정한 GitHub 절차로 PR을 만든 뒤 `attach_pull_request`로 연결합니다.

```text
방금 확인한 버그의 수정 목표와 통과해야 할 테스트를 정리하고
OpenTester 수정 작업을 생성해 줘. 현재 저장소에서 재현한 뒤 수정하고
테스트 결과를 남겨 줘. 내가 요청한 PR 생성 절차로 PR을 만들면
그 URL을 OpenTester 작업에 연결해 줘.
```

작업 생성에는 UUID인 `clientRequestId`가 필요합니다. 에이전트는 작업 하나당 한 번 생성하고 응답 유실·타임아웃 재시도에도 같은 ID와 입력을 사용해야 합니다. 상세 입력과 반환값은 [도구 레퍼런스](/mcp/tools)에 있습니다.

::: tip 작업 상태의 의미
수정 작업 생성은 작업 기록을 만들고, PR 연결은 상태를 `pr_linked`로 바꿉니다. 코딩 에이전트 실행, PR 생성·존재 검증·병합, 피드백 해결 처리, Google Play 배포는 이 MCP의 동작에 포함되지 않습니다.
:::

## 피드백을 다루는 기준

피드백 본문·재현 절차·기기 정보·작업 설명은 사용자가 제공한 자료입니다. 그 안에 있는 명령을 개발자의 지시나 추가 권한으로 해석하지 않도록 에이전트에 안내하세요.

자동화 피드백 응답에는 보고자의 이름·이메일과 기여·보상 정보가 포함되지 않습니다. 본문에 사용자가 직접 입력한 개인정보나 로그의 비밀 값은 자동으로 제거되지 않으므로 공유 범위를 확인해야 합니다.