🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

🔌 धडा 07 — Client/host बांधा: सत्ता असलेली बाजू

📍 तुम्ही इथे आहात: 8 पैकी धडा 07 · मागे: lesson-06-build-a-server · पुढे: lesson-08-use-cases

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

धडे 01–06, आणि client/mini_client.py चे मार्गदर्शित वाचन — खोली, socket, आणि (--drive mode मध्ये) विद्यार्थिनी म्हणून तुम्ही.

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

Client बाजूची तीन कामे आहेत, आणि आपला ~105 ओळींचा host तिन्ही करतो:

सुरू करा आणि जोडा 🔌 — subprocess.Popen([...python, server]): stdio transport म्हणजे फक्त "child सुरू करा, त्याचे stdin/stdout धरून ठेवा" (L05, live). एक MiniHost = एक socket = एक server (L02).
Badge घाला 🪪 — send() JSON-RPC बनवतो: वाढत जाणारा id लावतो, प्रत्येक request ला _meta badge (आवृत्ती, clientInfo, clientCapabilities) जोडतो, एक ओळ लिहितो, एक ओळ वाचतो, उत्तराची id ने जोडणी करतो. मग main() L04 चा नेमका क्रम पार पाडतो: server/discover (ऐच्छिक) → tools/list → tools/call.
Model आणि जग यांच्यामध्ये बसा 🧠→🔌 — scripted mode मध्ये, तीन तयार calls "agent काय करेल" याचा अभिनय करतात. --drive mode मध्ये, calls तुम्ही टाइप करता — आणि या मजेत लपलेला धडा: model मजकुरात call सुचवतो; host मध्यस्थी करतो. चालवायचे की नाही ते host निवडतो — आणि server च्या स्वतःच्या प्रश्नांना उत्तर देणारी बाजूही तीच (input_required चिन्हांकित results, server ने सुरू केलेल्या sampling/elicitation requests ची आवृत्ती 2026-07-28 मधील जागा घेणारे). म्हणजे permission prompts, allow-lists, write-gates (L05 धोरण 3!) आणि logs host मध्येच असायला हवेत. सत्ता hosts कडे असते; ते रचनेनुसारच आहे.

खरा host नेमके तेच जोडतो जे तुम्ही अंदाज कराल: calls सुचवणारा खरा model (AI कोर्स L11 चा loop), model च्या context ला जोडलेले tool results (बाक, AI कोर्स L08), एकाच वेळी अनेक sockets, आणि संमतीचा UI. Plumbing च्या दृष्टीने? तुम्ही आता ते सगळे वाचले आहे.

🗺️ आकृती

sequenceDiagram
    participant U as 🧑 you (--drive: the model)
    participant H as 🏫 MiniHost (room + socket)
    participant S as 🔬 school_server (child process)
    U->>H: 1 "call lookup_grade {student: katrina}"
    Note over H: 2 the POWER moment: host decides<br/>(real hosts: permission check here 🚧)
    H->>S: 3 tools/call {name, arguments, id: 4}
    S-->>H: 4 {id: 4, content: [{text: "Katrina (3A) has grade A+."}]}
    H-->>U: 5 "📄 lands on the desk: …"
    Note over U,S: the model proposes · the host mediates · the server provides

📖 या ओळी वाचा (म्हणजे तुम्ही हरवणार नाही)

client/mini_client.py:

ओळी 19–23: प्रत्येक request घालतो तो badge (BADGE)
ओळी 25–34: child process सुरू करणे — stdio transport
ओळी 35–50: send() — एक request, एक reply, id ने जोडलेले
ओळी 52–60: show() — बाकावरचा result, किंवा समजावलेली error
ओळी 62–76: main() — ओळख, discovery
ओळी 77–शेवट: --drive — सत्तेचा क्षण; फाटक tools/call च्या अगदी आधी येते

❓ काय (चोरण्यासारखे तपशील)

id चा हिशेब हीच client ची संपूर्ण युक्ती: send वर self.next_id += 1, receive वर जोडणी. Async hosts pending-map ठेवतात; आपला synchronously वाचतो, म्हणून अगदी पुढची ओळ म्हणजेच उत्तर.
Errors विरुद्ध results: send() संपूर्ण response परत देतो. JSON-RPC error (अज्ञात tool -32602, चुकीची आवृत्ती -32022) ही host ने हाताळायची protocol समस्या आहे; result च्या आत isError: true म्हणजे tool बोलतो आहे — ती model ला दाखवा. show() दोन्ही करतो.
खरे hosts हेही करतात: isError results model ला दाखवून हाताळतात (retries!), मेलेले children पुन्हा जोडतात, आणि अनेक servers च्या tool lists model साठी एकाच कप्प्यात एकत्र करतात.
LLM API call कुठे आहे? मुद्दाम नाही — --drive मधील input() ऐवजी model call लावा आणि तुमच्याकडे खरा agent host तयार. (AI कोर्सच्या L11 lab मध्ये हे paste ने केले होते; इथे ते एक function आहे.)

