문제 해결

대부분의 설정 실패는 네 가지 범주로 나뉩니다: API 키가 서버에 도달하지 못하거나, @maguyva/mcp 브리지가 시작되지 않거나, 저장소를 찾을 수 없거나, 클라이언트가 아예 연결되지 않는 경우입니다. 증상에 맞는 섹션을 확인하세요.

모든 요청은 Authorization: Bearer 헤더로, 클라이언트가 해당 헤더를 설정할 수 없는 경우에는 X-API-Key 헤더로 전송되는 API 키로 인증됩니다. 도구 호출이 거부된다면:

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

클라이언트에서 @maguyva/mcp 브리지를 사용하면 Maguyva의 원격 서버에 연결하는 로컬 프로세스를 시작합니다:

MAGUYVA_API_KEY=mgv_xxxx npx -y @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 클라이언트가 요청 기본값을 제공하거나 키가 정확히 하나의 저장소에만 접근할 수 있을 때만 저장소 매개변수를 생략하세요.

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

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