OpenCode MCP कॉन्फ़िग: सर्वर जोड़ें, OAuth लॉगिन और टाइमआउट की समस्याएँ ठीक करें

आप opencode.json में MCP सर्वर जोड़ते हैं, टर्मिनल रीस्टार्ट करते हैं, और टूल्स दिखते ही नहीं। या वे दिखते हैं, ब्राउज़र में लॉगिन खुलता है, पर कॉलबैक कभी नहीं पहुँचता। या सब कुछ तब तक ठीक चलता है जब तक पहली धीमी कॉल टाइमआउट से बंद नहीं हो जाती। ज़्यादातर OpenCode MCP कॉन्फ़िग की परेशानियाँ इन्हीं तीन समस्याओं से आती हैं, और हर एक का समाधान छोटा और सीधा है।

यह लेख वे सटीक फ़ील्ड समझाता है जो OpenCode पढ़ता है, वे कमांड बताता है जो बताएँ कि गड़बड़ी कहाँ है, और वे सेटिंग्स देता है जो अंदाज़ा लगाने का झंझट खत्म करती हैं। ये स्निपेट अक्टूबर 2026 में जाँचे गए आधिकारिक OpenCode MCP डॉक्स के अनुसार हैं, इसलिए इन्हें जैसे हैं वैसे चिपकाएँ और सिर्फ़ नाम, पाथ और URL बदलें।

OpenCode अपनी कॉन्फ़िग कहाँ से पढ़ता है

OpenCode एक ही कॉन्फ़िग फ़ाइल चुनकर बाकी को नज़रअंदाज़ नहीं करता। वह मिलने वाले हर स्रोत को मर्ज करता है, और जब दो स्रोत एक ही फ़ील्ड सेट करते हैं, तो नीचे दिए क्रम में बाद वाला जीतता है। इसीलिए जो सर्वर आपने प्रोजेक्ट फ़ाइल से "हटाया" था, वह वापस आता रहता है: वह अब भी आपकी ग्लोबल फ़ाइल में परिभाषित है।

कॉन्फ़िग की जगहें और मर्ज का क्रम

JSON और JSONC (टिप्पणियों वाला JSON) दोनों काम करते हैं। सबसे ऊपर "$schema": "https://opencode.ai/config.json" जोड़ने से आपके एडिटर में ऑटोकम्प्लीट मिलता है और टाइपो पर लाल लकीर दिखती है। टाइपो ही वह सबसे आम वजह है जिससे कोई सर्वर चुपचाप नज़रअंदाज़ हो जाता है, इसलिए यह स्कीमा लाइन मिनटों में अपनी लागत वसूल करा देती है।

💡 टिप: जब कोई सर्वर अजीब व्यवहार करे, तो पहले ग्लोबल फ़ाइल देखें। वहाँ की पुरानी एंट्री एक अच्छी प्रोजेक्ट एंट्री को ओवरराइड कर सकती है।

सीक्रेट्स चिपकाने की बजाय वेरिएबल इस्तेमाल करें

OpenCode कॉन्फ़िग में कहीं भी दो प्लेसहोल्डर बदल देता है। {env:NAME} एक एनवायरनमेंट वेरिएबल पढ़ता है, और {file:path} किसी फ़ाइल की सामग्री सीधे डालता है। हर टोकन के लिए इन्हें इस्तेमाल करें, ताकि कॉन्फ़िग कमिट करने के लिए सुरक्षित रहे।

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tracker": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:TRACKER_TOKEN}"
      }
    }
  }
}

प्रॉम्प्ट कॉपी करें

सापेक्ष फ़ाइल पाथ कॉन्फ़िग डायरेक्टरी से हल होते हैं, जबकि / या ~ से शुरू होने वाले पाथ एब्सोल्यूट होते हैं। अगर OpenCode को लॉन्च करने वाले शेल में वेरिएबल नहीं है, तो सर्वर को वैध टोकन नहीं मिलता और वह 401 देता है, जो बिल्कुल गलत टोकन जैसा दिखता है। उसी शेल में वेरिएबल एक्सपोर्ट करें, फिर उसी से OpenCode शुरू करें।

