MCP server integration की समस्याएँ: protocol, transport, permissions और schema

समस्या का तुरंत वर्गीकरण

Inspector चलाने से पहले एक symptom और आखिरी पुष्टि किया हुआ checkpoint लिखें:

• process बिल्कुल शुरू नहीं होता;
• process चल रहा है, लेकिन client को JSON-RPC नहीं मिलता;
• transport जवाब देता है, पर version या capabilities मेल नहीं खाते;
• server 401 या 403 लौटाता है;
• tools/list चलता है, लेकिन अपेक्षित tool नहीं मिलता;
• tool दिखता है, पर tools/call arguments अस्वीकार करता है;
• call पूरा होता है, लेकिन result सत्यापित नहीं किया जा सकता।

Notes में API Key, bearer token, cookie, पूरा prompt या private files का content न लिखें। Correlation के लिए समय, server का नाम, method, JSON-RPC id, error code और साफ किया हुआ message पर्याप्त है।

1. Protocol era तय करें

पता करें कि client, server और इस्तेमाल किया गया SDK कौन-सा version support करते हैं। Connected message transport और discovery के एक हिस्से की पुष्टि करता है, लेकिन इससे अकेले 2026-07-28 पर सहमति साबित नहीं होती।

Modern implementation में ये तीन संकेत जाँचें:

1. SDK या release notes साफ तौर पर 2026-07-28 support बताते हों।
2. Trace में server/discover या SDK द्वारा निर्धारित कोई दूसरा discovery path हो।
3. Requests में version, client information और capabilities वाला सही _meta मौजूद हो।

किसी दूसरे SDK से _meta का आकार हाथ से copy न करें। Exact wire format compatible client या official SDK को बनाना चाहिए। अगर server initialize का इंतजार करता है और client self-contained 2026-07-28 requests भेजता है, तो यह protocol era mismatch है, tool schema error नहीं।

Legacy initialize: केवल 2025-11-25 और पुराने versions के लिए

नीचे minimal legacy request है। इसे modern 2026-07-28 flow में “सुरक्षा के लिए” न जोड़ें।

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "mcp-diagnostic-client",
      "version": "1.0.0"
    }
  }
}

Successful response के बाद legacy client notifications/initialized भेजता है। अगर यह exchange टूटता है, तो पहले versions और capabilities list की तुलना करें। अभी tools/list पर जाना जल्दबाजी होगी।

2. Transport को MCP semantics से अलग जाँचें

MCP methods और data तय करता है, जबकि transport startup, framing, delivery और request cancellation संभालता है। stdio से HTTP पर जाने से गलत inputSchema ठीक नहीं होगा।

stdio

stdio में client, server को child process के रूप में शुरू करता है। Messages stdin और stdout से newline-delimited UTF-8 JSON-RPC documents के रूप में जाते हैं।

जाँचें:

1. command मौजूद हो और उसी user से चले।
2. Arguments अलग-अलग items के रूप में दिए जाएँ और shell aliases पर निर्भर न हों।
3. Working directory में जरूरी files हों या paths absolute हों।
4. जरूरी variables वास्तव में child process को उपलब्ध हों।
5. stdout में banner, debug lines या stack trace न हो; logs stderr में जाएँ।

stdout पर गलती से आया एक console.log() भी framing को उस समय तोड़ सकता है जब client ने JSON-RPC response देखा तक नहीं हो।

Streamable HTTP

Streamable HTTP में client एक MCP endpoint पर POST messages भेजता है। Response साधारण JSON या request-scoped SSE हो सकता है। Exact URL, HTTP method, Content-Type, TLS, redirects, proxy और authentication method की जाँच करें।

Transport test loopback या isolated test environment में करें। अनुमति के बिना public production endpoint scan न करें। अगर POST login page का HTML, दूसरे host का 301/302 या reverse proxy response लौटाता है, तो request अभी MCP तक नहीं पहुँची।

3. उसी environment में startup दोहराएँ

stdio के लिए server command को पहले उसी directory से और उसी user के रूप में सीधे चलाएँ, जिससे MCP client चलता है। IDE से launch करना इसका विकल्प नहीं है: वहाँ PATH, cwd, runtime और permissions अलग हो सकते हैं।

जाँचें:

node --version
pwd
node ./dist/server.js

pwd अपने आप में secret नहीं दिखाता, लेकिन path में user name या private project का नाम हो तो उसे publish न करें। Server command को या तो stdin पर JSON-RPC का इंतजार करना चाहिए, या stderr पर साफ error के साथ बंद होना चाहिए। बिना message के तुरंत exit आम तौर पर गलत entrypoint, missing dependency या बिना log के handle की गई startup error बताता है।

23 अगस्त 2026 की official Inspector CLI documentation के अनुसार Node.js 22.19.0 या नया चाहिए। Version इससे कम हो तो रुकें और आगे की diagnosis से पहले runtime बदलें।

4. Permissions और authentication को अलग करें

Response code अगली जाँच बताता है:

• 401 Unauthorized: credential गायब है, expire हो गई है या स्वीकार नहीं हुई;
• 403 Forbidden: identity पहचानी गई है, लेकिन जरूरी permission या scope नहीं है;
• 404: अक्सर endpoint या route गलत है, permissions की कमी नहीं;
• timeout: server, proxy या tool समय पर पूरा नहीं हुआ; यह auth error का प्रमाण नहीं है।

