🪪 धडा 04 — Wire: badge, discovery, calls (protocol आवृत्ती 2026-07-28)

📍 तुम्ही इथे आहात: 8 पैकी धडा 04 · मागे: lesson-03-primitives · पुढे: lesson-05-transports-security

📦 या ब्रँचमध्ये काय आहे

धडे 01–03, आणि खरा संवाद, संदेशा-संदेशाने — protocol म्हणजेच असलेली sequence आकृती, आवृत्ती 2026-07-28 नुसार (सध्याची; ❓ काय च्या शेवटचा box काय बदलले आणि का ते सांगतो).

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

खोलीत उपकरण जोडण्याची सुरुवात पूर्वी एका छोट्या विधीने व्हायची ("नमस्कार, मी socket-standard 2025 बोलतो"). आता नाही. आता प्रत्येक message ओळखपत्राचा badge घालतो 🪪, म्हणून कोणत्याही विधीची गरज नाही:

🪪 Badge. प्रत्येक request _meta घेऊन येतो: मी कोणती आवृत्ती बोलतो (io.modelcontextprotocol/protocolVersion), मी कोण आहे (…/clientInfo) आणि मी काय करू शकतो (…/clientCapabilities). उपकरण प्रत्येक message वरचा badge तपासते आणि उत्तर देते — किंवा ती आवृत्ती बोलत नसेल तर तसे सांगते (UnsupportedProtocolVersion, आणि ते बोलते त्या आवृत्त्यांची यादी). ऐच्छिक पण सभ्य: ओळख (server/discover) — "तू कोण आहेस, कोणती भाषा बोलतोस, कोणते कप्पे भरतोस?" आपला client नेहमी विचारतो; client हे टाळून थेट बोलायला सुरुवातही करू शकतो.
📋 "तू काय देतोस?" (tools/list) — उपकरण आपला कप्पा वाचून दाखवते: नावे, वर्णने, input forms.
🧰 "ते काम कर." (tools/call नाव + arguments सह) — उपकरण खरे काम करते आणि बाकासाठी content परत देते.

बस्स… हीच संपूर्ण भाषा. तीन क्रियापदे आणि एक badge. प्रत्येक message JSON-RPC 2.0 असतो: requests मध्ये id असतो (उत्तरांनी तो परत सांगायलाच हवा — त्यावरूनच socket प्रश्नाची उत्तराशी जोडणी करते), notifications मध्ये नसतो (पाठवा आणि विसरा — आपला server त्यांकडे दुर्लक्ष करतो), errors code सह error म्हणून येतात. प्रत्येक result resultType: "complete" सांगतो आणि server चा स्वतःचा badge (_meta → serverInfo) घेऊन येतो.

🗺️ आकृती — तुम्हाला सगळीकडे दिसणारा क्रम

sequenceDiagram
    participant H as 🔌 client (in the host)
    participant S as 🔬 server
    H->>S: 1 server/discover {_meta: protocolVersion, clientInfo, clientCapabilities} — optional
    S-->>H: 2 {resultType, supportedVersions: ["2026-07-28"], capabilities: {tools}, _meta: {serverInfo}}
    H->>S: 3 tools/list {_meta: …the same badge, every time}
    S-->>H: 4 {resultType, tools: [{name, description, inputSchema}, …], ttlMs}
    H->>S: 5 tools/call {name: "lookup_grade", arguments: {student: "katrina"}, _meta: …}
    S-->>H: 6 {resultType, content: [{type: "text", text: "Katrina (3A) has grade A+."}], isError: false}
    Note over H,S: three verbs and a badge — that's the protocol 🪪 (no handshake since 2026-07-28)

❓ काय

