Python में MCP सर्वर शुरू से कैसे बनाएँ, चरण दर चरण

अधिकतर MCP ट्यूटोरियल एक मौसम वाले टूल पर रुक जाते हैं जो हार्डकोड की गई एक स्ट्रिंग लौटाता है। यह ट्यूटोरियल एक ऐसा सर्वर बनाता है जिसे आप सच में आगे भी इस्तेमाल कर सकें। आप इसे आधिकारिक Python SDK से शुरू से लिखेंगे, बिना किसी AI क्लाइंट के टेस्ट करेंगे, Claude Desktop और Claude Code से जोड़ेंगे, और अंत में एक असली टूल पर पहुँचेंगे जो इमेज API को कॉल करता है और नतीजे का इंतज़ार करता है। नीचे का सब कुछ Python 3.10 या उससे नए की माँग करता है और MCP Python SDK 2.x से मेल खाता है (लिखे जाने के समय, अक्टूबर 2026 में, PyPI पर 2.3.0)।

अगर आपने 2025 के किसी ट्यूटोरियल का कोड कॉपी किया और ModuleNotFoundError: No module named 'mcp.server.fastmcp' मिला, तो आप सही जगह पर हैं। मुख्य क्लास का नाम बदल दिया गया है, और सेटअप वाले हिस्से में एक लाइन का समाधान दिया गया है।

MCP सर्वर असल में क्या करता है

Model Context Protocol (MCP) एक मानक तरीका है जिससे कोई AI एप्लिकेशन आपका कोड कॉल कर सके। तीन भूमिकाएँ मायने रखती हैं। होस्ट वह ऐप है जिससे व्यक्ति बात करता है, जैसे Claude Desktop या कोई IDE। क्लाइंट होस्ट के अंदर रहता है और प्रोटोकॉल में बात करता है। सर्वर वह हिस्सा है जिसे आप बनाते हैं। आपका सर्वर मॉडल से सीधे बात नहीं करता, वह बस क्लाइंट के अनुरोधों का जवाब देता है।

तीन प्रिमिटिव, तीन नियंत्रक

एक सर्वर ठीक तीन तरह की क्षमताएँ दिखाता है, और इनमें फ़र्क इस बात से होता है कि इन्हें इस्तेमाल करने का फ़ैसला कौन करता है:

अगर आपने कोई वेब API बनाया है, तो मैपिंग जल्दी समझ आ जाती है। एक रिसोर्स GET की तरह काम करता है, एक टूल POST की तरह, और प्रॉम्प्ट एक सेव की हुई क्वेरी है जिसे यूज़र नाम लेकर चलाता है।

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

ट्रांसपोर्ट जल्दी चुनें

ट्रांसपोर्ट वह तरीका है जिससे डेटा क्लाइंट और सर्वर के बीच आता-जाता है। इसे आप mcp.run() के एक आर्गुमेंट से चुनते हैं।

stdio से शुरू करें। आख़िर के पास आप Streamable HTTP पर स्विच करेंगे, और टूल वाला कोड बिल्कुल वैसा ही रहेगा।

पाँच मिनट में Python सेट करें

uv और SDK इंस्टॉल करें

आपको Python 3.10 या उससे नया और uv चाहिए। एक प्रोजेक्ट बनाएँ और SDK जोड़ें:

uv init mcp-image-studio
cd mcp-image-studio
uv add "mcp[cli]" httpx

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

cli एक्स्ट्रा mcp कमांड को mcp dev, mcp run और mcp install के साथ इंस्टॉल करता है। सादा pip install "mcp[cli]" भी काम करता है। Inspector एक Node.js ऐप है, इसलिए npx आपके PATH पर होना चाहिए।

एक रीनेम जो पुराने कोड को तोड़ता है

SDK 1.x में हाई-लेवल क्लास का नाम FastMCP था। 2.x में यह MCPServer है, और यह एक अलग मॉड्यूल में रहती है:

# SDK 1.x, seen in older tutorials
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("Demo")

# SDK 2.x, used in this article
from mcp.server import MCPServer
mcp = MCPServer("Demo")

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

एक और बदलाव लोगों को उलझाता है: port जैसी ट्रांसपोर्ट सेटिंग्स अब कंस्ट्रक्टर से हटकर run() पर चली गई हैं। MCPServer(...) को port= पास करने पर TypeError आता है।

अपना पहला सर्वर लिखें

server.py बनाएँ। एक फ़ाइल, तीन डेकोरेटर, और हर प्रिमिटिव रजिस्टर हो जाता है:

