MCP Inspector npx और CLI: MCP सर्वर का परीक्षण कैसे करें

एक MCP सर्वर बिना एक भी error दिखाए शुरू हो सकता है और फिर भी किसी काम का न हो। प्रोसेस चल रहा होता है, लॉग शांत रहता है, और जिस क्लाइंट से आप उसे जोड़ते हैं वह या तो टूल्स की खाली सूची दिखाता है या "failed to connect" जैसा धुंधला संदेश। क्लाइंट को दोष देने से पहले सर्वर को अकेले टेस्ट करें। MCP Inspector Model Context Protocol प्रोजेक्ट का अपना टूल है जो इसी काम के लिए बना है। यह क्लाइंट की भूमिका निभाता है, handshake करता है, और आपको वह सब लिस्ट और कॉल करने देता है जो आपका सर्वर उपलब्ध कराता है। यह लेख दिखाता है कि इसे npx से कैसे लॉन्च करें, CLI से इसे कैसे चलाएँ, इसके exit codes कैसे पढ़ें, और उन errors को कैसे ठीक करें जो सबसे ज़्यादा समय बर्बाद करते हैं।

💡 वर्ज़न जाँच: ऑनलाइन ज़्यादातर ट्यूटोरियल Inspector v1 के बारे में बताते हैं। लिखते समय npm पर नवीनतम रिलीज़ 2.9.0 है, और v2 ने पोर्ट, एनवायरनमेंट वेरिएबल, फ़्लैग और एग्ज़िट कोड बदल दिए हैं। नीचे दिया हर कमांड v2 के डॉक्यूमेंटेशन के अनुसार है।

MCP Inspector क्या करता है

Inspector debugging के लिए बना MCP क्लाइंट है। यह आपके सर्वर को शुरू करता है (stdio) या उससे कनेक्ट होता है (HTTP या SSE), initialize handshake चलाता है, और ठीक-ठीक दिखाता है कि क्या वापस आया। इसमें कोई लैंग्वेज मॉडल शामिल नहीं होता, इसलिए जब कुछ फेल होता है तो आपको पता रहता है कि गड़बड़ी सर्वर या कनेक्शन में है, प्रॉम्प्ट के व्यवहार में नहीं।

वह Handshake जिसकी जाँच होती है

पहली कॉल, initialize, साबित करती है कि सर्वर MCP बोलता है। जवाब में चार चीज़ें हैं जिन्हें लाइन-दर-लाइन पढ़ना फ़ायदेमंद है:

• serverInfo: आपके सर्वर द्वारा बताया गया नाम और वर्ज़न।
• protocolVersion: वह protocol revision जिस पर दोनों पक्ष सहमत हुए।
• capabilities: कौन-सी सुविधाएँ मौजूद हैं, जैसे tools, resources और prompts।
• instructions: वैकल्पिक टेक्स्ट जो सर्वर क्लाइंट्स को देता है।

अगर capabilities में tools entry नहीं है, तो कोई भी क्लाइंट कभी कोई टूल नहीं दिखाएगा, चाहे आपने कोड में कितने भी रजिस्टर किए हों। यह एक जाँच अकेले "मेरे टूल्स दिखते नहीं" वाली रिपोर्ट्स के बड़े हिस्से की वजह समझा देती है।

Web UI, CLI और TUI

एक पैकेज, तीन फ्रंट एंड। mode flag सबसे पहले आना चाहिए, पैकेज के नाम के ठीक बाद।

जब आप बना रहे हों तब web UI इस्तेमाल करें, और जब ऐसा जवाब चाहिए जिसे बार-बार दोहराया जा सके तब CLI।

npx से इसे लॉन्च करें

इंस्टॉल करने को कुछ नहीं है। npx पैकेज डाउनलोड करता है, उसे चलाता है, और पैकेज के नाम के बाद जो भी लिखा हो वह उस सर्वर को पास कर देता है जिसे आप टेस्ट करना चाहते हैं। एक समझदार पहला रन एक लाइन और एक मिनट का काम है।

Node वर्ज़न और Ports

v2 को Node.js 22.19.0 या उससे नया चाहिए। कुछ भी और करने से पहले node --version चलाएँ, क्योंकि पुराना रनटाइम सबसे पहले जाँचने वाली चीज़ है।