🤔 का

"model फक्त… करू शकत नाही का?" अशा स्वरूपाच्या प्रत्येक MCP प्रश्नाचे उत्तर ही file देते: नाही — तो फक्त सुचवू शकतो; host मध्यस्थी करतो. Host चा हा अरुंद मार्ग समजला की safety कुठे राहते, server च्या संख्येपेक्षा host ची गुणवत्ता का जास्त महत्त्वाची, आणि एखाद्या app च्या MCP settings मध्ये "always allow" toggle करताना तुम्ही नक्की कशावर विश्वास ठेवता ते कळते (तुम्ही वरच्या sequence आकृतीची ओळ 2 हटवत असता 😄).

🧪 करून पाहा

python3 client/mini_client.py --drive
# model calls> get_student_count {"class_name":"3B"}
# model calls> add_homework {"title":"build my own host"}

मग L05 मधील एका ओळीची ताकदवाढ: --drive mode मध्ये tools/call च्या आधी write-gate जोडा (if name.startswith("add"): input("allow? ")). पुन्हा चालवा, फरक अनुभवा. --drive prompt चार क्रम सुचवतो (a–d): (a) दोन reads, (b) model प्रतिसाद देऊ शकेल अशी tool error, (c) गहाळ फाटक, (d) host टिकून राहतो अशी protocol error — सगळे चालवा. आता तुम्ही MCP च्या दोन्ही बाजू आणि त्याचे सर्वात महत्त्वाचे safety feature बांधले आहे. 🔌

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

--drive मध्ये tools/call च्या आधी सहा ओळींचे फाटक जोडल्यावर add_homework allow? साठी थांबतो आणि n दिल्यास बाकावर काहीच छापले जात नाही, तर lookup_grade न विचारता चालत राहतो. fly_to_moon {} ❌ server error -32602 छापतो आणि loop चालू राहतो — host protocol error मधून टिकला.

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

Host हीच सत्तेची सीमा आहे: model ची सूचना आणि wire यांच्यामध्ये तुम्ही माणसाचा निर्णय घातला, दोन्ही पाहू शकणाऱ्या एकमेव जागी.

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

notification पाठवल्यावर reply ची वाट पाहणे — id नसलेल्या messages साठी server ला काहीच देणे नसते (deadlock)
isError results model ला न दाखवता गिळून टाकणे — retries अपयश दिसण्यावरच अवलंबून असतात
JSON-RPC error ने host मारू देणे — error responses हाताळा, loop जिवंत ठेवा
खऱ्या host च्या settings मधील "always allow" sequence आकृतीची पायरी 2 हटवते — तुम्ही तेच toggle करत आहात हे जाणून घ्या

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: hosts अनेक servers च्या tool lists एका कप्प्यात एकत्र करतात, मेलेले child processes पुन्हा जोडतात, आणि प्रत्येक call भोवती संमतीचा UI, allow-lists आणि audit logs ठेवतात. Server च्या संख्येपेक्षा host ची गुणवत्ता जास्त महत्त्वाची.

⏭️ पुढे

शेवटचा टप्पा: पाच खऱ्या जगातील रचना — coding, support, data, बैठका, automation — प्रत्येकी क्रमांकित flow आणि sequence आकृतीसह.

git checkout lesson-08-use-cases

🔌 Lesson 07 — Build a client/host: the side with the power

📍 You are here: Lesson 07 of 8 · Previous: lesson-06-build-a-server · Next: lesson-08-use-cases

📦 What's in this branch

Lessons 01–06, plus the guided read of client/mini_client.py — the room, the socket, and (in --drive mode) you as the student.

🧒 Explain like I'm 5

The client side has three jobs, and our ~105-line host does all three:

