Pemecahan Masalah

Sebagian besar kegagalan setup terbagi dalam empat kelompok: kunci API tidak sampai ke server, bridge @maguyva/mcp tidak berjalan, repository tidak bisa ditemukan, atau klien sama sekali tidak bisa terhubung. Kerjakan bagian yang sesuai dengan gejala Anda.

Setiap request diautentikasi dengan kunci API Anda, dikirim sebagai header Authorization: Bearer atau, kalau sebuah client tidak bisa menyetelnya, sebagai header X-API-Key. Kalau tool call ditolak:

• Pastikan key Anda diawali dengan prefix mgv_.
• Periksa apakah Anda sudah mengganti placeholder mgv_xxxx di contoh config dengan key asli Anda dari app.maguyva.ai.
• Kalau config Anda membaca key dari MAGUYVA_API_KEY, pastikan variabel itu sudah diset di environment tempat klien Anda benar-benar dijalankan. Shell export yang ditambahkan ke ~/.zshrc atau ~/.bashrc baru berlaku setelah shell-nya di-reload — dan aplikasi GUI mungkin tidak mewarisinya sama sekali. Kalau ragu, tulis key-nya langsung di config: di header Authorization pada config remote native (Bearer diikuti key Anda), atau di blok env pada config bridge @maguyva/mcp.
• Pastikan key-nya belum kedaluwarsa atau dicabut.

Jika klien memakai penghubung @maguyva/mcp, klien menjalankan proses lokal yang terhubung ke server jarak jauh Maguyva:

MAGUYVA_API_KEY=mgv_xxxx npx -y @maguyva/mcp

Kalau server tidak pernah muncul di klien Anda, atau muncul lalu langsung terputus:

• Pastikan npx tersedia di PATH Anda — bridge-nya butuh instalasi Node.js yang berfungsi. Jalankan npx -y @maguyva/mcp --help di terminal untuk memastikan itu bisa berjalan.
• Periksa sintaks konfigurasi MCP klien Anda — file JSON yang salah format gagal secara diam-diam di beberapa klien.
• Banyak klien yang sama sekali tidak butuh bridge-nya. Claude Code memakai plugin Maguyva (/plugin install maguyva@maguyva), dan Cursor, VS Code, Devin Desktop, serta Zed terhubung ke server remote secara native dengan header Bearer (Zed lewat context_servers). Bridge-nya untuk klien yang tidak bisa mengirim header itu dari config-nya, seperti Claude Desktop, yang file claude_desktop_config.json-nya hanya menjalankan server lokal. Custom connector di Claude Desktop bisa mengirim request header authorization, tapi request header masih beta untuk sejumlah organisasi terbatas.

• Pastikan repository terhubung dan terindeks di app.maguyva.ai.
• Periksa format: "owner/repo" menargetkan branch default, "owner/repo:branch" menargetkan branch tertentu (mis. "owner/repository:develop").
• Pastikan akun Anda memiliki akses ke repository.
• Gunakan repository_context(action="info", repository="...") untuk memeriksa resolusi repository; jangan sertakan parameter repository hanya jika klien MCP Anda menyediakan default untuk permintaan atau kunci dapat mengakses tepat satu repository.

• Uji konektivitas ke https://maguyva.tools/mcp dari mesin Anda — proxy korporat dan firewall biasanya jadi biang keladinya.
• Periksa apakah token API Anda valid dan belum kedaluwarsa.
• Cek ulang config klien Anda terhadap Panduan Instalasi untuk klien Anda — lokasi dan bentuk file config-nya berbeda-beda tiap klien.

Setelah melakukan perubahan apa pun, tanyakan ke agen Anda "Repository apa saja yang terhubung ke akun saya?" — itu memverifikasi koneksinya dari ujung ke ujung. Lalu ajukan pertanyaan sungguhan soal repo Anda; Anda harus melihat jawaban dengan path file dan nomor baris dari repository yang terhubung.