Port और variable में बदलाव पुरानी पोस्ट्स को फॉलो करने वालों को सबसे ज़्यादा परेशान करते हैं, इसलिए यहाँ छोटी तुलना है:

CLIENT_PORT से web UI का पोर्ट बदलें। यह 1 से 65535 के बीच का एक निश्चित पूर्णांक होना चाहिए। v2 MCP Apps sandbox के लिए 6275 और app-origin server के लिए 6278 भी आरक्षित रखता है, इसलिए इन दोनों को खाली रखें।

CLIENT_PORT=6280 npx @modelcontextprotocol/inspector node build/index.js

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

Windows PowerShell पर पहले $env:CLIENT_PORT = "6280" से variable सेट करें और फिर वही npx लाइन चलाएँ।

Arguments और Environment Variables पास करना

build किए हुए Node सर्वर के लिए, कमांड को पैकेज के नाम के ठीक बाद रखें:

npx @modelcontextprotocol/inspector node build/index.js

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

Environment variables -e के साथ डालें:

npx @modelcontextprotocol/inspector -e API_TOKEN=your-token -- node build/index.js

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

बिना build step वाला TypeScript सर्वर भी इसी तरह काम करता है, जैसे npx @modelcontextprotocol/inspector tsx src/index.ts। ज़्यादातर प्रोजेक्ट इस लाइन को npm script में लपेट देते हैं, ताकि पूरी टीम एक ही कमांड चलाए:

{
  "scripts": {
    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
  }
}

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

💡 डबल डैश का मतलब बदल जाता है। web और TUI mode में, -- के बाद जो भी हो वह आपके सर्वर को जाता है। CLI mode में, -- से पहले जो भी हो वह target है और उसके बाद जो हो वह Inspector का option है। CLI mode में सर्वर कमांड भी सबसे पहले आना चाहिए: --cli --method tools/list node build/index.js target को चुपचाप हटा देता है।

UI के पीछे का Token

