विषय-सूची

आपने एक MCP (Model Context Protocol) सर्वर सेट किया, लेकिन /mcp खोलने पर वह कुछ इस तरह की स्थिति में अटका दिखता है — परिचित लगता है?

/mcp

  filesystem      ✓ connected      (12 tools)
  github          ✗ failed
  notion          △ needs authentication
  my-server       ⏸ pending approval

MCP, Claude Code को "हाथ" देता है — बाहरी टूल्स (फ़ाइल ऑपरेशन, GitHub, डेटाबेस, विभिन्न API) — लेकिन इसके कनेक्शन आपकी सोच से कहीं ज़्यादा बार अटक जाते हैं। कारण तीन परिवारों में बँटते हैं: "लोकल सबप्रोसेस लॉन्च फेल्योर," "रिमोट ऑथेंटिकेशन," और "कॉन्फ़िग फ़ाइल की गलतियाँ," और /mcp का स्टेटस आपको बताता है कि यह कौन-सा है। यह लेख स्टेटस कैसे पढ़ें, कारण-दर-कारण उपाय, सबसे बड़ा Windows जाल, और डायग्नोस्टिक वर्कफ़्लो — आधिकारिक जानकारी के आधार पर समझाता है।

सबसे पहले मुख्य बातें। (1) पहले /mcp (और claude mcp list) से स्टेटस देखें — failed (लॉन्च फेल्योर), needs authentication (ऑथेंटिकेशन), और pending approval (अनुमोदन की प्रतीक्षा) — इन सबके उपाय पूरी तरह अलग हैं। (2) लोकल (stdio) के लिए आम दोषी होते हैं पाथ और एनवायरनमेंट वेरिएबल, साथ ही Windows की npx समस्या। (3) रिमोट (HTTP) के लिए आम दोषी OAuth होता है। (4) अटक जाएँ तो claude --debug mcp चलाकर सर्वर का एरर आउटपुट (stderr) देखें। व्यवहार और डिफ़ॉल्ट वर्ज़न के साथ बदलते हैं, इसलिए नवीनतम आधिकारिक डॉक्स से पुष्टि करें।

CLAUDE CODE · MCP STATUS

स्टेटस ही उपाय बता देता है

— failed / needs auth / pending — हर एक का इलाज अलग है

$ /mcp
✓ filesystem connected · 12 tools
✗ github failed → लॉन्च · पाथ · npx
△ notion needs auth → /mcp OAuth
⏸ my-server pending → इसे अनुमोदित करें

✗ failed = लोकल लॉन्च की समस्या, △ needs auth = रिमोट ऑथेंटिकेशन, ⏸ pending = अनुमोदन की प्रतीक्षा।
"कनेक्ट नहीं हो रहा" को एक साथ न समेटें — पहले स्टेटस से वर्गीकृत करें; यही सबसे छोटा रास्ता है।

1. यह एरर आपको क्या बता रहा है

MCP सर्वर मोटे तौर पर दो कनेक्शन प्रकारों में आते हैं। (1) stdio (लोकल) — Claude Code आपकी मशीन पर सर्वर की कमांड को एक सबप्रोसेस के रूप में लॉन्च करता है और स्टैंडर्ड I/O के ज़रिए बात करता है। (2) HTTP (रिमोट) — यह एक क्लाउड सर्वर से URL द्वारा जुड़ता है (पुराना SSE अब अप्रचलित है)। "कनेक्ट नहीं हो रहा" का मतलब प्रकार के आधार पर बहुत बदलता है।

लोकल (stdio) फेल्योर लगभग हमेशा "कमांड खुद ही लॉन्च नहीं हो पाई" होता है — गलत पाथ, npx का रिज़ॉल्व न होना (खासकर Windows पर), या किसी ज़रूरी एनवायरनमेंट वेरिएबल की कमी से सर्वर का तुरंत क्रैश हो जाना। रिमोट (HTTP) फेल्योर आमतौर पर "OAuth पूरा नहीं हुआ" होता है — सर्वर 401/403 लौटाता है और needs authentication दिखाता है। और जब यह दोनों में से कोई नहीं हो, फिर भी कॉन्फ़िग का कोई असर न हो, तो कॉन्फ़िग फ़ाइल के स्थान, JSON की टाइपो, या प्रोजेक्ट अनुमोदन पर शक करें।

इसलिए पहला कदम है "/mcp खोलें, स्टेटस पढ़ें, और पहचानें कि यह तीनों परिवारों में से कौन-सा है।" हर एरर को सामान्य "कनेक्ट नहीं हो रहा" मानकर बेतरतीब छेड़छाड़ करना लंबा रास्ता है। अगला भाग बताता है कि स्टेटस कैसे पढ़ें।

