Sorun Giderme

Çoğu kurulum hatası dört gruba ayrılır: API anahtarı sunucuya ulaşmıyor, mcp-remote köprüsü başlamıyor, repo çözümlenemiyor ya da istemci hiç bağlanamıyor. Belirtinize uyan bölümü izleyin.

API anahtarı sorunları#

Her istek, Authorization: Bearer header'ı olarak gönderilen API anahtarınızla kimlik doğrular. Araç çağrıları reddediliyorsa:

• Anahtarınızın mgv_ önekiyle başladığını doğrulayın.
• Yapılandırma örneklerindeki mgv_xxxx yer tutucusunu app.maguyva.ai adresinden aldığınız gerçek anahtarınızla değiştirdiğinizi kontrol edin.
• Yapılandırmanız anahtarı MAGUYVA_API_KEY değerinden okuyorsa, değişkenin istemcinizin gerçekten başlatıldığı ortamda ayarlandığını doğrulayın. ~/.zshrc veya ~/.bashrc dosyasına eklenen shell export'ları yalnızca shell yeniden yüklendikten sonra geçerli olur — ve GUI uygulamaları bunları hiç devralmayabilir. Şüphedeyseniz, anahtarı yapılandırmanın env bloğuna koyun.
• Anahtarın süresinin dolmadığından ya da iptal edilmediğinden emin olun.

mcp-remote köprü sorunları#

Belgelenen istemci yapılandırmalarının çoğu, stdio MCP trafiğini uzak sunucuya ileten yerel bir köprü süreci başlatır:

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

Sunucu istemcinizde hiç görünmüyorsa ya da görünüp hemen bağlantısı kesiliyorsa:

• npx değerinin PATH'inizde bulunduğunu doğrulayın — köprünün çalışan bir Node.js kurulumuna ihtiyacı var. Başlayıp başlamadığını doğrulamak için bir terminalde npx -y mcp-remote --help çalıştırın.
• İstemcinizin MCP yapılandırma sözdizimini kontrol edin — biçimsiz bir JSON dosyası bazı istemcilerde sessizce başarısız olur.
• Birçok istemcinin köprüye hiç ihtiyacı yoktur. Claude Code, Maguyva eklentisini kullanır (/plugin install maguyva@maguyva) ve Cursor, VS Code, Windsurf ile Zed, uzak sunucuya bir Bearer header'ıyla doğrudan bağlanır (Zed, context_servers üzerinden). Köprü yalnızca Claude Desktop'ın yalnızca-OAuth connector'ları gibi yerel uzak-header desteği olmayan istemciler içindir.

Repo bulunamadı#

• app.maguyva.ai içinde deponun bağlı ve indekslenmiş olduğunu doğrulayın.
• Biçimi kontrol edin: "owner/repo" varsayılan dalı hedefler, "owner/repo:branch" belirli bir dalı hedefler (örn. "owner/repository:develop").
• Hesabınızın depoya erişimi olduğundan emin olun.
• Depo çözümlemesini incelemek için repository_context(action="info", repository="...") kullanın; depo parametresini yalnızca MCP istemciniz bir istek varsayılanı sağladığında veya anahtar tam olarak bir depoya erişebildiğinde atlayın.

MCP bağlantı sorunları#

• Makinenizden https://maguyva.tools/mcp adresine bağlantıyı test edin — kurumsal proxy'ler ve güvenlik duvarları genellikle asıl suçludur.
• API token'ınızın geçerli ve süresi dolmamış olduğunu kontrol edin.
• İstemciniz için istemci yapılandırmasını Kurulum Rehberi ile yeniden kontrol edin — yapılandırma dosyasının konumu ve biçimi istemciye göre değişir.

Düzeltmeyi doğrulayın#

Herhangi bir değişiklikten sonra ajanınıza "Hangi repolar bağlı?" diye sorun — bu, bağlantıyı uçtan uca doğrular. Ardından reponuz hakkında gerçek bir soru sorun; bağlı reponuzdan dosya yolları ve satır numaralarıyla cevaplar görmelisiniz.