लोकल और रिमोट सर्वर जोड़ें

सब कुछ mcp नाम के एक टॉप-लेवल फ़ील्ड के नीचे रहता है। हर चाइल्ड एक सर्वर है, जिसका नाम आप चुनते हैं, और यही नाम उसके टूल्स का प्रीफ़िक्स बन जाता है, इसलिए छोटे, लोअरकेस और बिना स्पेस वाले नाम चुनें।

एक न्यूनतम लोकल सर्वर

लोकल सर्वर वह प्रोसेस है जिसे OpenCode आपके लिए शुरू करता है और स्टैंडर्ड इनपुट और आउटपुट के ज़रिए उससे बात करता है।

{
  "mcp": {
    "files": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/home/dev/projects"],
      "enabled": true,
      "timeout": 15000
    }
  }
}

प्रॉम्प्ट कॉपी करें

दो फ़ील्ड ज़रूरी हैं: "type": "local" और command। जिस बात पर लोग अक्सर अटकते हैं वह यह है कि command स्ट्रिंग्स का एरे है, जिसमें हर आर्गुमेंट के लिए एक एंट्री होती है, कोई एक शेल स्ट्रिंग नहीं। "command": "npx -y some-server" लिखना वह सबसे तेज़ तरीका है जिससे सर्वर कभी शुरू ही नहीं होता।

एनवायरनमेंट वेरिएबल और वर्किंग डायरेक्टरी

लोकल सर्वरों को अक्सर क्रेडेंशियल या किसी खास फ़ोल्डर की ज़रूरत होती है। environment चाइल्ड प्रोसेस को वेरिएबल पास करता है, और cwd उसकी वर्किंग डायरेक्टरी सेट करता है। cwd में सापेक्ष पाथ वर्कस्पेस से हल होते हैं।

{
  "mcp": {
    "reports": {
      "type": "local",
      "command": ["node", "./tools/reports-server.js"],
      "cwd": "./mcp",
      "environment": {
        "API_TOKEN": "{env:REPORTS_API_TOKEN}",
        "LOG_LEVEL": "info"
      }
    }
  }
}

प्रॉम्प्ट कॉपी करें

हेडर वाला एक रिमोट सर्वर

रिमोट सर्वर कहीं और पहले से चल रहा होता है, इसलिए OpenCode को सिर्फ़ एक पता और आम तौर पर एक क्रेडेंशियल चाहिए।

{
  "mcp": {
    "docs": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:DOCS_MCP_TOKEN}"
      },
      "oauth": false,
      "timeout": 20000
    }
  }
}

प्रॉम्प्ट कॉपी करें

जो सर्वर स्टैटिक टोकन से प्रमाणित होता है, उसके लिए "oauth": false सेट करना सही कदम है। इसके बिना OpenCode 401 को OAuth लॉगिन शुरू करने का संकेत मान लेता है, जो तब भ्रम पैदा करता है जब असली समस्या खराब टोकन हो।

mcp list से नतीजा जाँचें

हर बदलाव के बाद opencode mcp list चलाएँ। यह हर कॉन्फ़िगर किए गए सर्वर को उसकी स्थिति के साथ दिखाता है, इसलिए दो सेकंड में पता चल जाता है कि सर्वर कनेक्ट हुआ, ऑथेंटिकेशन माँगता है या फ़ेल हुआ। सेशन खोलने और यह सोचने से पहले यह करें कि टूल्स क्यों गायब हैं।

पूरा फ़ील्ड रेफ़रेंस यहाँ एक जगह पर है:

💡 टिप: जिन सर्वरों की ज़रूरत आपको कभी-कभी ही हो, उन पर "enabled": false सेट करें। एंट्री फ़ाइल में बनी रहती है, और उसे वापस चालू करने तक कुछ भी आपके सेशन में लोड नहीं होता।