2. पहले /mcp से स्टेटस पढ़ें

सेशन में /mcp चलाएँ (या शेल से claude mcp list / claude mcp get <name>) ताकि हर सर्वर की स्थिति दिखे। मुख्य स्टेटस और उनके अर्थ:

स्टेटसअर्थपहले कहाँ देखें
✓ connectedकनेक्ट हो गया। बगल में टूल की संख्या दिखती हैअगर टूल की संख्या 0 हो: "कनेक्ट तो हुआ पर कोई टूल नहीं" → पुनः कनेक्ट / डिबग
✗ failedलॉन्च फेल हुआ, या रीट्राई खत्म हो गएलोकल लॉन्च = कमांड, पाथ, npx, env vars (§3, §4)
△ needs authenticationरिमोट ने 401/403 लौटाया। OAuth नहीं हुआ/mcp से ऑथेंटिकेशन चलाएँ (ब्राउज़र में अनुमोदित करें)
⏸ pending approvalकिसी प्रोजेक्ट .mcp.json सर्वर के अनुमोदन की प्रतीक्षा/mcp में अनुमोदित करें। गलती से अस्वीकृत हो तो: claude mcp reset-project-choices
✗ rejectedएक प्रोजेक्ट सर्वर जिसे आपने पहले अस्वीकार किया थावही (फिर से अनुमोदित करने के लिए reset-project-choices)

मूल बात: "failed = लॉन्च की समस्या, needs authentication = ऑथेंटिकेशन, pending = अनुमोदन" — स्टेटस ही आपका अगला कदम तय कर देता है। एक अक्सर छूट जाने वाला मामला है "connected पर 0 टूल" — सर्वर शुरू तो हुआ पर टूल की सूची नहीं लौटा रहा; पुनः कनेक्ट करें या claude --debug mcp से लॉग जाँचें।

3. कनेक्शन फेल होने के मुख्य कारण और उपाय

यहाँ failed (लोकल लॉन्च फेल्योर) और कॉन्फ़िग समस्याओं के प्रतिनिधि कारण, उनके उपायों के साथ दिए गए हैं।

ROOT CAUSES

failed / कॉन्फ़िग समस्याओं के मुख्य कारक

1) पाथ / PATH
रिलेटिव पाथ लॉन्च डायरेक्टरी के सापेक्ष रिज़ॉल्व होते हैं और खिसक जाते हैं। लोकल स्क्रिप्ट के लिए एब्सोल्यूट पाथ इस्तेमाल करें। एक्ज़ीक्यूटेबल न मिलने पर spawn ... ENOENT आता है।
2) env vars पास नहीं हुए
सर्वर की API कीज़ प्रति-सर्वर env में जाती हैं (.mcp.json में या --env से)। settings.json का env, MCP तक नहीं पहुँचता।
3) स्टार्टअप टाइमआउट
भारी सर्वर समय रहते शुरू नहीं हो पाता। लॉन्च पर MCP_TIMEOUT (ms) बढ़ाएँ, जैसे MCP_TIMEOUT=10000 claude।
4) कॉन्फ़िग स्थान / JSON
प्रोजेक्ट .mcp.json रिपॉ रूट पर रखें (.claude/ के नीचे नहीं, settings.json में नहीं)। अपरिभाषित ${VAR} से कॉन्फ़िग पार्सिंग फेल हो जाती है।
5) stdout को दूषित करना
एक stdio सर्वर जो stdout पर लॉग लिखता है, प्रोटोकॉल को बिगाड़ देता है (connected पर 0 टूल, आदि)। लॉग stderr पर भेजें।
6) रिमोट ऑथ
401/403 = needs authentication। /mcp से OAuth। ध्यान दें: एक अस्वीकृत स्टैटिक ऑथ हेडर failed के रूप में रिपोर्ट होता है।

लोकल के लिए, इस क्रम में जाँचें: 1) पाथ → 2) env vars → 4) कॉन्फ़िग स्थान।
रिमोट के लिए, 6) ऑथ ही लगभग सब कुछ है। अगले भाग का Windows जाल भी बहुत आम है।

एक प्रोजेक्ट .mcp.json को git के ज़रिए साझा किया जा सकता है और पहली बार अनुमोदन का प्रॉम्प्ट आता है। अगर आप गलती से उस प्रॉम्प्ट को बंद कर दें, तो सर्वर निष्क्रिय रहता है (pending/rejected)। अनुमोदन फिर से करने के लिए claude mcp reset-project-choices चलाएँ। इसे MCP की मूल बातें और एजेंट-से-एजेंट A2A के साथ जोड़कर देखें ताकि कनेक्टिविटी की पूरी तस्वीर मिले।