from mcp.server import MCPServer

mcp = MCPServer("Demo")


@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b


@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"


@mcp.prompt()
def summarize(text: str) -> str:
    """Summarize a piece of text in one sentence."""
    return f"Summarize the following text in one sentence:\n\n{text}"


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

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

बस, यह एक काम करने वाला सर्वर है। if __name__ गार्ड मायने रखता है: mcp dev, mcp run, mcp install और आपके टेस्ट, ये सभी इस फ़ाइल को इम्पोर्ट करते हैं, और बिना गार्ड वाला run() जैसे ही कोई इसे लोड करता, सर्वर शुरू हो जाता।

एक टूल जोड़ें

SDK आपके फ़ंक्शन से तीन चीज़ें पढ़ता है। नाम टूल का नाम बनता है, डॉकस्ट्रिंग वह विवरण बनता है जो मॉडल देखता है, और टाइप हिंट आर्गुमेंट स्कीमा बनते हैं। कोई JSON Schema लिखने की ज़रूरत नहीं, क्योंकि a: int, b: int ही स्कीमा है। अगर क्लाइंट किसी ऐसे पैरामीटर में स्ट्रिंग भेजे जिसे आपने integer घोषित किया था, तो SDK आपका फ़ंक्शन चलने से पहले ही कॉल ठुकरा देता है।

किसी पैरामीटर को डिफ़ॉल्ट दें तो वह वैकल्पिक बन जाता है। सख़्त सीमाओं के लिए टाइप को Annotated में लपेटें और Pydantic Field लगाएँ:

from typing import Annotated, Literal
from pydantic import Field


@mcp.tool()
def search_books(
    query: str,
    limit: Annotated[int, Field(ge=1, le=50, description="Maximum results")] = 10,
    genre: Literal["fiction", "non-fiction", "poetry"] = "fiction",
) -> str:
    """Search the catalog by title or author."""
    return f"Found 3 books matching {query!r} (up to {limit})."

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

सीमाएँ स्कीमा में minimum और maximum के रूप में दिखती हैं, और Literal एक एनम बन जाता है जिसमें से मॉडल को चुनना होता है।

एक रिसोर्स और एक प्रॉम्प्ट जोड़ें

रिसोर्स URI में {param} उसे रिसोर्स टेम्पलेट बना देता है, इसलिए greeting://{name} के लिए तब तक कोई एक सूची-प्रविष्टि नहीं होती जब तक कोई नाम न दे। प्रॉम्प्ट और भी सरल है: वह जो स्ट्रिंग लौटाता है वही यूज़र मैसेज बन जाती है। दोनों अपना विवरण टूल की तरह डॉकस्ट्रिंग से पढ़ते हैं।

ऐसे एरर उठाएँ जिन्हें मॉडल पढ़ सके

जब कोई टूल फ़ेल हो, तो ToolError raise करें। कभी एरर स्ट्रिंग न लौटाएँ, क्योंकि लौटाई गई स्ट्रिंग में is_error=False होता है और वह सफल जवाब जैसी लगती है।

from mcp.server.mcpserver.exceptions import ToolError

CATALOG = {"Dune": "Frank Herbert", "Neuromancer": "William Gibson"}


@mcp.tool()
def get_author(title: str) -> str:
    """Look up the author of a book in the catalog."""
    if title not in CATALOG:
        raise ToolError(f"No book titled {title!r} in the catalog.")
    return CATALOG[title]

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

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

💡 जब भी कोई टूल I/O करे, जैसे API कॉल, फ़ाइल रीड या डेटाबेस क्वेरी, तो async def घोषित करें। बाकी सब के लिए सादा def इस्तेमाल करें।

टेस्ट करें और जोड़ें

MCP Inspector चलाएँ

किसी भी AI क्लाइंट को आपके सर्वर को छूने से पहले, उसे Inspector के नीचे चलाएँ:

uv run mcp dev server.py

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

जो URL वह प्रिंट करे उसे खोलें। Inspector server.py को stdio पर सबप्रोसेस के रूप में लॉन्च करता है, ठीक वैसे जैसे असली होस्ट करता। टैब क्रम से देखें:

• Tools: add आपके टाइप हिंट से बने फ़ॉर्म के साथ दिखता है। इसे a=1 और b=2 के साथ कॉल करें, और आपको 3 मिलेगा।
• Resources: सूची खाली होती है, और greeting Resource Templates के नीचे बैठता है। उसे World दें, तो आप Hello, World! पढ़ पाते हैं।
• Prompts: summarize में एक ज़रूरी text आर्गुमेंट है और वह एक ही यूज़र मैसेज लौटाता है।