OAuth साइन-इन की समस्याएँ ठीक करें

MCP ऑथराइज़ेशन फ़्लो को फ़ॉलो करने वाले रिमोट सर्वरों को लगभग कोई सेटअप नहीं चाहिए। जब OpenCode को 401 मिलता है, तो वह अपने आप OAuth शुरू करता है, Dynamic Client Registration (RFC 7591) के ज़रिए क्लाइंट के रूप में रजिस्टर करता है, आपका ब्राउज़र खोलता है, और रीडायरेक्ट का इंतज़ार करता है। नतीजे में मिले टोकन ~/.local/share/opencode/mcp-auth.json में सहेजे जाते हैं।

ऑटोमैटिक OAuth कैसे काम करता है

जो सर्वर इसे सपोर्ट करता है, उसके लिए पूरा सेटअप सिर्फ़ दो फ़ील्ड और एक कमांड है।

1. सर्वर को सिर्फ़ type और url के साथ जोड़ें।
2. opencode mcp auth tracker चलाएँ, और tracker की जगह अपना सर्वर नाम लिखें।
3. खुले ब्राउज़र टैब में अनुरोध को मंज़ूरी दें।
4. opencode mcp list चलाएँ और पुष्टि करें कि सर्वर कनेक्टेड दिख रहा है।

चार कमांड पूरा लाइफ़साइकिल संभालते हैं:

जब पिछले हफ़्ते काम करने वाला लॉगिन अचानक फ़ेल हो जाए, तो कारण आम तौर पर पुराना या रद्द किया गया टोकन होता है। opencode mcp logout <name> चलाएँ, फिर opencode mcp auth <name> दोबारा चलाएँ, और आप साफ़ शुरुआत से शुरू करते हैं।

पहले से रजिस्टर्ड क्लाइंट और स्कोप

कुछ प्रोवाइडर डायनामिक रजिस्ट्रेशन को मना करते हैं और चाहते हैं कि आप ऐप हाथ से रजिस्टर करें। ऐसे में OpenCode को वही क्लाइंट विवरण दें जो वह अन्यथा खुद बनाता।