JSON-RPC 2.0 चे आकार (आपल्या demo output मध्ये सगळे दिसतात):
- request: {"jsonrpc":"2.0","id":N,"method":"…","params":{…, "_meta":{…}}}
- response: {"jsonrpc":"2.0","id":N,"result":{"resultType":"complete", …}} (तोच id!)
- error: {"jsonrpc":"2.0","id":N,"error":{"code":…,"message":…,"data":…}}
- notification: id नाही → कधीच response नाही.
Version negotiation प्रत्येक request वर होते: badge एका आवृत्तीचे नाव सांगतो (इथे 2026-07-28); ती न बोलणारा server data.supported: [...] सह -32022 Unsupported protocol version असे उत्तर देतो, आणि client त्यांपैकी एका आवृत्तीने पुन्हा प्रयत्न करतो. Session नाही, requests मध्ये तुमची कोणतीही आठवण नाही — म्हणूनच load balancer मागील कोणताही server instance कोणत्याही request ला उत्तर देऊ शकतो.
Capabilities = कप्प्यांची यादी (L03), ज्यांचे उत्तर server/discover देतो: आपला server {"tools": {}} म्हणतो. Clients आपल्या badge मध्ये स्वतःच्या जाहीर करतात — हे दोन्ही बाजूंनी होते.
Results मध्ये नेहमी resultType असतो — "complete", किंवा server ला आधी host कडून काहीतरी हवे असेल तेव्हा "input_required" (server ने सुरू केलेल्या sampling/elicitation requests ची जागा घेणारी multi-round-trip पद्धत) — आणि बहुधा _meta.serverInfo. List results मध्ये ttlMs/cacheScope जोडले जातात, म्हणजे hosts कप्पा cache करू शकतात.
Tool results म्हणजे content arrays ({"type":"text",…} — images आणि इतरही आहेत) आणि isError — tool अपयश म्हणजे model ने प्रतिसाद द्यावा असा data, protocol crash नव्हे. अज्ञात tool नाव मात्र protocol error असतो (-32602). school_server.py मधील tools/call handler पाहा: दोन्ही प्रकार तिथे आहेत.
इतर कप्प्यांसाठी आणखी verbs आहेत (resources/list, prompts/get, …) आणि बदलांच्या notifications साठीही (subscriptions/listen) — तेच व्याकरण, गरज लागेल तेव्हा शिका.

⏳ काय बदलले, आणि जुनी पद्धत तुम्हाला अजूनही का भेटेल. आवृत्ती 2025-11-25 पर्यंत प्रत्येक session handshake ने सुरू व्हायचे — initialize → notifications/initialized — आणि server तुम्हाला लक्षात ठेवायचा (एक session; HTTP वर Mcp-Session-Id). आवृत्ती 2026-07-28 ने ते निवृत्त केले: requests स्वतःचे वर्णन स्वतः करतात, sessions गेले, आणि server/discover हा आधीच विचारण्याचा ऐच्छिक मार्ग आहे. जुने servers अजूनही handshake अपेक्षित धरतात; आपला client मुद्दाम फक्त आधुनिक आवृत्ती बोलतो, आणि आपला server जुन्या initialize ला -32022 आणि तो बोलतो त्या आवृत्त्यांची यादी देऊन उत्तर देतो — जुन्या client शी प्रामाणिक राहण्याचा spec ने शिफारस केलेला मार्ग.

🤔 का

एकदा तुम्ही wire वाचू शकलात की MCP debugging अंदाजपंचे न राहता k8s च्या धडा 16 सारखे triage बनते: पहिल्याच request वर -32022? (version mismatch — badge ने server न बोलणाऱ्या आवृत्तीचे नाव सांगितले.) Tool कधीच call झाला नाही? (वाईट वर्णन — model ला तुमचा कप्पा नीट दिसत नाही, L03.) Call अडकतो? (id mismatch किंवा server मेला — stderr तपासा.) "MCP चालत नाही" पैकी नव्वद टक्के प्रकरणे तुम्हाला आता तोंडपाठ असलेल्या सहा messages मध्ये दिसतात.

🧪 करून पाहा — आकृती, live

python3 client/mini_client.py

या धड्याची sequence आकृती output शेजारी ठेवा: messages 1–6, क्रमाने, खरे. मग झटपट प्रश्न: प्रत्येक → ओळीवर कोणते field असते? (_meta badge.) आता मुद्दाम मोडा — mini_client.py मधील BADGE ची META + "protocolVersion" ओळ comment out करा, पुन्हा चालवा, आणि server चा नकार वाचा: -32022, तो बोलतो त्या आवृत्त्यांसह. ती परत लावा, --drive सह चालवा, lookup_grade {"student":"nobody"} call करा — wire मध्ये नम्र isError उत्तर शोधा; मग दुसऱ्या प्रकारच्या error साठी fly_to_moon {}.

✅ तपासा — तुम्हाला काय दिसायला हवे