इन-मेमोरी टेस्ट लिखें

SDK की Client क्लास इन-मेमोरी में भी कनेक्ट होती है: उसे सर्वर ऑब्जेक्ट दें, तो न कोई सबप्रोसेस लगता है और न कोई पोर्ट। pytest को uv add --dev pytest के साथ जोड़ें, फिर test_server.py बनाएँ:

import pytest
from mcp import Client

from server import mcp


@pytest.fixture
def anyio_backend():
    return "asyncio"


@pytest.mark.anyio
async def test_add():
    async with Client(mcp, raise_exceptions=True) as client:
        result = await client.call_tool("add", {"a": 1, "b": 2})
        assert result.structured_content == {"result": 3}

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

raise_exceptions=True को सिर्फ़ टेस्ट में रखें। यह असली एरर मैसेज दिखाता है, न कि वह साफ़ किया हुआ Internal server error जो एक रिमोट कॉलर को दिखता।

Claude Desktop और Claude Code से जोड़ें

हर होस्ट को एक ही चीज़ चाहिए: वह कमांड जो आपका सर्वर शुरू करे। यह कमांड किसी भी डायरेक्टरी से काम करती है, और इसके लिए कोई virtual environment एक्टिवेट नहीं करना पड़ता:

uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py

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

Claude Desktop वह एकमात्र होस्ट है जिसे SDK आपके लिए कॉन्फ़िगर कर सकता है:

uv run mcp install server.py

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

यह claude_desktop_config.json में एक एंट्री लिखता है, जो macOS पर ~/Library/Application Support/Claude/ में और Windows पर %APPDATA%\Claude\ में मिलती है। Claude Desktop को पूरी तरह बंद करें, सिर्फ़ विंडो नहीं, फिर दोबारा खोलें। ऐप आपका सर्वर अपने ही एनवायरनमेंट के साथ शुरू करता है, इसलिए सीक्रेट्स -v NAME=value या -f .env के ज़रिए पास करें।

Claude Code को कोई फ़ाइल नहीं चाहिए। CLI से सर्वर रजिस्टर करें, फिर यह पक्का करने के लिए सेशन के अंदर /mcp चलाएँ कि वह कनेक्ट है:

claude mcp add image-studio -- uv run --with "mcp[cli]" mcp run /absolute/path/to/server.py

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

Cursor mcpServers फ़ील्ड के नीचे .cursor/mcp.json पढ़ता है, और VS Code servers के नीचे .vscode/mcp.json पढ़ता है, जिसमें "type": "stdio" भी होता है। अंदर का कमांड बिल्कुल एक जैसा है।

ऐसे सर्वर को ठीक करें जो दिखता नहीं

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

Claude Desktop हर सर्वर का एक लॉग रखता है, जिसका नाम mcp-server-<NAME>.log है, जो macOS पर ~/Library/Logs/Claude में और Windows पर %APPDATA%\Claude\logs में होता है। वही फ़ाइल आपके सर्वर का stderr है।

एक असली इमेज टूल बनाएँ

सर्वर अपनी उपयोगिता तब साबित करता है जब कोई टूल वह काम करे जो मॉडल अकेले नहीं कर सकता। यह टूल एक प्रॉम्प्ट लेता है, PicassoIA API से एक इमेज माँगता है, और URL लौटाता है।

टूल का कॉन्ट्रैक्ट डिज़ाइन करें

यह API Replicate-शैली की है: आप एक प्रेडिक्शन बनाते हैं, उसे पोल करते हैं, फिर आउटपुट पढ़ते हैं। ये वे तथ्य हैं जिन पर टूल निर्भर करता है:

API डॉक्स बताते हैं कि Infinite प्लान ज़रूरी है, और उसके बिना अनुरोध 403 plan_required लौटाता है। प्रेडिक्शन को मुफ़्त बताया गया है और उनमें कोई क्रेडिट नहीं लगता। किसी और चीज़ को डीबग करने से पहले अपना प्लान जाँच लें।

कॉन्ट्रैक्ट छोटा रखें: एक टूल, दो पैरामीटर, और बदले में एक URL। हर फ़ेल होने वाला रास्ता ToolError उठाता है, ताकि मॉडल को हमेशा पढ़ा जा सकने वाला मैसेज मिले।

बिना ब्लॉक किए async जॉब संभालें

