# 설치 가이드

Canonical source: https://maguyva.ai/ko/docs/installation

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

5분 이내에 시작할 수 있습니다. 이 가이드는 Claude Code, Claude Desktop, Cursor, VS Code, Devin Desktop, Codex CLI, GitHub Copilot CLI, Gemini CLI, Cline, Goose, Continue, LM Studio, Kiro CLI, JetBrains, Zed, Trae, OpenCode, BoltAI, LibreChat, Antigravity, Claude Cowork, ChatGPT, 그리고 Warp 등을 포함한 23개 MCP 클라이언트의 설정 방법을 다룹니다.

**사전 준비물**: [app.maguyva.ai](https://app.maguyva.ai)에서 발급받은 API 키와 연결된 GitHub 저장소가 필요합니다.

## 환경 설정

먼저 API 키를 환경 변수에 설정합니다. MCP 클라이언트가 요청 기본값을 제공하거나 키가 정확히 하나의 저장소에만 접근할 수 있으면 `repository`을(를) 생략하고, 그 외에는 명시적으로 전달합니다.

### macOS/Linux (Bash/Zsh)

```bash
export MAGUYVA_API_KEY="mgv_xxxx"
```

### Windows (PowerShell)

```powershell
'$Env:MAGUYVA_API_KEY="mgv_xxxx"' | Out-File -Append $PROFILE
. $PROFILE
```

`mgv_xxxx`를 [app.maguyva.ai](https://app.maguyva.ai)에서 발급받은 실제 API 키로 교체하세요.

## 클라이언트 설정

아래에서 사용하는 MCP 클라이언트를 선택하면 구체적인 설정 방법을 확인할 수 있습니다.

```json
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

Maguyva는 표준 MCP를 사용합니다. 위에 자체 가이드가 없더라도, 이 프로토콜을 지원하는 클라이언트라면 무엇이든 연결할 수 있습니다. 23개 클라이언트의 설정 문서가 있으며, 계속 추가되고 있습니다.

## 설정 검증하기

연결한 후, 에이전트에게 몇 가지 질문을 던져보세요:

- "제가 연결한 저장소는 무엇인가요?" — 연결이 작동하는지 확인합니다
- "이 코드베이스에서 인증은 어떻게 처리되나요?" — 시맨틱 검색을 테스트합니다
- "데이터베이스를 호출하는 모든 함수를 찾아줘" — 의존성 검색을 테스트합니다
- "UserService 클래스는 무엇에 의존하나요?" — 심볼 조회를 테스트합니다

연결된 저장소의 파일 경로와 줄 번호가 포함된 결과를 볼 수 있어야 합니다. 그렇지 않다면 아래의 [troubleshooting](https://maguyva.ai/ko/docs/troubleshooting)를 확인하세요.

## 저장소 형식

저장소를 지정할 때:

- 브랜치 지정: `"owner/repo:branch"` (e.g. `"owner/repository:develop"`)
- 기본 브랜치: `"owner/repo"`

**팁**: `repository_context(action="info", repository="...")`로 저장소 이름이 어떻게 해석되는지 확인하세요. 저장소를 재지정한 값은 현재 호출에만 적용됩니다.

## 문제 해결

### API 키 문제

- 키가 mgv_ 접두사로 시작하는지 확인하세요
- 키가 환경에 올바르게 설정되어 있는지 확인하세요
- 키가 만료되지 않았는지 확인하세요

### 저장소를 찾을 수 없음

- 저장소가 app.maguyva.ai에 연결되어 있는지 확인하세요
- owner/repo 형식이 올바른지 확인하세요
- 저장소에 접근 권한이 있는지 확인하세요

### MCP 연결 문제

- 클라이언트에서 @maguyva/mcp 브리지를 사용한다면 PATH에서 npx를 실행할 수 있는지 확인하세요
- API 토큰이 유효하고 만료되지 않았는지 확인하세요
- https://maguyva.tools/mcp로의 연결을 테스트하세요
- 클라이언트의 MCP 설정 문법을 확인하세요

## 다음 단계

- MCP API 레퍼런스: 전체 API 문서
- 작동 방식: 컨텍스트 최적화 이해하기
- 문제 해결: 설정 및 연결 문제 해결하기