4. जब Windows पर फेल हो (सबसे आम जाल)

नेटिव Windows पर, npx-आधारित MCP सर्वर का spawn npx ENOENT / Failed to connect के साथ कनेक्ट न होना बेहद आम है। कारण: Windows का npx असल में एक बैच शिम (npx.cmd) है, और Node का प्रोसेस स्पॉन किसी .cmd को सीधे रिज़ॉल्व नहीं कर पाता।

उपाय: इसे cmd /c में रैप करें

command को सीधे npx के बजाय cmd बनाएँ, और args के रूप में /c npx ... पास करें:

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@scope/your-mcp-server"]
}

या इसे WSL के अंतर्गत चलाएँ, जो भरोसेमंद है। अगर where npx कोई पाथ दिखाता है फिर भी फेल होता है, तो सबसे पहले इसी .cmd समस्या पर शक करें। कुछ वर्ज़न-विशिष्ट घटनाएँ बाद के रिलीज़ में ठीक हो चुकी हो सकती हैं, इसलिए नवीनतम वर्ज़न में अपडेट करके भी देखें।

5. डायग्नोस्टिक वर्कफ़्लो

जब कारण स्पष्ट न हो, ऊपर से नीचे काम करें। तरकीब यह है कि Claude Code को दोष देने से पहले पुष्टि करें कि सर्वर अकेले चलता है।

DIAGNOSE

ऊपर से नीचे अलग-अलग करें

1
/mcp और claude mcp list / get से स्टेटस जाँचें (failed बनाम auth बनाम pending)।
2
claude --debug mcp से सर्वर का stderr (एरर आउटपुट) पढ़ें। क्रैश का कारण आमतौर पर यहीं मिल जाता है।
3
सर्वर को अकेले लॉन्च करें (क्या उसी शेल में npx ... चलता है?)। अगर नहीं, तो यह Claude Code से पहले की समस्या है।
4
सर्वर को अकेले MCP Inspector (npx @modelcontextprotocol/inspector) से सत्यापित करें — उसकी टूल सूची देखें और UI में टूल चलाएँ।
5
Claude Desktop पर, कॉन्फ़िग बदलने के बाद पूरी तरह छोड़कर फिर खोलें (विंडो बंद करना काफी नहीं)। लॉग mcp*.log में होते हैं। /doctor भी जाँचता है।

नियम: पहले पुष्टि करें कि "क्या सर्वर अकेले चलता है?"
यह तय हो जाने पर, बाकी सब कॉन्फ़िग (पाथ, env, स्थान) या ऑथ तक सिमट जाता है।

ध्यान दें: बहुत सारे MCP सर्वर जोड़ने से टूल परिभाषाएँ कॉन्टेक्स्ट खा जाती हैं (खासकर हमेशा-लोड सेटअप में)। Claude Code डिफ़ॉल्ट रूप से टूल सर्च के ज़रिए टूल परिभाषाओं को विलंबित कर देता है, इसलिए असर कम होता है, फिर भी जो सर्वर इस्तेमाल न करें उन्हें निष्क्रिय कर देना समझदारी है। कॉन्टेक्स्ट को अधिक भरने से Prompt is too long भी ट्रिगर हो सकता है।

6. रोकथाम चेकलिस्ट

MCP कनेक्शन पर न अटकने की आदतें।

(1) लोकल स्क्रिप्ट को एब्सोल्यूट पाथ से निर्दिष्ट करें। (2) सर्वर की कीज़ प्रति-सर्वर env में रखें (settings.json में नहीं)। (3) Windows पर, cmd /c npx ... से रैप करें (या WSL इस्तेमाल करें)। (4) .mcp.json को रिपॉ रूट पर रखें; JSON सिंटैक्स और अपरिभाषित ${VAR} पर नज़र रखें। (5) सर्वर stdout पर लॉग न लिखें (stderr इस्तेमाल करें)। (6) कॉन्फ़िग बदलने के बाद रीलोड करें (Desktop को पूरी तरह रीस्टार्ट; प्रोजेक्ट सर्वर फिर से अनुमोदित करें)। (7) अटक जाएँ तो claude --debug mcp और एक स्टैंडअलोन सर्वर लॉन्च से अलग-अलग करें, और ज़रूरत हो तो नवीनतम वर्ज़न में अपडेट करें।

सारांश

Claude Code के MCP सर्वर कनेक्शन एरर के लिए, सबसे छोटा रास्ता है /mcp के स्टेटस से तीन परिवारों में वर्गीकृत करना। ✗ failed एक लोकल लॉन्च की समस्या है (पाथ, env vars, टाइमआउट, कॉन्फ़िग स्थान — और Windows पर, npx को cmd /c से रैप करें), △ needs authentication रिमोट OAuth है (/mcp से ऑथेंटिकेट करें), और ⏸ pending approval एक प्रोजेक्ट सर्वर है जो अनुमोदन की प्रतीक्षा में है (/mcp में अनुमोदित करें; गलत अस्वीकृति claude mcp reset-project-choices से ठीक होती है)।