{
  "mcp": {
    "tracker": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:TRACKER_CLIENT_ID}",
        "clientSecret": "{env:TRACKER_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

प्रॉम्प्ट कॉपी करें

scope मान स्पेस से अलग किए गए स्कोप वाली एक स्ट्रिंग है, ठीक वैसे ही जैसे प्रोवाइडर उन्हें डॉक्युमेंट करता है। सबसे छोटा सेट माँगें जो काम करे। कोई चौड़ा स्कोप जिसे प्रोवाइडर ठुकरा दे, लॉगिन पेज पर ऐसा एरर देता है जिसमें यह नहीं बताया जाता कि कौन सा स्कोप समस्या था।

रिमोट मशीन पर लॉगिन फ़ेल होता है

यही वह समस्या है जो पूरी दोपहर खा जाती है। साइन-इन के दौरान OpenCode एक लोकल कॉलबैक पोर्ट सुनता है, और यूज़र्स की रिपोर्ट के अनुसार डिफ़ॉल्ट 19876 है। अगर OpenCode SSH पर किसी रिमोट होस्ट पर चल रहा है, तो लैपटॉप पर आपका ब्राउज़र लैपटॉप के 127.0.0.1:19876 पर रीडायरेक्ट करता है, जहाँ कुछ भी नहीं सुन रहा होता। अप्रूवल सफल होता है, कॉलबैक कभी नहीं पहुँचता, और कमांड आखिर में टाइमआउट हो जाता है।

इसका समाधान है आपके लैपटॉप से रिमोट होस्ट तक पोर्ट फ़ॉरवर्ड:

ssh -o ExitOnForwardFailure=yes -L 127.0.0.1:19876:127.0.0.1:19876 user@remote-host

प्रॉम्प्ट कॉपी करें

उस SSH सेशन के अंदर opencode mcp auth <name> चलाएँ, छपा हुआ URL अपने लोकल ब्राउज़र में खोलें, और अब कॉलबैक उस टनल से होकर गुज़रता है।

हाल के बिल्ड oauth ऑब्जेक्ट के अंदर callbackPort और redirectUri भी स्वीकार करते हैं, उन प्रोवाइडरों के लिए जो एक तय, पहले से रजिस्टर्ड कॉलबैक माँगते हैं। रीडायरेक्ट URI में http:// होना चाहिए, साथ में localhost, 127.0.0.1 या [::1] और एक स्पष्ट पोर्ट। अगर आप पोर्ट बदलते हैं, तो वही पोर्ट फ़ॉरवर्ड करें। किसी भी फ़ील्ड पर भरोसा करने से पहले अपने एडिटर में स्कीमा जाँच लें, क्योंकि पुराने वर्ज़न इन्हें नहीं जानते होंगे।

काम करने वाले टाइमआउट फ़िक्स

दो अलग-अलग टाइमआउट होते हैं, और उन्हें आपस में मिलाने से घंटों बर्बाद होते हैं। एक तय करता है कि OpenCode सर्वर के शुरू होने और उसके टूल्स की सूची आने तक कितनी देर इंतज़ार करे। दूसरा तय करता है कि सर्वर चालू होने के बाद एक अकेली टूल कॉल कितनी देर चल सकती है।

स्टार्टअप का डिफ़ॉल्ट

timeout फ़ील्ड मिलीसेकंड में है, और लोकल व रिमोट दोनों सर्वरों के लिए डिफ़ॉल्ट 5000 है। छोटी स्क्रिप्ट के लिए पाँच सेकंड ठीक हैं। लेकिन ठंडे कैश पर npx -y के लिए यह काफ़ी नहीं है, क्योंकि सर्वर शुरू होने से पहले पैकेज डाउनलोड होना पड़ता है। फिर सर्वर फ़ेल दिखता है और उसके टूल्स कभी लोड नहीं होते।

इसे इस क्रम में ठीक करें:

1. सिर्फ़ उस सर्वर के लिए फ़ील्ड बढ़ाएँ। धीमी एंट्री पर "timeout": 15000 या 30000 सेट करें और बाकी को छेड़ें नहीं।
2. डाउनलोड हटाएँ। npm install -g से पैकेज ग्लोबली इंस्टॉल करें, फिर command को इंस्टॉल किए गए बाइनरी पर पॉइंट करें। स्टार्टअप घटकर एक सेकंड के एक हिस्से तक आ जाता है।
3. रिमोट सर्वरों के लिए एंडपॉइंट टेस्ट करें। URL के खिलाफ सादा curl चलाएँ। अगर curl भी धीमा है, तो समस्या नेटवर्क लेटेंसी या सर्वर की है, आपकी कॉन्फ़िग की नहीं।

जब टूल कॉल 60 सेकंड पर बंद हो जाती हैं

एक अलग एरर बाद में, सेशन के बीच में दिखता है: MCP error -32001: Request timed out। यह MCP क्लाइंट लाइब्रेरी का रिक्वेस्ट टाइमआउट है, और TypeScript SDK पर बने कई क्लाइंट का डिफ़ॉल्ट 60 सेकंड होता है। स्टार्टअप वाला timeout बढ़ाने से चल रही टूल कॉल पर इसका असर नहीं पड़ता।

पहले अपने बिल्ड के स्कीमा में प्रति-रिक्वेस्ट सेटिंग देखें। अगर कोई नहीं है, तो क्लाइंट की बजाय टूल बदलें। पहला टूल तुरंत एक जॉब आईडी लौटाए, और दूसरा टूल जॉब की स्थिति बताए। मॉडल सबमिट करता है, एक आईडी पाता है, और बाद में दोबारा जाँचता है। यही सबमिट-फिर-पोल पैटर्न इमेज और वीडियो जनरेशन APIs उसी कारण से इस्तेमाल करते हैं।

💡 टिप: सर्वर लॉग हमेशा stderr पर भेजें, stdout पर नहीं। लोकल सर्वर stdout को प्रोटोकॉल के साथ साझा करता है, इसलिए एक भटका हुआ console.log हैंडशेक खराब कर सकता है और टाइमआउट जैसा दिख सकता है।

ऐसे सर्वर को डीबग करें जो कनेक्ट नहीं होता

जब समाधान साफ़ न हो, तो कॉन्फ़िग एडिट करना बंद करें और हर लेयर को अलग-अलग टेस्ट करें।

सर्वर को हाथ से चलाएँ

command एरे को टर्मिनल में कॉपी करें और एक ही लाइन में चलाएँ। स्वस्थ stdio सर्वर शुरू होता है और इनपुट के लिए चुपचाप इंतज़ार करता है। अगर वह कोई एरर छापता है, जैसे गायब मॉड्यूल या गलत पाथ, तो आपने बिना OpenCode के बीच में आए समस्या पकड़ ली। फिर opencode mcp debug <name> चलाएँ, जो उस एक सर्वर के लिए कनेक्शन और OAuth की समस्याओं की जाँच करता है।

रिमोट सर्वर के लिए, उसी हेडर के साथ URL पर curl -i करें। 401 का मतलब क्रेडेंशियल है, 404 का मतलब पाथ है, और अटकना मतलब नेटवर्क।

आम एरर और उनके समाधान

हर एजेंट के लिए कॉन्टेक्स्ट छोटा रखें

हर कनेक्टेड सर्वर अपने टूल डिस्क्रिप्शन हर रिक्वेस्ट के साथ भेजे जाने वाले कॉन्टेक्स्ट में जोड़ता है। कुछ सर्वर भी आपके एक शब्द टाइप करने से पहले कॉन्टेक्स्ट विंडो का बड़ा हिस्सा खा सकते हैं, और जब मॉडल के सामने पचास टूल्स हों, तो सही टूल चुनने में उसकी सटीकता गिरती है। OpenCode के डॉक्स भी यही कहते हैं: MCP सर्वर सोच-समझकर इस्तेमाल करें।

ग्लोबली बंद करें, हर एजेंट के लिए चालू करें

टूल के नामों में सर्वर का नाम प्रीफ़िक्स के रूप में होता है, इसलिए एक ग्लोब पैटर्न पूरे सर्वर को एक साथ चालू या बंद कर सकता है। * शून्य या अधिक अक्षरों से मेल खाता है, और ? ठीक एक अक्षर से।

{
  "tools": {
    "files_*": false,
    "tracker_*": false
  },
  "agent": {
    "builder": {
      "tools": { "files_*": true }
    },
    "planner": {
      "tools": { "tracker_*": true }
    }
  }
}

प्रॉम्प्ट कॉपी करें

इस सेटअप के साथ builder एजेंट को सिर्फ़ फ़ाइलसिस्टम टूल्स दिखते हैं, और planner एजेंट को सिर्फ़ ट्रैकर। दोनों में से कोई भी दूसरे सर्वर की टूल लिस्ट का टोकन खर्च नहीं उठाता।

Claude Sonnet 5 कैसे इस्तेमाल करें

कॉन्फ़िग की गड़बड़ियाँ थकाऊ पैटर्न मिलान हैं: जहाँ एरे होना चाहिए वहाँ स्ट्रिंग, कोई वेरिएबल जो एक्सपोर्ट नहीं हुआ, या कोई पोर्ट जो किसी ने फ़ॉरवर्ड नहीं किया। यहीं कोडिंग मॉडल काम आता है। PicassoIA पर Claude Sonnet 5 कॉन्फ़िग टेक्स्ट, एरर आउटपुट और यहाँ तक कि स्क्रीनशॉट भी पढ़ता है, इसलिए आप जो देख रहे हैं वह चिपकाकर पूछ सकते हैं कि गड़बड़ी क्या है।

1. मॉडल पेज खोलें। PicassoIA पर Claude Sonnet 5 पर जाएँ और प्रॉम्प्ट बॉक्स ढूँढें।
2. अपना mcp ब्लॉक चिपकाएँ। पहले हर टोकन और सीक्रेट को प्लेसहोल्डर से बदलें, फिर opencode mcp debug <name> का आउटपुट जोड़ें।
3. इफ़र्ट सेट करें। डिफ़ॉल्ट low थिंकिंग छोड़ देता है और सबसे तेज़ जवाब देता है। जब कई फ़ाइलें आपस में असर डालें, जैसे ग्लोबल कॉन्फ़िग जिसे प्रोजेक्ट कॉन्फ़िग ओवरराइड करे, तब medium या high इस्तेमाल करें।
4. एक बार सिस्टम प्रॉम्प्ट जोड़ें। कुछ ऐसा: "आप opencode.json MCP कॉन्फ़िग की समीक्षा करते हैं। type, command, timeout और oauth जाँचें। सिर्फ़ सुधरा हुआ JSON लौटाएँ।"
5. अगर हो तो स्क्रीनशॉट जोड़ें। इमेज इनपुट टर्मिनल एरर पढ़ता है। जब स्क्रीनशॉट का टेक्स्ट छोटा हो, तो अधिकतम इमेज रेज़ोल्यूशन बढ़ाएँ।
6. max_tokens 8192 पर रखें। यही डिफ़ॉल्ट है और कुछ कॉन्फ़िग ब्लॉक के लिए काफ़ी है।
7. चिपकाने से पहले जाँचें। उसके सुझाए हर फ़ील्ड को ऊपर की टेबल और आधिकारिक डॉक्स से मिलाएँ।

💡 टिप: किसी भी चैट बॉक्स में असली टोकन कभी न चिपकाएँ। TRACKER_TOKEN जैसे प्लेसहोल्डर मॉडल को वह सब दे देते हैं जो उसे चाहिए।

आज ही अपनी इमेज बनाएँ

कॉन्फ़िग MCP की क्षमता का सिर्फ़ आधा हिस्सा है। जब कोई कोडिंग एजेंट टूल्स कॉल कर सकता है, तो वह इमेज जनरेटर भी कॉल कर सकता है। PicassoIA अपने जनरेटर MCP पर उपलब्ध कराता है, और सर्वर का पता आपके अकाउंट के MCP कनेक्शन पेज पर मिलता है। कोई भी सर्वर जो HTTP बोलता है, इस लेख के रिमोट पैटर्न को फ़ॉलो करता है: type, url, एक हेडर या OAuth, और एक समझदार timeout।

अगर आप सेटअप छोड़कर सिर्फ़ तस्वीरें बनाना चाहते हैं, तो Picasso IA खोलें और ये टेक्स्ट-टू-इमेज मॉडल आज़माएँ:

• तेज़, आम उद्देश्य के नतीजों के लिए PicassoIA Image
• विस्तृत, फ़ोटोग्राफ़िक दृश्यों के लिए Seedream 5 Pro
• सटीक लेआउट वाले प्रॉम्प्ट के लिए GPT Image 2
• तीखी बनावट और प्राकृतिक रोशनी के लिए FLUX 2 Pro

कोई एक चुनें, उस चीज़ के बारे में प्रॉम्प्ट लिखें जो आपने अभी कॉन्फ़िग की है, और देखें कि हर मॉडल उसे कैसे पढ़ता है। दस मिनट का प्रयोग प्रॉम्प्ट की शब्दावली के बारे में एक घंटे की पढ़ाई से ज़्यादा सिखाता है, और हर बनाई गई इमेज अगली के लिए एक मुफ़्त अभ्यास है।