Pemecahan Masalah

Sebagian besar kegagalan setup terbagi dalam empat kelompok: API key tidak sampai ke server, bridge mcp-remote tidak berjalan, repository tidak bisa ditemukan, atau klien sama sekali tidak bisa terhubung. Kerjakan bagian yang sesuai dengan gejalamu.

Masalah API key#

Setiap request diautentikasi dengan API key-mu, dikirim sebagai header Authorization: Bearer. Kalau tool call ditolak:

• Pastikan key-mu diawali dengan prefix mgv_.
• Periksa apakah kamu sudah mengganti placeholder mgv_xxxx di contoh config dengan key aslimu dari app.maguyva.ai.
• Kalau config-mu membaca key dari MAGUYVA_API_KEY, pastikan variabel itu sudah diset di environment tempat klienmu 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, taruh key-nya di blok env pada config.
• Pastikan key-nya belum kedaluwarsa atau dicabut.

Masalah bridge mcp-remote#

Sebagian besar config klien yang terdokumentasi menjalankan proses bridge lokal yang meneruskan trafik stdio MCP ke server remote:

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

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

• Pastikan npx tersedia di PATH-mu — bridge-nya butuh instalasi Node.js yang berfungsi. Jalankan npx -y mcp-remote --help di terminal untuk memastikan itu bisa berjalan.
• Periksa sintaks konfigurasi MCP klienmu — 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, Windsurf, serta Zed terhubung ke server remote secara native dengan header Bearer (Zed lewat context_servers). Bridge-nya hanya untuk klien tanpa dukungan native remote-header, seperti connector OAuth-only milik Claude Desktop.

Repository tidak ditemukan#

• 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 ketika klien MCP Anda menyediakan default untuk permintaan tersebut atau kunci dapat mengakses tepat satu repository.

Masalah koneksi MCP#

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

Verifikasi perbaikannya#

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