문제 해결

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

API 키 문제#

모든 요청은 Authorization: Bearer 헤더로 전송되는 API 키로 인증됩니다. 도구 호출이 거부된다면:

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

mcp-remote 브리지 문제#

문서화된 대부분의 클라이언트 설정은 stdio MCP 트래픽을 원격 서버로 전달하는 로컬 브리지 프로세스를 실행합니다:

npx -y mcp-remote https://maguyva.tools/mcp --header "Authorization: Bearer ${MAGUYVA_API_KEY}"

서버가 클라이언트에 전혀 나타나지 않거나, 나타났다가 즉시 연결이 끊긴다면:

• npx가 PATH에서 사용 가능한지 확인하세요 — 브리지는 정상 작동하는 Node.js 설치가 필요합니다. 터미널에서 npx -y mcp-remote --help를 실행해 시작되는지 확인하세요.
• 클라이언트의 MCP 설정 문법을 확인하세요 — 잘못된 형식의 JSON 파일은 일부 클라이언트에서 조용히 실패합니다.
• 많은 클라이언트는 브리지가 아예 필요하지 않습니다. Claude Code는 Maguyva 플러그인(/plugin install maguyva@maguyva)을 사용하고, Cursor, VS Code, Windsurf, Zed는 Bearer 헤더로 원격 서버에 네이티브 연결합니다(Zed는 context_servers를 통해). 브리지는 Claude Desktop의 OAuth 전용 커넥터처럼 네이티브 원격 헤더를 지원하지 않는 클라이언트에만 필요합니다.

저장소를 찾을 수 없음#

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

MCP 연결 문제#

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

수정 사항 확인하기#

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