Scripted run नेमक्या याच क्रमाने सहा messages दाखवतो: server/discover → त्याचा result (supportedVersions, capabilities, _meta.serverInfo); tools/list → {resultType, tools:[…]}; tools/call → {resultType, content:[…], isError:false}. प्रत्येक → ओळीवर io.modelcontextprotocol/protocolVersion: "2026-07-28" असलेला _meta badge असतो. BADGE मधून protocolVersion ओळ काढा आणि पहिले उत्तर supported: ["2026-07-28"] ची यादी देणारे error -32022 Unsupported protocol version बनते.

🏁 तुम्ही आत्ताच काय सिद्ध केले

तुम्ही सध्याचे MCP lifecycle डोळ्यांनी वाचू शकता: तीन क्रियापदे, प्रत्येक request वर badge, प्रत्येक result वर resultType, आणि तुम्ही घडवू शकता व ज्यातून सावरू शकता असा version error.

⚠️ नेहमीच्या चुका

initialize शोधणे — 2026-07-28 पासून तो नाही; तुमच्या पहिल्या request ला -32022 ने उत्तर देणारा server तो कोणत्या आवृत्त्या बोलतो ते सांगत असतो
JSON-RPC id पुन्हा वापरणे — उत्तराची जोडणी id ने होते; retry ला नवा id मिळायलाच हवा
isError: true ला protocol अपयश मानणे — तो tool ची तक्रार घेऊन येणारा सामान्य result आहे, model साठी

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: version negotiation आता प्रत्येक request वर होते, त्यामुळेच load balancer मागील कोणताही server instance कोणत्याही request ला सामायिक session store शिवाय उत्तर देऊ शकतो. Server बाजूला badge (clientInfo, version) log करा — debugging साठी तो तुमचा सर्वोत्तम धागा आहे.

⏭️ पुढे

Messages कसे प्रवास करतात (stdio विरुद्ध Streamable HTTP) — आणि कधीच न टाळायचा security धडा: transports आणि विश्वास.

git checkout lesson-05-transports-security

🪪 Lesson 04 — The wire: badge, discovery, calls (protocol revision 2026-07-28)

📍 You are here: Lesson 04 of 8 · Previous: lesson-03-primitives · Next: lesson-05-transports-security

📦 What's in this branch

Lessons 01–03, plus the actual conversation, message by message — the sequence diagram that IS the protocol, as of revision 2026-07-28 (the current one; the box at the end of ❓ What says what changed and why).

🧒 Explain like I'm 5

Plugging an instrument into a room used to start with a little ritual ("hello, I speak socket-standard 2025"). Not any more. Now every message wears an ID badge 🪪, so no ritual is needed:

🪪 The badge. Every request carries _meta: which revision I speak (io.modelcontextprotocol/protocolVersion), who I am (…/clientInfo) and what I can do (…/clientCapabilities). The instrument checks the badge on every message and answers — or, if it doesn't speak that revision, says so (UnsupportedProtocolVersion, listing the revisions it does speak). Optional but polite: introductions (server/discover) — "who are you, what do you speak, which shelves do you stock?" Our client always asks; a client may skip it and just start talking.
📋 "What do you offer?" (tools/list) — the instrument reads out its shelf: names, descriptions, input forms.
🧰 "Do the thing." (tools/call with name + arguments) — the instrument does real work and hands back content for the desk.

That's… the whole language. Three verbs and a badge. Every message is JSON-RPC 2.0: requests carry an id (answers must quote it back — that's how the socket matches question to answer), notifications don't (fire-and-forget — our server ignores them), errors come as error with a code. Every result says resultType: "complete" and carries the server's own badge (_meta → serverInfo).

🗺️ Diagram — the sequence you'll see everywhere

sequenceDiagram
    participant H as 🔌 client (in the host)
    participant S as 🔬 server
    H->>S: 1 server/discover {_meta: protocolVersion, clientInfo, clientCapabilities} — optional
    S-->>H: 2 {resultType, supportedVersions: ["2026-07-28"], capabilities: {tools}, _meta: {serverInfo}}
    H->>S: 3 tools/list {_meta: …the same badge, every time}
    S-->>H: 4 {resultType, tools: [{name, description, inputSchema}, …], ttlMs}
    H->>S: 5 tools/call {name: "lookup_grade", arguments: {student: "katrina"}, _meta: …}
    S-->>H: 6 {resultType, content: [{type: "text", text: "Katrina (3A) has grade A+."}], isError: false}
    Note over H,S: three verbs and a badge — that's the protocol 🪪 (no handshake since 2026-07-28)