चूँकि जॉब एक रिमोट GPU पर चलता है, टूल को सर्वर को जमाए बिना इंतज़ार करना होगा। इसका मतलब है async def, httpx.AsyncClient और asyncio.sleep:

import asyncio
import os
from typing import Literal

import httpx
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError

API = "https://api.picassoia.com/v1"
MODEL = "picassoia/picassoia-image"
DONE = ("succeeded", "failed", "canceled")

mcp = MCPServer("Image Studio")
slots = asyncio.Semaphore(4)


@mcp.tool()
async def generate_image(
    prompt: str,
    aspect_ratio: Literal["1:1", "16:9", "9:16", "4:3"] = "16:9",
) -> str:
    """Generate an image from a text prompt and return its URL."""
    token = os.environ.get("PICASSOIA_API_TOKEN")
    if not token:
        raise ToolError("PICASSOIA_API_TOKEN is not set for this server.")

    headers = {"Authorization": f"Bearer {token}"}
    body = {"input": {"prompt": prompt, "aspect_ratio": aspect_ratio}}

    async with slots, httpx.AsyncClient(headers=headers, timeout=30) as http:
        response = await http.post(f"{API}/models/{MODEL}/predictions", json=body)
        prediction = response.json()
        if not response.is_success:
            raise ToolError(f"{prediction.get('code')}: {prediction.get('detail')}")

        while prediction["status"] not in DONE:
            eta = prediction.get("eta") or {}
            await asyncio.sleep(eta.get("next_poll_in_seconds", 2))
            prediction = (await http.get(prediction["urls"]["get"])).json()

    if prediction["status"] != "succeeded":
        raise ToolError(prediction.get("error") or prediction["status"])

    output = prediction["output"]
    return output[0] if isinstance(output, list) else output


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

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

तीन बातें इसे चालू छोड़ने के लिए सुरक्षित बनाती हैं:

1. सर्वर के शेड्यूल पर पोल करें। रिस्पॉन्स में eta.next_poll_in_seconds होता है, इसलिए आप उतनी ही देर सोते हैं जितनी API माँगती है।
2. अपनी कॉन्करेंसी सीमित करें। Semaphore(4) एक बहुत ज़्यादा अनुरोध करने वाले मॉडल को सारे 5 अकाउंट स्लॉट लेने से रोकता है।
3. टोकन एनवायरनमेंट से पढ़ें। इसे mcp install server.py -v PICASSOIA_API_TOKEN=pia_sk_... के साथ रजिस्टर करें, और फ़ाइल में कभी पेस्ट न करें।

💡 output फ़ील्ड URL की सूची हो सकती है, एक URL हो सकता है, या null। आख़िरी दो लाइनें पहली दो स्थितियाँ सँभालती हैं, और उनके ऊपर वाला succeeded चेक व्यवहार में null को बाहर कर देता है।

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

टूल का कोड लिखने में भाषा मॉडल सबसे ज़्यादा समय बचाता है। PicassoIA पर Claude Sonnet 5 मल्टी-स्टेप कोडिंग और टूल-यूज़ के काम सँभालता है, इसलिए आप काम कर रहा generate_image टूल पेस्ट करके अगला माँग सकते हैं।

1. मॉडल का पेज खोलें Claude Sonnet 5 के लिए।
2. प्रॉम्प्ट लिखें। अपना सर्वर पेस्ट करें और माँगें: GET /v1/predictions के साथ एक दूसरा टूल जोड़ें जो मेरी हाल की प्रेडिक्शन सूचीबद्ध करे। वही एरर हैंडलिंग दोबारा इस्तेमाल करें। prompt फ़ील्ड ही एकमात्र ज़रूरी फ़ील्ड है।
3. सिस्टम प्रॉम्प्ट सेट करें ताकि रीनेम वाली समस्या शुरू होने से पहले ही रुक जाए: आप MCP SDK 2.x के लिए Python लिखते हैं। mcp.server से MCPServer इम्पोर्ट करें और कभी FastMCP इस्तेमाल न करें।
4. एफ़र्ट चुनें। डिफ़ॉल्ट low एक्सटेंडेड थिंकिंग छोड़ देता है और सबसे तेज़ है। कई फ़ाइलों को छूने वाले बग के लिए high या max इस्तेमाल करें।
5. पूरी सर्वर फ़ाइलों के लिए मैक्स टोकन 8192 रखें, या किसी छोटे स्निपेट के लिए इसे कम करें।
6. अगर आपके पास Inspector एरर का स्क्रीनशॉट है, तो उसे अटैच करें। मॉडल इमेज पढ़ता है, और max_image_resolution (डिफ़ॉल्ट 0.5 megapixels) उन्हें छोटा कर देता है।
7. जनरेट करें, कॉपी करें, और टेस्ट करें। नतीजा server.py में पेस्ट करें और उस पर भरोसा करने से पहले mcp dev के ज़रिए चलाएँ।

