समस्या निवारण

ज़्यादातर सेटअप विफलताएँ चार श्रेणियों में आती हैं: API कुंजी सर्वर तक नहीं पहुँच रही, @maguyva/mcp ब्रिज शुरू नहीं हो रहा, रिपॉज़िटरी रिज़ॉल्व नहीं हो पा रही, या क्लाइंट बिल्कुल कनेक्ट नहीं हो पा रहा। जो सेक्शन आपके लक्षण से मेल खाता है, उस पर काम करें।

हर रिक्वेस्ट आपकी API कुंजी से ऑथेंटिकेट होती है, जो एक Authorization: Bearer हेडर के रूप में भेजी जाती है — या, अगर कोई क्लाइंट वह हेडर सेट नहीं कर सकता, तो एक X-API-Key हेडर के रूप में। अगर टूल कॉल अस्वीकार हो रहे हैं:

• जाँच लें कि आपकी कुंजी mgv_ प्रीफ़िक्स से शुरू होती है।
• जाँच लें कि आपने कॉन्फ़िग उदाहरणों के mgv_xxxx प्लेसहोल्डर को app.maguyva.ai से मिली अपनी असली कुंजी से बदला है।
• अगर आपका कॉन्फ़िग MAGUYVA_API_KEY से कुंजी पढ़ता है, तो पुष्टि करें कि यह वेरिएबल उस एनवायरनमेंट में सेट है जहाँ से आपका क्लाइंट असल में लॉन्च होता है। ~/.zshrc या ~/.bashrc में जोड़े गए शेल एक्सपोर्ट शेल रीलोड करने के बाद ही लागू होते हैं — और संभव है कि 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 टोकन वैध है और उसकी समय-सीमा समाप्त नहीं हुई है।
• अपने क्लाइंट के लिए इंस्टॉलेशन गाइड के मुक़ाबले क्लाइंट कॉन्फ़िग दोबारा जाँचें — कॉन्फ़िग फ़ाइल की लोकेशन और संरचना हर क्लाइंट में अलग होती है।

किसी भी बदलाव के बाद, अपने एजेंट से "मेरे पास कौन-सी रिपॉज़िटरी कनेक्टेड हैं?" पूछें — यह कनेक्शन को शुरू से आख़िर तक वेरिफ़ाई कर देता है। फिर अपनी रिपॉज़िटरी के बारे में कोई असली सवाल पूछें; आपको अपनी कनेक्टेड रिपॉज़िटरी से फ़ाइल पाथ और लाइन नंबर के साथ जवाब दिखने चाहिए।