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

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

API कुंजी समस्याएँ#

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

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

फ़िक्स को वेरिफ़ाई करें#

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