❓ What

JSON-RPC 2.0 shapes (all of them appear in our demo output):
- request: {"jsonrpc":"2.0","id":N,"method":"…","params":{…, "_meta":{…}}}
- response: {"jsonrpc":"2.0","id":N,"result":{"resultType":"complete", …}} (same id!)
- error: {"jsonrpc":"2.0","id":N,"error":{"code":…,"message":…,"data":…}}
- notification: no id → no response ever.
Version negotiation is per request: the badge names a revision (2026-07-28 here); a server that doesn't speak it answers -32022 Unsupported protocol version with data.supported: [...], and the client retries with one of those. No session, no memory of you between requests — which is exactly why any server instance behind a load balancer can answer any request.
Capabilities = the shelf list (L03), answered by server/discover: our server says {"tools": {}}. Clients declare theirs in the badge — it's mutual.
Results always carry resultType — "complete", or "input_required" when a server needs something from the host first (the multi-round-trip pattern that replaced server-initiated sampling/elicitation requests) — and usually _meta.serverInfo. List results add ttlMs/cacheScope so hosts may cache the shelf.
Tool results are content arrays ({"type":"text",…} — images and more exist) plus isError — tool failures are data for the model to react to, not protocol crashes. An unknown tool name IS a protocol error (-32602). Look at school_server.py's tools/call handler: both kinds are there.
More verbs exist for the other shelves (resources/list, prompts/get, …) and for change notifications (subscriptions/listen) — same grammar, learn on demand.

⏳ What changed, and why you'll still meet the old way. Until revision 2025-11-25 every session began with a handshake — initialize → notifications/initialized — and the server remembered you (a session; Mcp-Session-Id on HTTP). Revision 2026-07-28 retired that: requests are self-describing, sessions are gone, and server/discover is the optional way to ask up front. Older servers still expect the handshake; our client deliberately speaks only the modern revision, and our server answers a legacy initialize with -32022 plus the list of revisions it does speak — the spec's recommended way to be honest with an old client.

🤔 Why

Once you can READ the wire, MCP debugging becomes lesson-16-of-k8s style triage instead of vibes: -32022 on the first request? (version mismatch — the badge named a revision the server doesn't speak.) Tool never called? (bad description — the model can't see your shelf properly, L03.) Call hangs? (id mismatch or the server died — check stderr.) Ninety percent of "MCP doesn't work" is visible in six messages you now know by heart.

🧪 Try it — the diagram, live

python3 client/mini_client.py

Hold this lesson's sequence diagram next to the output: messages 1–6, in order, real. Then the pop quiz: which field is on EVERY → line? (The _meta badge.) Now break it on purpose — comment out the META + "protocolVersion" line of BADGE in mini_client.py, rerun, and read the server's refusal: -32022, with the revisions it does speak. Put it back, run with --drive, call lookup_grade {"student":"nobody"} — find the polite isError answer in the wire; then fly_to_moon {} for the other kind of error.

✅ Verify — what you should see

The scripted run shows six messages in this exact order: server/discover → its result (supportedVersions, capabilities, _meta.serverInfo); tools/list → {resultType, tools:[…]}; tools/call → {resultType, content:[…], isError:false}. Every → line carries the _meta badge with io.modelcontextprotocol/protocolVersion: "2026-07-28". Remove the protocolVersion line from BADGE and the first reply becomes error -32022 Unsupported protocol version listing supported: ["2026-07-28"].

🏁 What you just proved

You can read the current MCP lifecycle by eye: three verbs, a badge on every request, resultType on every result, and a version error you can trigger and recover from.

⚠️ Common mistakes

looking for initialize — there is none since 2026-07-28; a server that answers your first request with -32022 is telling you which revisions it speaks
reusing a JSON-RPC id — the answer is matched by id; a retry must get a new one
treating isError: true as a protocol failure — it is a normal result carrying a tool's complaint, meant for the model

🏭 Why this matters in production: version negotiation now happens on every request, which is what lets any server instance behind a load balancer answer any request with no shared session store. Log the badge (clientInfo, version) on the server side — it is your best debugging breadcrumb.

⏭️ Next

How the messages travel (stdio vs Streamable HTTP) — and the security lesson that must not be skipped: transports & trust.

git checkout lesson-05-transports-security

← Previousprimitives Next →transports security

This page is the lesson's README from the lesson-04-the-wire branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.