MCP सर्वर ट्यूटोरियल: शुरुआती लोगों के लिए सेटअप, उदाहरण और पहला टूल

आपका AI असिस्टेंट स्प्रेडशीट पर सॉनेट लिख सकता है, लेकिन पूछिए कि आपके लैपटॉप पर कोई फ़ाइल कितनी बड़ी है, तो वह कंधे उचका देता है। Model Context Protocol यही दूरी मिटाता है। MCP सर्वर एक छोटा प्रोग्राम है जो असिस्टेंट को असली क्षमताएँ देता है: फ़ोल्डर पढ़ना, डेटाबेस से क्वेरी करना, API कॉल करना, यहाँ तक कि इमेज जनरेट करना। यह ट्यूटोरियल एक खाली फ़ोल्डर से शुरू होकर लगभग बीस मिनट में एक काम करने वाला पहला टूल बनाता है, और इसके लिए प्रोटोकॉल का पहले से कोई अनुभव ज़रूरी नहीं है।

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

MCP सर्वर क्या करता है

USB-C की मिसाल

USB-C से पहले, हर गैजेट को अपनी अलग केबल चाहिए थी। MCP AI के लिए वही काम करता है जो उस एक पोर्ट ने हार्डवेयर के लिए किया। इसके बिना, हर असिस्टेंट को हर सेवा के लिए अलग कोड चाहिए था, यानी N असिस्टेंट गुणा M सेवाएँ जितना आपस में जोड़ने वाला कोड। इसके साथ, आप एक सर्वर लिखते हैं और हर MCP-संगत क्लाइंट उसका इस्तेमाल कर सकता है।

Anthropic ने यह प्रोटोकॉल 2024 के आख़िर में पेश किया था, और तब से कई चैट ऐप, कोड एडिटर और एजेंट फ़्रेमवर्क इसे अपना चुके हैं। यही अपनाया जाना इसे सीखने की असली वजह है: आज आप जो टूल बनाते हैं वह किसी एक प्रोडक्ट तक सीमित नहीं रहता, और जो कौशल आप सीखते हैं वह हर उस क्लाइंट में काम आता है जो इस प्रोटोकॉल को समझता है।

होस्ट, क्लाइंट और सर्वर

हर MCP बातचीत में तीन भूमिकाएँ दिखती हैं, और शुरुआती लोग अक्सर इन्हें आपस में मिला देते हैं।

संदेश JSON-RPC 2.0 में चलते हैं। लोकल सर्वर stdio पर बात करता है: होस्ट आपकी स्क्रिप्ट को चाइल्ड प्रोसेस के रूप में लॉन्च करता है और उसके इनपुट व आउटपुट स्ट्रीम से संदेशों का आदान-प्रदान होता है। रिमोट सर्वर Streamable HTTP पर बात करता है, और होस्टेड कनेक्टर इसी तरह काम करते हैं।

जब आप कोई सवाल पूछते हैं, तो यह होता है:

1. होस्ट आपका सर्वर शुरू करता है, और उसका क्लाइंट पूछता है, "आप क्या कर सकते हैं?"
2. सर्वर टूल्स की सूची और हर एक का स्कीमा लौटाता है।
3. आप एक सवाल पूछते हैं। मॉडल तय करता है कि कोई टूल फिट बैठता है और आर्गुमेंट्स के साथ कॉल भेजता है।
4. होस्ट अनुमति का प्रॉम्प्ट दिखाता है, फिर कॉल आपके सर्वर को भेजता है।
5. आपका फ़ंक्शन चलता है, नतीजा वापस आता है, और मॉडल अंतिम जवाब लिखता है।

टूल्स, रिसोर्सेज़ और प्रॉम्प्ट

एक सर्वर तीन तरह की चीज़ें दे सकता है, और हर एक का मालिक अलग होता है।

💡 पहले टूल बनाएँ। ये सबसे व्यापक रूप से समर्थित प्रिमिटिव हैं, और एक काम करने वाला टूल आपको प्रोटोकॉल की ज़्यादातर माँगें सिखा देता है।

अपना एनवायरनमेंट सेट करें

आपको क्या चाहिए

कोई भी कोड टाइप करने से पहले चार चीज़ें जुटा लें:

