# 문제 해결

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

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).

Maguyva 설정에서 흔히 발생하는 문제를 해결하세요: API 키 문제, @maguyva/mcp 브리지 문제, 저장소 조회, 연결 오류.

### API 키 문제

- 키가 mgv_ 접두사로 시작하는지 확인하세요.
- 설정 예시의 mgv_xxxx 플레이스홀더를 app.maguyva.ai에서 발급받은 실제 키로 교체했는지 확인하세요.
- 설정이 MAGUYVA_API_KEY에서 키를 읽어온다면, 클라이언트가 실제로 실행되는 환경에 그 변수가 설정되어 있는지 확인하세요. ~/.zshrc나 ~/.bashrc에 추가한 셸 export는 셸을 다시 불러온 후에만 적용되며, GUI 앱은 아예 상속받지 못할 수도 있습니다. 확실하지 않다면 키를 설정에 직접 넣으세요. 네이티브 원격 설정에서는 Authorization 헤더(Bearer 뒤에 키)에, @maguyva/mcp 브리지 설정에서는 env 블록에 넣습니다.
- 키가 만료되거나 취소되지 않았는지 확인하세요.

### @maguyva/mcp 브리지 문제

- npx가 PATH에서 사용 가능한지 확인하세요 -- 브리지는 정상 작동하는 Node.js 설치가 필요합니다. 터미널에서 npx -y @maguyva/mcp --help를 실행해 시작되는지 확인하세요.
- 클라이언트의 MCP 설정 문법을 확인하세요 -- 잘못된 형식의 JSON 파일은 일부 클라이언트에서 조용히 실패합니다.
- 많은 클라이언트는 브리지가 아예 필요하지 않습니다. Claude Code는 Maguyva 플러그인(/plugin install maguyva@maguyva)을 사용하고, Cursor, VS Code, Devin Desktop, Zed는 Bearer 헤더로 원격 서버에 네이티브 연결합니다(Zed는 context_servers를 통해). 브리지는 설정에서 그 헤더를 보낼 수 없는 클라이언트를 위한 것입니다. 예를 들어 Claude Desktop의 claude_desktop_config.json는 로컬 서버만 실행합니다. Claude Desktop 사용자 지정 커넥터는 authorization 요청 헤더를 보낼 수 있지만, 요청 헤더는 일부 조직에만 제공되는 베타 기능입니다.

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

- 저장소가 app.maguyva.ai에 연결되어 인덱싱되었는지 확인하세요.
- 형식을 확인하세요: "owner/repo"는 기본 브랜치를 지정하고, "owner/repo:branch"는 특정 브랜치를 지정합니다(예: "owner/repository:develop").
- 계정이 해당 저장소에 접근 권한이 있는지 확인하세요.
- 저장소 이름의 해석 결과를 살펴보려면 repository_context(action="info", repository="...")을(를) 사용하세요. MCP 클라이언트가 요청 기본값을 제공하거나 키가 정확히 하나의 저장소에만 접근할 수 있을 때만 저장소 매개변수를 생략하세요.

### MCP 연결 문제

- 여러분의 기기에서 https://maguyva.tools/mcp로의 연결을 테스트하세요 -- 회사 프록시와 방화벽이 흔한 원인입니다.
- API 토큰이 유효하고 만료되지 않았는지 확인하세요.
- 클라이언트의 설치 가이드와 설정을 다시 대조해 보세요 -- 설정 파일 위치와 구조는 클라이언트마다 다릅니다.

### 수정 사항 확인하기

변경 후에는 에이전트에게 "제가 연결한 저장소는 무엇인가요?"라고 물어보세요 -- 연결을 처음부터 끝까지 검증할 수 있습니다. 그다음 저장소에 관한 실제 질문을 하나 던져보세요. 연결된 저장소의 파일 경로와 줄 번호가 포함된 답변을 볼 수 있어야 합니다.