v2 हर लॉन्च पर एक रैंडम API token बनाता है और हर /api/* route पर उसे माँगता है। बिना उसके खुला पेज रिजेक्ट हो जाता है। अगर आप स्थिर वैल्यू चाहते हैं तो MCP_INSPECTOR_API_TOKEN खुद सेट करें, और अगर कोई tab शिकायत करे तो दोबारा लॉन्च करें, क्योंकि पुराना token पुराने प्रोसेस के साथ ही ख़त्म हो गया था।

Web server डिफ़ॉल्ट रूप से HOST के ज़रिए 127.0.0.1 पर बाइंड होता है। इसे दूसरे interfaces के लिए खोलने को एक साफ़ DANGEROUSLY_BIND_ALL_INTERFACES चाहिए, और DANGEROUSLY_OMIT_AUTH=true token check को पूरी तरह बंद कर देता है। Inspector आपकी ओर से स्थानीय प्रोसेस शुरू करता है, इसलिए token को पासवर्ड की तरह समझें और दोनों overrides साझा मशीनों से दूर रखें।

Config File इस्तेमाल करें

जब किसी सर्वर को तीन arguments और दो environment variables चाहिए, तब कमांड टाइप करना थका देता है। इन्हें एक file में डालें और सर्वर को नाम से चुनें। दो flags हैं, और इन्हें एक साथ इस्तेमाल नहीं किया जा सकता:

डिफ़ॉल्ट कैटलॉग ~/.mcp-inspector/mcp.json पर रहता है। इनमें से कोई भी flag एक ही command line पर ad-hoc target के साथ इस्तेमाल नहीं किया जा सकता।

Stdio Entries

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "node",
      "args": ["build/index.js"],
      "env": { "API_TOKEN": "your-token" },
      "cwd": "/path/to/server"
    }
  }
}

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

command और args के हर आइटम को अलग-अलग एंट्री के रूप में रखें। Inspector उन्हें एक स्ट्रिंग में जोड़ने की जगह सीधे स्पॉन करता है। इससे पाथ में स्पेस होने पर भी आर्ग्युमेंट की सीमाएँ बनी रहती हैं।

HTTP और SSE Entries

{
  "mcpServers": {
    "remote-server": {
      "type": "http",
      "url": "https://mcp.internal.example/mcp",
      "headers": { "X-Tenant": "acme" }
    }
  }
}

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

type field stdio, http (Streamable HTTP) या sse स्वीकार करता है। CLI में आप --server से entry चुनते हैं:

npx @modelcontextprotocol/inspector --cli --config ./mcp.json --server my-server --method tools/list

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

--server केवल CLI mode में सर्वर चुनता है। web client file लोड करते समय चेतावनी देता है और उसे अनदेखा करता है, और TUI उसे अज्ञात option मानकर रिजेक्ट कर देता है।

CLI से MCP सर्वर टेस्ट करें

CLI mode browser को छोड़ देता है और जवाब को stdout पर प्रिंट करता है, इसलिए त्वरित जाँच और उन कामों के लिए यह सही टूल है जिन्हें आप ऑटोमेट करना चाहते हैं। हर कमांड का ढाँचा एक जैसा है: पहले target, फिर --method, फिर वह सब जो उस method को चाहिए।

पहले टूल्स की लिस्ट देखें

हमेशा यह पूछकर शुरू करें कि सर्वर खुद को क्या-क्या देने का दावा करता है:

npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

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

बाकी दो फ़ीचर जाँचने के लिए मेथड को resources/list या prompts/list से बदलें। रिमोट सर्वर को एक पता और एक ट्रांसपोर्ट चाहिए, और अगर वह सुरक्षित है तो एक bearer टोकन भी:

npx @modelcontextprotocol/inspector --cli \
  --transport http --server-url https://example.com/mcp \
  --header 'Authorization: Bearer <token>' \
  --method tools/list

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

आउटपुट के नामों की तुलना उस चीज़ से करें जिसकी आपका क्लाइंट उम्मीद करता है। जो टूल generateImage के रूप में रजिस्टर है पर generate_image के रूप में माँगा जा रहा है, वह एक क्लासिक गड़बड़ी है, और उसे पकड़ने में बस एक कमांड लगता है।

JSON Arguments के साथ टूल कॉल करें

npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call \
  --tool-name generate_image \
  --tool-args-json '{"prompt":"a ceramic mug on an oak desk, soft window light","aspect_ratio":"16:9"}'

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

--tool-args-json एक JSON ऑब्जेक्ट लेता है और कोई टाइप बदलाव नहीं करता, इसलिए नंबर नंबर ही रहते हैं और बूलियन बूलियन ही। तेज़ टेस्ट के लिए --tool-arg prompt="a red door" ज़्यादा छोटा तरीका है, लेकिन उसकी वैल्यू वैध होने पर JSON के रूप में पार्स होती हैं, इसलिए नंबर जैसी दिखने वाली स्ट्रिंग नंबर बन जाती है। जब टाइप मायने रखते हों, तो JSON वाला तरीका इस्तेमाल करें।

💡 Windows नोट: Windows PowerShell 5.1 नेटिव प्रोग्राम को भेजे गए JSON के भीतरी डबल कोट हटा देता है। हर कोट को बैकस्लैश से एस्केप करें, या छोटी वैल्यू के लिए --tool-arg का सहारा लें।

Exit Codes पढ़ें

CLI नतीजा अपने exit code में बताता है, इसलिए किसी script को यह जानने के लिए कभी टेक्स्ट खंगालना नहीं पड़ता कि क्या हुआ।

टेस्टिंग के लिए कोड 5 सबसे ज़्यादा मायने रखता है। जो टूल साफ़ तरीके से फेल होता है, वह अब कमांड को भी फेल कर देता है, इसलिए inspector --cli ... && next-step वहीं रुक जाता है जहाँ v1 आगे बढ़ जाता था। Ad-hoc runs के लिए कनेक्शन डिफ़ॉल्ट रूप से 15 सेकंड में हार मान लेते हैं, और --connect-timeout <ms> उस सीमा को बढ़ा देता है जब आपका सर्वर startup पर कोई database या model लोड करता है।

Inspector Checks को CI में चलाएँ

एक उपयोगी smoke test चार बातें जाँचता है: सर्वर कनेक्ट होता है, टूल मौजूद है, एक वैध कॉल सफल होती है, और एक अवैध कॉल फेल होती है। चार कमांड, कोई browser नहीं, और कोई टूटा हुआ release उपयोगकर्ताओं तक नहीं पहुँचता।

Version Pin करें

CI में एक सटीक वर्ज़न पिन करें, @2.x जैसी रेंज कभी नहीं, क्योंकि मेजर रिलीज़ के बीच फ़्लैग और एग्ज़िट कोड बदल गए थे:

npx --yes @modelcontextprotocol/inspector@2.9.0 --cli node build/index.js --method initialize

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

हर जॉब को उसका अपना टोकन स्टोर दें, ताकि एक रन कभी दूसरे रन की साइन-इन स्थिति दोबारा इस्तेमाल न कर सके:

export MCP_STORAGE_DIR="$(mktemp -d)"
export MCP_INSPECTOR_OAUTH_STATE_PATH="$MCP_STORAGE_DIR/oauth.json"

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

jq से Assert करें

--format json जोड़ें और CLI एक JSON object प्रिंट करता है जिसमें result field होता है, जो jq के लिए तैयार है। दो जाल जानने लायक हैं। पार्स करते समय 2>&1 से stderr को stdout में कभी न मिलाएँ, क्योंकि डायग्नोस्टिक्स JSON के भीतर जा गिरेंगे। और pipe करने से पहले exit status को पकड़ लें, क्योंकि pipeline अपनी आख़िरी कमांड का status दिखाता है, जो एक फेल CLI को एक ख़ुशनुमा jq के पीछे छिपा देता है।

#!/usr/bin/env bash
set -u
INSPECT="npx --yes @modelcontextprotocol/inspector@2.9.0 --cli node build/index.js"

# 1. The handshake works
$INSPECT --method initialize --format json > init.json || exit 1

# 2. The tool exists (status captured before the pipe)
tools=$($INSPECT --method tools/list --format json); code=$?
[ "$code" -eq 0 ] || { echo "tools/list failed with $code"; exit "$code"; }
echo "$tools" | jq -e '.result.tools | map(.name) | index("generate_image")' > /dev/null || exit 1

# 3. A valid call succeeds
$INSPECT --method tools/call --tool-name list_models --tool-args-json '{}' \
  --format json > call.json || exit 1

# 4. An invalid call fails
if $INSPECT --method tools/call --tool-name generate_image --tool-args-json '{}' \
  > /dev/null 2>&1; then
  echo "tool accepted empty input"; exit 1
fi

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

चौथी जाँच वह है जिसे लोग छोड़ देते हैं। एक सर्वर जो बिना प्रॉम्प्ट के भी स्वीकार कर लेता है और खाली इमेज लौटा देता है, वह आपके लिखे हर पॉज़िटिव टेस्ट को पास कर देगा।

आपको दिखने वाली Errors ठीक करें

ज़्यादातर विफलताएँ कुछ पैटर्न में आती हैं। पहले लक्षण मिलाएँ, फिर वह सेक्शन पढ़ें जो उसे समझाता है।

Stdio पर Stdout का प्रदूषण

stdio ट्रांसपोर्ट अपने JSON-RPC मैसेज stdout पर भेजता है, और प्रोटोकॉल कहता है कि सर्वर को वहाँ ऐसा कुछ नहीं लिखना चाहिए जो वैध MCP मैसेज न हो। एक भी भटका हुआ console.log, स्टार्टअप बैनर, या कोई डिपेंडेंसी जो चेतावनी प्रिंट करे, स्ट्रीम को बिगाड़ देती है। तब हैंडशेक पार्स एरर के साथ फ़ेल हो जाता है या बस अटक जाता है।

इसे ठीक करने के लिए हर लॉग लाइन को stderr पर भेजें (console.error Node में, sys.stderr Python में)। दोषी को खोजने के लिए सर्वर कमांड अकेले चलाएँ: एक स्वस्थ stdio सर्वर तब तक कुछ प्रिंट नहीं करता जब तक कोई क्लाइंट उससे बात न करे।

Transport का पता नहीं चला

v2 अब अंदाज़ा नहीं लगाता। वह transport तभी पहचानता है जब URL का path /mcp या /sse पर खत्म होता है, और बाकी किसी भी स्थिति में flag को साफ़-साफ़ लिखना पड़ता है:

npx @modelcontextprotocol/inspector --cli --server-url https://example.com/api \
  --transport http --method tools/list

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

जब कोई error संदेश आपकी समझ में न आए, तो stderr आउटपुट और अपना टूल schema Claude Sonnet 5 या GPT 5.6 Sol में डालें और तीन सबसे संभावित कारण पूछें। दोनों stack traces अच्छी तरह पढ़ते हैं, और जवाब को फिर भी Inspector से जाँचना आपका काम है।

इमेज जनरेशन सर्वर को टेस्ट करना

मीडिया बनाने वाले सर्वर टेस्ट में अलग तरह से व्यवहार करते हैं। कॉल धीमी होती हैं, उनकी कीमत लग सकती है, और काम अक्सर बैकग्राउंड में चलता है। PicassoIA का developer API इस पैटर्न को साफ़ दिखाता है। यह Replicate-style है: आप https://api.picassoia.com/v1 पर POST /v1/models/{owner}/{name}/predictions के साथ एक prediction बनाते हैं, bearer token से प्रमाणित होते हैं, GET /v1/predictions/{id} को poll करते हैं, और पूरा होने पर नतीजा पढ़ते हैं।

लिखते समय API और MCP कनेक्शन वही चार मॉडल उपलब्ध कराते हैं: PicassoIA Image, PicassoIA Image Editor Pro, PicassoIA Video और Seedance 2.5 Lite। एक अकाउंट 5 एक साथ चलने वाली प्रेडिक्शन की अनुमति देता है, जो टोकन और MCP कनेक्शन के बीच साझा होती हैं, और प्रॉम्प्ट 4,000 अक्षरों तक के हो सकते हैं।

💡 टेस्ट सीरियल में करें। एक Inspector session में टूल कॉल्स का loop पाँचों slots भर सकता है और आपके असली क्लाइंट के लिए कोई स्लॉट नहीं बचने देता। इमेज टेस्ट एक बार में एक कॉल करके चलाएँ।

Async Tools को Status Tool चाहिए

जो टूल कोई job शुरू करता है उसे कुछ सेकंड में एक ID लौटानी चाहिए, और एक दूसरा टूल progress बताए। दोनों हिस्सों को अलग-अलग टेस्ट करें:

• स्टार्ट कॉल कनेक्शन को मिनटों तक खुला रखने के बजाय जल्दी एक ID लौटाती है।
• स्टेटस कॉल वह ID लेती है और progress state और अंतिम state बताती है।
• फेल हुआ जॉब isError: true के साथ एक नतीजे के रूप में लौटता है, न कि एक अटकी हुई कॉल के रूप में।
• ग़लत ID exit code 5 देती है, सर्वर प्रोसेस का crash नहीं।
• आउटपुट URL जब आप उसे fetch करते हैं तो status 200 और एक image content type के साथ जवाब देता है।

वह आख़िरी जाँच सबसे आसान है, और वही वह विफलता पकड़ती है जो पाठक सबसे पहले देखते हैं: प्रकाशित पेज पर टूटी हुई इमेज।

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

अब आपके पास यह साबित करने का तरीका है कि कोई सर्वर काम करता है, इससे पहले कि कोई उस पर निर्भर हो। वही आदत रचनात्मक पक्ष पर भी फ़ायदा देती है: एक छोटा टेस्ट चलाएँ, नतीजा पढ़ें, और एक बार में एक चीज़ बदलें।

Picasso IA खोलें और लूप खुद आज़माएँ। PicassoIA Image में एक वाक्य का प्रॉम्प्ट लिखें, PicassoIA Image Editor Pro से नतीजे को निखारें, फिर PicassoIA Video से उस स्थिर इमेज को जीवंत करें। हर रन के बीच लेंस, रोशनी या सब्जेक्ट बदलें और आउटपुट को साथ-साथ रखकर तुलना करें। इस लेख की पाँच कमांड अपने टर्मिनल के पास रखने लायक हैं:

• --method initialize handshake की पुष्टि के लिए।
• --method tools/list टूल नामों की पुष्टि के लिए।
• --method tools/call --tool-args-json व्यवहार की पुष्टि के लिए।
• --format json और jq जवाब पर assert करने के लिए।
• Exit code, जिसे आउटपुट से पहले हमेशा पढ़ें।