• Python 3.10 या नया। python --version से जाँचें।
• Node.js 18 या नया, केवल Inspector डिबगर के लिए, जो npx के ज़रिए चलता है।
• एक टर्मिनल और कोई भी कोड एडिटर, सादा भी चलेगा।
• एक MCP क्लाइंट, जैसे Claude Desktop, Claude Code या कोई संगत एडिटर।

Windows, macOS और Linux, तीनों पर यह काम करता है। बस वर्चुअल एनवायरनमेंट एक्टिवेट करने वाला कमांड बदलता है, और नीचे दिया कोड हर सिस्टम पर एक जैसा है।

Python या TypeScript?

कई भाषाओं के लिए आधिकारिक SDK मौजूद हैं। पहले सर्वर के लिए दो सबसे सुरक्षित विकल्प हैं:

यह ट्यूटोरियल Python इस्तेमाल करता है। टूल्स से लेकर ट्रांसपोर्ट तक की अवधारणाएँ बिना बदले हर दूसरे SDK में भी लागू होती हैं।

अपना पहला टूल लिखें

प्रोजेक्ट बनाएँ

एक फ़ोल्डर बनाएँ, एक अलग एनवायरनमेंट जोड़ें और SDK इंस्टॉल करें:

mkdir word-counter
cd word-counter
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install "mcp[cli]"

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

[cli] एक्सट्रा से mcp कमांड इंस्टॉल होता है, जिसमें जल्दी टेस्ट के लिए एक dev रनर शामिल है।

15 लाइनों में आपका टूल

इस सामग्री के साथ server.py बनाएँ:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("word-counter")

@mcp.tool()
def count_words(text: str) -> dict:
    """Count the words, characters and lines in a piece of text."""
    return {
        "words": len(text.split()),
        "characters": len(text),
        "lines": len(text.splitlines()),
    }

if __name__ == "__main__":
    mcp.run(transport="stdio")

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

तीन विवरण सारा काम करते हैं:

1. डॉकस्ट्रिंग वह है जिसे मॉडल पढ़ता है यह तय करने के लिए कि टूल को कब कॉल करना है। इसे एक लाइन के जॉब डिस्क्रिप्शन की तरह लिखें।
2. टाइप हिंट्स (text: str) JSON स्कीमा बन जाते हैं, जो क्लाइंट को बताता है कि कौन से आर्गुमेंट मौजूद हैं और हर एक किस टाइप का है।
3. रिटर्न वैल्यू सीरियलाइज़ होकर टूल के नतीजे के रूप में मॉडल को वापस भेजी जाती है।

जब कोई क्लाइंट जुड़ता है, तो वह सर्वर से टूल्स की सूची माँगता है। FastMCP count_words नाम, आपकी डॉकस्ट्रिंग को विवरण के रूप में, और सिग्नेचर से बने इनपुट स्कीमा के साथ जवाब देता है: एक ऑब्जेक्ट जिसमें text नाम की एक ज़रूरी स्ट्रिंग प्रॉपर्टी है। यह छोटा JSON दस्तावेज़ ही वह सब है जो मॉडल आपके फ़ंक्शन के बारे में जानता है, इसीलिए नाम और शब्दों का चुनाव किसी चतुर कोड से ज़्यादा मायने रखता है।

💡 अगर कोई टूल कभी कॉल नहीं होता, तो कारण लगभग हमेशा एक अस्पष्ट डॉकस्ट्रिंग होती है, आपके कोड का बग नहीं।

Inspector में टेस्ट करें

अभी कोई चैट ऐप न जोड़ें। MCP Inspector, एक ब्राउज़र-आधारित टेस्ट बेंच, में डिबग करें:

npx @modelcontextprotocol/inspector python server.py

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

एक लोकल पेज खुलता है। फिर:

1. अपना सर्वर लॉन्च करने के लिए Connect पर क्लिक करें।
2. Tools टैब खोलें और List Tools दबाएँ। count_words दिखना चाहिए।
3. उसे चुनें, text फ़ील्ड में एक वाक्य लिखें और रन करें।
4. जाँचें कि JSON नतीजा सही गिनती दिखाता है।

⚠️ stdio सर्वर में कभी print() का इस्तेमाल न करें। स्टैंडर्ड आउटपुट ही मैसेज चैनल है, और एक गलत प्रिंट उसे बिगाड़ देता है। लॉग को stderr पर भेजें या Python के logging मॉड्यूल का उपयोग करें।