कोई और मॉडल पसंद है? Kimi K2.6 उसी श्रेणी में है और एजेंट बनाने व कोड लिखने के लिए बताया गया है।

HTTP पर शिप करें

ट्रांसपोर्ट बदलें

server.py के आख़िर में एक लाइन बदलें:

if __name__ == "__main__":
    mcp.run(transport="streamable-http", port=3001)

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

क्लाइंट अब http://127.0.0.1:3001/mcp से कनेक्ट होते हैं। आप फ़ाइल को छुए बिना uv run mcp run server.py --transport streamable-http भी चला सकते हैं। run() कॉल ये विकल्प लेती है:

• host और port, जिनका डिफ़ॉल्ट 127.0.0.1 और 8000 है
• streamable_http_path, जिसका डिफ़ॉल्ट /mcp है
• json_response=True, ताकि हर POST का जवाब एक JSON बॉडी में मिले
• stateless_http=True, हर अनुरोध के लिए नया ट्रांसपोर्ट

रिमोट सर्वर को Claude Code में claude mcp add --transport http image-studio https://mcp.example.com/mcp से रजिस्टर करें।

इसे सुरक्षित करें

एक बार आपका सर्वर localhost से बाहर जाए, तो तीन चीज़ें बदल जाती हैं:

• Host allowlist। डिफ़ॉल्ट सिर्फ़ 127.0.0.1, localhost और [::1] स्वीकार करता है। किसी असली होस्टनेम के पीछे, हर अनुरोध 421 Misdirected Request और Invalid Host header के साथ फ़ेल होता है। इसे transport_security= से ठीक करें और allowed_hosts में "mcp.example.com" और "mcp.example.com:*" दोनों डालें।
• Authorization। आपका सर्वर एक OAuth 2.1 resource server है। TokenVerifier लागू करें, जिसमें एक async verify_token मेथड हो जो एक्सेस टोकन या None लौटाए, और token_verifier= को auth= के साथ पास करें।
• प्रॉक्सी के पीछे TLS। जब लोड बैलेंसर TLS खत्म करे, तो uvicorn को --proxy-headers के साथ शुरू करें ताकि वह फ़ॉरवर्ड हेडर पर भरोसा करे।

💡 421 एक सादा HTTP रिस्पॉन्स है, प्रोटोकॉल एरर नहीं, इसलिए क्लाइंट को बस एक सामान्य ट्रांसपोर्ट फ़ेल्योर दिखता है। जिस होस्टनेम पर आपत्ति हुई वह सर्वर के लॉग में दिखता है। जो नया डिप्लॉय किया सर्वर हर कनेक्शन ठुकराए, उसे तब तक Host allowlist की समस्या मानें जब तक उलटा साबित न हो।

Picasso IA के साथ अपनी इमेज बनाएँ

अब आपके पास एक ऐसा सर्वर है जो टूल, रिसोर्स और प्रॉम्प्ट रजिस्टर करता है, इन-मेमोरी टेस्ट पास करता है, Claude के अंदर चलता है, और एक असली होस्टनेम के पीछे डिप्लॉय हो सकता है। अगले घंटे का सबसे क़ीमती हिस्सा टूल ही है: मॉडल slug बदलें, एक edit_image टूल जोड़ें, या उसके बगल में एक वीडियो टूल जोड़ें।

वही मॉडल आज़माएँ जिसे आपके सर्वर ने अभी कॉल किया। PicassoIA Image एक प्रॉम्प्ट को कुछ ही सेकंड में तैयार तस्वीर में बदल देता है, और ऑटोमेट करने से पहले आप किसी भी प्रॉम्प्ट को ब्राउज़र में टेस्ट कर सकते हैं। जब एक स्थिर तस्वीर काफ़ी न हो, तो PicassoIA Video और Seedance 2.5 Lite किसी प्रॉम्प्ट या फ़ोटो को छोटे क्लिप में ऐनिमेट करते हैं।

Picasso IA खोलें, एक मॉडल चुनें, और वही प्रॉम्प्ट चलाएँ जो आप अपने टूल को देते। फिर उसे अपने सर्वर से जोड़ें और Claude को क्लिक करने दें।