Smoke test के लिए permissions बंद न करें। Minimum scope वाली अलग test identity बनाएँ और ऐसा read-only tool चुनें जिसका कोई external effect न हो। Client में इंसान के पास call अस्वीकार करने का विकल्प रहना चाहिए; tool annotations untrusted data हैं और policy की जगह नहीं लेतीं।

Logs में auth decision (allowed/denied), scope name और correlation ID रखें। Credential, Authorization header और cookie को हटाएँ या mask करें।

5. Capability और inputSchema जाँचें

tools/list serve करने से पहले server को tools capability declare करनी चाहिए। हर tool का unique name और inputSchema में valid JSON Schema object होना चाहिए। tools/call के arguments को उस schema से मेल खाना चाहिए।

Minimal read-only tool declaration:

{
  "name": "echo",
  "description": "दिया गया text बिना बदलाव के लौटाता है",
  "inputSchema": {
    "type": "object",
    "properties": {
      "text": {
        "type": "string"
      }
    },
    "required": ["text"],
    "additionalProperties": false
  }
}

आम गलतियाँ सरल हैं: root type: object नहीं है, required field properties में नहीं है, client string की जगह number भेजता है, argument name का case बदल जाता है, या server एक ही नाम वाले दो tools advertise करता है।

Version और transport के मेल के बाद इस JSON-RPC payload से method जाँचें:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

फिर ठीक एक tool call करें:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "echo",
    "arguments": {
      "text": "MCP_OK_2026"
    }
  }
}

ये snippets methods के payload दिखाते हैं, पूरा connection bootstrap नहीं। 2026-07-28 flow में compatible client जरूरी request metadata को _meta में जोड़ता है; legacy flow में पहले initialize होता है। अनुमति के बिना इन JSON snippets को production endpoint पर manually न भेजें।

6. MCP Inspector CLI से सुरक्षित test चलाएँ

पहले Inspector को trusted lockfile से pinned project dependency के रूप में install करें। नीचे का --no-install diagnosis के दौरान कोई मनमाना current version download नहीं करता।

Local stdio server के tools की सूची:

npx --no-install @modelcontextprotocol/inspector --cli node ./dist/server.js --method tools/list

echo का एक call:

npx --no-install @modelcontextprotocol/inspector --cli node ./dist/server.js \
  --method tools/call \
  --tool-name echo \
  --tool-arg text=MCP_OK_2026

Loopback पर test Streamable HTTP endpoint के लिए:

npx --no-install @modelcontextprotocol/inspector --cli \
  http://127.0.0.1:3000/mcp \
  --transport http \
  --method tools/list

Token को shell history, URL या article में न डालें। Endpoint को auth चाहिए तो local environment में Inspector के सामान्य तरीके से credential configure करें, या test रोककर server owner से test identity माँगें। ऊपर के commands में जानबूझकर कोई real Key नहीं है।

Symptom → जाँच → सुधार

सफल जाँच के मानदंड

Integration न्यूनतम acceptance तभी पास करती है जब पाँचों शर्तें पूरी हों:

1. Logs या telemetry में अपेक्षित negotiated protocol version दिखे।
2. Transport framing न बिगाड़े: stdio में अतिरिक्त stdout न हो और HTTP, MCP endpoint से जवाब दे।
3. tools/list valid inputSchema वाला एक अपेक्षित tool लौटाए।
4. tools/call सच में text=MCP_OK_2026 के साथ चले और MCP_OK_2026 बिना बदलाव के लौटाए।
5. Test ने permissions बंद न की हों, credentials उजागर न की हों और external side effect न किया हो।

Model response में केवल MCP_OK_2026 दिखना पर्याप्त नहीं है। संबंधित JSON-RPC id के साथ दर्ज tool call, या Inspector record और sanitized server log चाहिए।

Stop conditions

Diagnosis रोक दें और अगली layer पर न जाएँ अगर:

• किसी भी side द्वारा supported protocol era अज्ञात है;
• Inspector बिना जाँच के unpinned package version install करना चाहता है;
• test को production credential, auth बंद करने या scope बढ़ाने की जरूरत है;
• उपलब्ध एकमात्र tool database में लिखता, message भेजता, file बदलता या command चलाता है;
• HTTP endpoint किसी third party का है और test की अनुमति पक्की नहीं है;
• logs में Key, token, cookie, personal data या private resource का content आ गया है;
• repeated runs में tools/list अस्थिर है या अलग-अलग schemas लौटाता है;
• valid JSON-RPC response से पहले server crash हो जाता है।

इन स्थितियों में sanitized symptom, client/server/SDK versions, transport, correlation ID और error का न्यूनतम अंश सुरक्षित रखें। अनावश्यक permissions या secrets बाँटे बिना समस्या सही layer के owner को सौंपने के लिए इतना पर्याप्त है।

स्रोत

• MCP 2026-07-28: versioning
• MCP 2026-07-28: transports
• MCP 2026-07-28: tools
• MCP Inspector

Specification version, transport details और minimum Node.js version को 23 अगस्त 2026 को सत्यापित किया गया था। Client, server, SDK या Inspector update करने के बाद diagnosis दोहराने से पहले current official documentation फिर से देखें।