इसे एक असली क्लाइंट से जोड़ें

जब Inspector में सब हरा दिखे, तो सर्वर को किसी क्लाइंट में रजिस्टर करें। Claude Desktop के लिए, claude_desktop_config.json फ़ाइल में यह जोड़ें:

{
  "mcpServers": {
    "word-counter": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

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

Claude Code के लिए, एक कमांड वही काम करता है:

claude mcp add word-counter -- /absolute/path/to/.venv/bin/python /absolute/path/to/server.py

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

ऐप को पूरी तरह रीस्टार्ट करें, फिर पूछें: "इस पैराग्राफ़ में कितने शब्द हैं?" और उसके बाद कुछ टेक्स्ट लिखें। क्लाइंट अनुमति माँगता है, count_words चलाता है और अनुमान की जगह सटीक संख्या बताता है।

अगर कुछ नहीं दिखता, तो इन्हें क्रम से जाँचें:

• केवल एब्सोल्यूट पाथ। रिलेटिव पाथ टूटते हैं, क्योंकि होस्ट प्रोसेस को अपने फ़ोल्डर से लॉन्च करता है।
• venv इंटरप्रेटर की ओर इशारा करें। सादा python अक्सर किसी दूसरे इंस्टॉल को पकड़ता है, जिसमें SDK नहीं होता।
• ऐप को पूरी तरह बंद करें। विंडो बंद करने पर वह अक्सर ट्रे में चलता रहता है।
• लॉग पढ़ें। क्लाइंट हर सर्वर के लिए अलग लॉग लिखते हैं, जिनमें सटीक ट्रेसबैक होता है।

जब एक लोकल स्क्रिप्ट काफ़ी न रहे, तो mcp.run(transport="streamable-http") से ट्रांसपोर्ट बदलें, उसे HTTPS के पीछे होस्ट करें और ऑथेंटिकेशन जोड़ें। टूल का कोड बिल्कुल वही रहता है, और किसी प्रोटोकॉल पर बनाने का यही चुपचाप मिलने वाला फ़ायदा है।

कॉपी करने लायक तीन उदाहरण

केवल-पढ़ने वाला रिसोर्स

रिसोर्सेज़ डेटा को URI से उपलब्ध कराते हैं। यह एक नोट्स फ़ाइल परोसता है:

from pathlib import Path

@mcp.resource("notes://today")
def todays_notes() -> str:
    """Return the contents of today's notes file."""
    return Path("notes/today.md").read_text(encoding="utf-8")

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

ऐप इसे बिना मॉडल के कोई कॉल किए संदर्भ के रूप में जोड़ सकता है। रिसोर्सेज़ notes://{date} जैसे URI टेम्पलेट भी इस्तेमाल कर सकते हैं, ताकि एक फ़ंक्शन फ़ाइलों के पूरे परिवार को सेवा दे।

एक प्रॉम्प्ट टेम्पलेट

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

@mcp.prompt()
def review_code(code: str) -> str:
    """Ask for a short, friendly code review."""
    return f"Review this code and list the three most important fixes:\n\n{code}"

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

एक टूल जो API को कॉल करता है

ज़्यादातर असली सर्वर किसी वेब सेवा को रैप करते हैं। यह जाँचता है कि कोई साइट चालू है या नहीं:

import httpx

@mcp.tool()
async def check_site(url: str) -> str:
    """Return the HTTP status code of a website."""
    async with httpx.AsyncClient(timeout=10) as client:
        response = await client.get(url, follow_redirects=True)
    return f"{url} answered with status {response.status_code}"

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

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

वो गलतियाँ जो आपकी दोपहर बर्बाद करती हैं

नाम रखना ऊपर की तालिका जितना ही मददगार है। ऐसे क्रिया-शब्द चुनें जो बताएँ कि क्या होता है, जैसे count_words या check_site, हर टूल को एक ही काम तक सीमित रखें, और आर्गुमेंट्स को उतने ही तक सीमित रखें जितने मॉडल को सच में चाहिए। छह वैकल्पिक फ़ील्ड वाला process टूल गलत अनुमान लगाने का न्योता है।

एक्सेस को सख़्त रखें

टूल वह कोड है जिसे मॉडल आपकी मशीन पर चला सकता है, इसलिए इसे सावधानी से बरतें:

• केवल-पढ़ने को प्राथमिकता दें। राइट या डिलीट टूल तभी जोड़ें जब सच में ज़रूरत हो।
• इनपुट वैलिडेट करें। फ़ाइल टूल को चुने हुए एक फ़ोल्डर के बाहर के पाथ ठुकरा देने चाहिए।
• सीक्रेट्स को कोड से बाहर रखें। टोकन को क्लाइंट कॉन्फ़िग के env फ़ील्ड से पास करें, जिससे वे आपके रिपॉज़िटरी से बाहर रहते हैं।
• अनुमति प्रॉम्प्ट पढ़ें। ऐसे किसी टूल कॉल को मंज़ूरी न दें जिसे आप समझा न सकें।

MCP के ज़रिए PicassoIA से जुड़ें

कनेक्टर क्या देता है

सर्वर केवल लोकल स्क्रिप्ट तक सीमित नहीं हैं। PicassoIA MCP क्लाइंट्स को इमेज और वीडियो जनरेशन उपलब्ध कराता है, ताकि कोई असिस्टेंट सीधे चैट से मीडिया बना सके। कनेक्टर और डेवलपर API एक ही चार मॉडल साझा करते हैं:

अंदरूनी तौर पर API एक परिचित पैटर्न का पालन करता है: प्रेडिक्शन बनाएँ, उसकी स्थिति पोल करें, फिर नतीजा लाएँ। अनुरोध Bearer टोकन इस्तेमाल करते हैं, प्रॉम्प्ट 4,000 अक्षरों तक हो सकते हैं, और एक अकाउंट एक साथ अधिकतम 5 प्रेडिक्शन चला सकता है, जो सभी टोकन और MCP कनेक्शन में साझा होते हैं। कनेक्शन PicassoIA अकाउंट के MCP पेज से मैनेज करें, और यह जानने के लिए अपना प्लान देखें कि MCP एक्सेस में क्या शामिल है।

LLM से टूल कोड का ड्राफ़्ट बनवाएँ

आपको हर टूल हाथ से लिखने की ज़रूरत नहीं है। लार्ज लैंग्वेज मॉडल एक सादे वाक्य को पहले ड्राफ़्ट में बदल देते हैं, जिसे आप Inspector में टेस्ट कर सकते हैं:

टूल को एक वाक्य में बताएँ, FastMCP वर्ज़न माँगें, और उस पर भरोसा करने से पहले उसे Inspector में चलाएँ। मॉडल सही लगने वाला कोड लिखते हैं, और Inspector ही वह तरीका है जिससे आप उन हिस्सों को खोजते हैं जो दिखते तो ठीक हैं पर गलत हैं।

चैट से इमेज जनरेट करें

कनेक्ट होने के बाद, वर्कफ़्लो छोटा है:

1. MCP-सक्षम चैट खोलें और पुष्टि करें कि PicassoIA कनेक्टर सक्रिय है।
2. शॉट को ठोस विवरणों के साथ बताएँ: सब्जेक्ट, लेंस, रोशनी और मूड। "ओक की मेज़ पर एक सिरेमिक मग, बाईं ओर से नरम खिड़की की रोशनी, 50mm लेंस" जैसी लाइन "अच्छी कॉफ़ी फ़ोटो" से बेहतर है।
3. असिस्टेंट को PicassoIA Image कॉल करने दें और नतीजे का इंतज़ार करें।
4. फिर से शुरू करने के बजाय PicassoIA Image Editor Pro से रिफ़ाइन करें।
5. सबसे अच्छे फ़्रेम को PicassoIA Video से एनिमेट करें।

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

💡 जनरेशन एसिंक्रोनस है। अगर क्लाइंट "pending" दिखाता है, तो वह पोल कर रहा है, फ़ेल नहीं हो रहा।

आज Picasso IA पर आज़माएँ

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

फिर रचनात्मक पक्ष को काम पर लगाएँ। Picasso IA पर जाएँ, PicassoIA Image जैसा मॉडल चुनें, और एक वाक्य से अपनी पहली इमेज बनाएँ। रोशनी, लेंस और मूड के साथ प्रयोग करें, सबसे अच्छे नतीजे को Seedance 2.5 Lite पर भेजकर उसमें जान डालें, और देखें कि एक अच्छा प्रॉम्प्ट कितनी दूर तक जा सकता है।