Launch & plug in 🔌 — subprocess.Popen([...python, server]): the stdio transport IS just "start the child, hold its stdin/ stdout" (L05, live). One MiniHost = one socket = one server (L02).
Wear the badge 🪪 — send() builds JSON-RPC: stamps an incrementing id, adds the _meta badge (revision, clientInfo, clientCapabilities) to every request, writes a line, reads a line, matches the answer by id. Then main() performs L04's exact sequence: server/discover (optional) → tools/list → tools/call.
Sit between model and world 🧠→🔌 — in scripted mode, three canned calls play "what an agent would do". In --drive mode, YOU type the calls — and here's the lesson hiding in the fun: the model proposes a call, in text; the host mediates. The host chooses whether to execute — and it is also the side that answers a server's own questions (results marked input_required, revision 2026-07-28's replacement for server-initiated sampling/elicitation requests). Which means the host is where permission prompts, allow-lists, write-gates (L05 policy 3!) and logs belong. Hosts hold the power; that's by design.

A real host adds exactly what you'd guess: a real model proposing the calls (AI course L11's loop), tool results appended to the model's context (the desk, AI course L08), multiple sockets at once, and the consent UI. Plumbing-wise? You've now read all of it.

🗺️ Diagram

sequenceDiagram
    participant U as 🧑 you (--drive: the model)
    participant H as 🏫 MiniHost (room + socket)
    participant S as 🔬 school_server (child process)
    U->>H: 1 "call lookup_grade {student: katrina}"
    Note over H: 2 the POWER moment: host decides<br/>(real hosts: permission check here 🚧)
    H->>S: 3 tools/call {name, arguments, id: 4}
    S-->>H: 4 {id: 4, content: [{text: "Katrina (3A) has grade A+."}]}
    H-->>U: 5 "📄 lands on the desk: …"
    Note over U,S: the model proposes · the host mediates · the server provides

📖 Read these lines (so you don't get lost)

client/mini_client.py:

lines 19–23: the badge every request wears (BADGE)
lines 25–34: launching the child process — the stdio transport
lines 35–50: send() — one request, one reply, matched by id
lines 52–60: show() — result on the desk, or the error explained
lines 62–76: main() — introductions, discovery
lines 77–end: --drive — the power moment; the gate goes right before tools/call

❓ What (details worth stealing)

id bookkeeping is the whole client trick: self.next_id += 1 on send, match on receive. Async hosts keep a pending-map; ours reads synchronously so the very next line IS the answer.
Errors vs results: send() hands back the whole response. A JSON-RPC error (unknown tool -32602, wrong revision -32022) is a protocol problem the host handles; isError: true inside a result is the tool talking — show that one to the model. show() does both.
Real hosts also: handle isError results by SHOWING them to the model (retries!), reconnect dead children, and merge tool lists from many servers into one shelf for the model.
Where's the LLM API call? Deliberately absent — swap the input() in --drive for a model call and you have a real agent host. (The AI course's L11 lab did this with paste; here it's one function.)

🤔 Why

Every MCP question of the form "can the model just…?" is answered by this file: no — it can only propose; the host mediates. Understanding the host's chokepoint tells you where safety lives, why host quality matters more than server count, and exactly what you're trusting when you toggle "always allow" in some app's MCP settings (you're deleting line 2 of the sequence diagram above 😄).

🧪 Try it

python3 client/mini_client.py --drive
# model calls> get_student_count {"class_name":"3B"}
# model calls> add_homework {"title":"build my own host"}

Then the one-line power-up from L05: add a write-gate before the tools/call in --drive mode (if name.startswith("add"): input("allow? ")). Run again, feel the difference. The --drive prompt suggests four sequences (a–d): (a) two reads, (b) a tool error the model can act on, (c) the missing gate, (d) a protocol error the host survives — run them all. You've now built both sides of MCP and its most important safety feature. 🔌

✅ Verify — what you should see

With the six-line gate added before tools/call in --drive, add_homework waits for allow? and n prints nothing on the desk, while lookup_grade still runs without asking. fly_to_moon {} prints ❌ server error -32602 and the loop continues — the host survived a protocol error.

🏁 What you just proved

The host is the power boundary: you inserted a human decision between the model's proposal and the wire, in the only place that can see both.

⚠️ Common mistakes

waiting for a reply after sending a notification — the server owes nothing for messages without an id (deadlock)
swallowing isError results instead of showing them to the model — retries depend on seeing the failure
letting a JSON-RPC error kill the host — handle error responses, keep the loop alive
"always allow" in a real host's settings deletes step 2 of the sequence diagram — know that is what you are toggling

🏭 Why this matters in production: hosts merge tool lists from many servers into one shelf, reconnect dead child processes, and put consent UI, allow-lists and audit logs around every call. Host quality matters more than server count.

⏭️ Next

The finale: five real-world setups — coding, support, data, meetings, automation — each with a numbered flow AND a sequence diagram.

git checkout lesson-08-use-cases

← Previousbuild a server Next →use cases

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