इस क्रम में डायग्नोस करें: (1) /mcp से स्टेटस -> (2) claude --debug mcp से stderr -> (3) स्टैंडअलोन लॉन्च -> (4) MCP Inspector -> (5) Desktop को पूरी तरह रीस्टार्ट। Claude Code को दोष देने से पहले पुष्टि करें कि सर्वर अकेले चलता है, फिर बाकी सब कॉन्फ़िग या ऑथ तक सिमट जाता है। बस तीन आदतें — env vars प्रति-सर्वर env में, .mcp.json रिपॉ रूट पर, लॉग stderr पर — घटनाओं को नाटकीय रूप से घटा देती हैं। संबंधित: MCP क्या है, MCP सर्वर से कमाई, Claude Code एरर संग्रह।

FAQ

Q. /mcp "failed" दिखाता है। कहाँ से शुरू करूँ?
A. failed ज़्यादातर एक लोकल (stdio) सर्वर लॉन्च फेल्योर होता है। इस क्रम में जाँचें: (1) कमांड/स्क्रिप्ट का पाथ (एब्सोल्यूट पाथ इस्तेमाल करें), (2) ज़रूरी एनवायरनमेंट वेरिएबल (उन्हें प्रति-सर्वर env में रखें), और (3) Windows पर, cmd /c npx ... से रैप करें। अगर कारण फिर भी स्पष्ट न हो, तो claude --debug mcp से सर्वर का stderr पढ़ें, और पहले यह जाँचें कि क्या सर्वर उसी शेल में अकेले लॉन्च होता है।

Q. यह "needs authentication" कहता है और टूल काम नहीं करते।
A. यह एक रिमोट (HTTP) सर्वर है जो ऑथेंटिकेशन माँग रहा है (401/403)। /mcp खोलें और उस सर्वर के लिए ऑथेंटिकेशन चलाएँ; यह ब्राउज़र में OAuth अनुमोदन तक बढ़ता है। पूरा होने पर, टोकन सुरक्षित रूप से स्टोर होते हैं और स्वतः रिफ़्रेश होते हैं। ध्यान दें कि कुछ सेवाएँ (Microsoft 365, Gmail, Google Calendar) Claude Code से लोकल ऑथ का समर्थन नहीं करतीं और इन्हें इसके बजाय claude.ai पर Settings → Connectors के ज़रिए कनेक्ट करना होता है।

Q. Windows पर मेरा npx सर्वर बस कनेक्ट ही नहीं होता।
A. Windows का npx असल में एक बैच शिम (npx.cmd) है, जो अक्सर spawn npx ENOENT के साथ लॉन्च नहीं हो पाता। इसे रैप करने के लिए command को cmd और args को ["/c","npx","-y","package-name"] में बदलें। WSL के अंतर्गत चलाना भी भरोसेमंद है। अगर where npx कोई पाथ दिखाता है फिर भी फेल होता है, तो यह लगभग निश्चित रूप से इसी .cmd समस्या के कारण है। यह नए वर्ज़न में ठीक हो सकता है, इसलिए अपडेट करके भी देखें।

Q. यह "connected" है पर 0 टूल दिखाता है।
A. सर्वर सफलतापूर्वक लॉन्च तो हुआ पर टूल की सूची नहीं लौटा रहा। एक आम कारण है एक stdio सर्वर का stdout पर लॉग लिखना और प्रोटोकॉल को बिगाड़ना — लॉग हमेशा stderr पर भेजें। पहले /mcp से पुनः कनेक्ट करें; अगर इससे ठीक न हो, तो claude --debug mcp से सर्वर का आउटपुट जाँचें।

Q. मैंने एक सर्वर कॉन्फ़िगर किया पर वह /mcp में दिखता ही नहीं।
A. कॉन्फ़िग फ़ाइल का स्थान ही संभावित समस्या है। एक साझा प्रोजेक्ट सर्वर .mcp.json में रिपॉ रूट पर जाता है (यह .claude/ के नीचे या settings.json के अंदर नहीं पढ़ा जाता)। एक अपरिभाषित ${VAR} से भी कॉन्फ़िग पार्सिंग फेल हो जाती है। प्रोजेक्ट सर्वर को पहली बार अनुमोदन की ज़रूरत होती है; अगर आप प्रॉम्प्ट बंद कर दें तो यह pending ही रहता है — इसे claude mcp reset-project-choices से फिर से करें।