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

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

🏫 धडा 02 — Architecture: hosts, clients, servers

📍 तुम्ही इथे आहात: 8 पैकी धडा 02 · मागे: lesson-01-why-mcp · पुढे: lesson-03-primitives

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

धडा 01, आणि तीन भूमिका व नक्की कोण कोणाशी बोलतो — कोणतीही wire traffic वाचण्यापूर्वी लागणारा नकाशा.

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

Socket व्यवस्थेतील तीन भूमिका:

खोली 🏫 (host) — माणूस प्रत्यक्ष वापरतो ते AI application: Claude Desktop, एखादा IDE, तुमचे custom agent app. कोणती उपकरणे जोडायची ते खोली ठरवते, आणि model (विद्यार्थिनी 🧠) तिच्या बाकावर इथेच बसते.
भिंतीवरचे socket 🔌 (client) — खोलीच्या आत, जोडलेल्या प्रत्येक उपकरणासाठी एक socket. Socket विजेचे तपशील सांभाळते: handshake, message ची चौकट, उत्तरांची प्रश्नांशी जोडणी. एका खोलीत अनेक sockets असू शकतात (files + GitHub + database, सगळे एकाच वेळी).
उपकरण 🔬 (server) — एकच क्षमता गुंडाळणारा छोटा program. आपण कोणत्या खोलीत आहोत हे त्याला माहीत नसते आणि त्याची पर्वाही नसते — तो फक्त मानक प्रश्नांची उत्तरे देतो. आपला school_server.py म्हणजे नेमक्या याच्या ~125 ओळी.

सूक्ष्म पण महत्त्वाचा भाग: model कधीच socket ला हात लावत नाही. विद्यार्थिनी शब्दांत म्हणते "मला lookup_grade call करायचा आहे" (एक structured tool call — AI कोर्स L11); ते खरोखर करायचे की नाही ते खोली ठरवते, socket message वाहून नेते, उपकरण उत्तर देते, आणि result विद्यार्थिनीच्या बाकावर ठेवला जातो. Model सुचवतो; host ठरवतो. धडा 05 मधील सगळी सुरक्षा त्याच फटीत राहते.

कोण काय ठरवते — लक्षात ठेवण्याचा तक्ता:

निर्णय	कोण ठरवते	ते कुठे असते
कोणती उपकरणे जोडली आहेत	user (host च्या settings मधून)	host config / allow-list
बाकावर काय जाते (resources, history)	host / app	host
कोणता tool, कोणत्या arguments सह call करायचा	model — सूचना म्हणून	model output
तो call खरोखर चालतो की नाही	host (policy, permission prompt)	host — सत्तेचा क्षण (L07)
एखादे write होते की नाही	माणसाचा click (धोरण 3, L05)	host UI
tool काय करतो आणि काय परत देतो	server	server code

🗺️ आकृती

flowchart LR
    subgraph host["🏫 HOST - e.g. your IDE"]
        model["🧠 the model<br/>proposes tool calls in words"]
        c1["🔌 client #1"]
        c2["🔌 client #2"]
    end
    s1["🔬 server: filesystem<br/>(local child process)"]
    s2["🔬 server: GitHub<br/>(remote, Streamable HTTP)"]
    model -->|"1 'I want lookup_grade(…)'"| c1
    c1 <-->|"2 JSON-RPC"| s1
    c2 <-->|"2 JSON-RPC"| s2
    s1 -->|"3 result → the desk"| model

❓ काय

Host = application; user शी नाते, model शी संवाद आणि परवानगीचे सगळे निर्णय त्याच्याकडे. एक host, अनेक clients.
Client = एका server शी एक connection; protocol बोलतो, discovery आणि calls पुढे पोहोचवतो. मुद्दाम कंटाळवाणा — plumbing तसेच असावे.
Server = क्षमतेभोवतीचे आवरण. Local (host त्याला child process म्हणून सुरू करतो — stdio) किंवा remote (Streamable HTTP, स्वतःच्या ओळखीसह). तो काय देतो ते जाहीर करतो (धडा 03) आणि calls ना उत्तर देतो. तो तुमचे इतर servers, तुमची prompt history किंवा model स्वतः कधीच पाहत नाही — फक्त स्वतःचा संवाद.
वेगळेपण हे वैशिष्ट्य आहे: filesystem server ने काय सांगितले ते GitHub server वाचू शकत नाही; प्रत्येक socket चे स्वतःचे वेगळे circuit असते.

🤔 का

प्रत्येक debugging session आणि प्रत्येक security प्रश्न या नकाशातूनच जातो: "model ने X केले" म्हणजे जवळजवळ नेहमी "HOST ने X करू दिले". आणि एखाद्या अनोळखी व्यक्तीने लिहिलेला server तुमच्या खोलीत — त्याच्याबद्दल काहीही माहीत नसताना — चालतो, याचे कारण भूमिका फक्त मानक socket वरच भेटतात. अरुंद interfaces, बदलता येणारे भाग: हीच संपूर्ण युक्ती.

🧪 करून पाहा

python3 client/mini_client.py

आता जे दिसते त्यातील भूमिका ओळखा: mini_client.py host आणि client दोन्ही बनला आहे (तो child सुरू करतो आणि socket त्याच्याकडे आहे); school_server.py हे उपकरण आहे; आणि भाग 3 मधील scripted calls model च्या सूचनेची जागा घेतात. मग --drive सह चालवा — आता model तुम्ही आहात, आणि लक्षात घ्या: तुम्ही फक्त सुचवू शकता; host मध्यस्थी करतो आणि प्रत्यक्ष स्पर्श client करतो.

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

Scripted run मध्ये → ओळी म्हणजे client (socket) बोलतो आणि ← ओळी म्हणजे server; model जे बोलेल ते wire वर कधीच दिसत नाही. --drive मध्ये तुम्ही call साठी विनंती टाइप करता आणि host तिचे tools/call मध्ये रूपांतर करतो.

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

तीन भूमिका code मध्ये वेगळ्या करता येतात: MiniHost (खोली + socket) आणि school_server.py (उपकरण) फक्त wire वर भेटतात; model कधीच socket ला हात लावत नाही.

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

संपूर्ण app ला 'client' म्हणणे — client म्हणजे एका server शी एक connection; user, model आणि परवानगीचे निर्णय host कडे असतात
server ला तुमच्या इतर servers किंवा संवादाबद्दल माहीत असेल असे अपेक्षित धरणे — तो फक्त स्वतःची wire पाहतो
model थेट tools call करू शकतो असे गृहीत धरणे — तो फक्त सुचवू शकतो; host मध्यस्थी करतो (धडा 07)

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: "कोण काय ठरवते" हीच तुमची security architecture आहे. Permission prompts, allow-lists आणि logs host मध्ये ठेवा, कारण model ची सूचना आणि user दोन्ही पाहणारी ती एकमेव जागा आहे.

⏭️ पुढे

उपकरण नक्की काय देऊ शकते? तीन कप्पे: tools, resources, prompts.

git checkout lesson-03-primitives

🏫 Lesson 02 — The architecture: hosts, clients, servers

📍 You are here: Lesson 02 of 8 · Previous: lesson-01-why-mcp · Next: lesson-03-primitives

📦 What's in this branch

Lesson 01, plus the three roles and exactly who talks to whom — the map you need before reading any wire traffic.

🧒 Explain like I'm 5

Three roles in the socket system:

The room 🏫 (host) — the AI application the human actually uses: Claude Desktop, an IDE, your custom agent app. The room decides which instruments get plugged in, and it's where the model (the student 🧠) sits at its desk.
The wall socket 🔌 (client) — INSIDE the room, one socket per plugged-in instrument. The socket handles the electrical details: the handshake, message framing, matching answers to questions. One room can have many sockets (files + GitHub + database, all at once).
The instrument 🔬 (server) — a small program wrapping ONE capability. It doesn't know or care which room it's in — it just answers the standard questions. Our school_server.py is ~125 lines of exactly this.

The subtle, important bit: the model never touches the socket. The student says "I want to call lookup_grade" in words (a structured tool call — AI course L11); the ROOM decides whether to actually do it, the socket carries the message, the instrument answers, and the result is placed on the student's desk. Model proposes; host disposes. That gap is where all of lesson 05's safety lives.

Who decides what — the table to keep:

Decision	Who decides	Where it lives
which instruments are plugged in	the user (via the host's settings)	host config / allow-list
what goes on the desk (resources, history)	the host / app	host
which tool to call, with which arguments	the model — as a proposal	model output
whether that call actually runs	the host (policy, permission prompt)	host — the power moment (L07)
whether a write happens	a human click (policy 3, L05)	host UI
what the tool does and returns	the server	server code

🗺️ Diagram

flowchart LR
    subgraph host["🏫 HOST - e.g. your IDE"]
        model["🧠 the model<br/>proposes tool calls in words"]
        c1["🔌 client #1"]
        c2["🔌 client #2"]
    end
    s1["🔬 server: filesystem<br/>(local child process)"]
    s2["🔬 server: GitHub<br/>(remote, Streamable HTTP)"]
    model -->|"1 'I want lookup_grade(…)'"| c1
    c1 <-->|"2 JSON-RPC"| s1
    c2 <-->|"2 JSON-RPC"| s2
    s1 -->|"3 result → the desk"| model

❓ What

Host = the application; owns the user relationship, the model conversation, and ALL permission decisions. One host, many clients.
Client = one connection to one server; speaks the protocol, relays discovery and calls. Boring on purpose — plumbing should be.
Server = the capability wrapper. Local (host launches it as a child process — stdio) or remote (Streamable HTTP, with its own identity). It publishes what it offers (lesson 03) and answers calls. It never sees your other servers, your prompt history, or the model itself — only its own conversation.
Isolation is a feature: the GitHub server can't read what the filesystem server said; each socket is its own circuit.

🤔 Why

Every debugging session and every security question routes through this map: "the model did X" is almost always "the HOST allowed X". And the reason a server written by a stranger works in your room — without knowing anything about it — is that the roles only meet at the standard socket. Narrow interfaces, swappable parts: the whole trick.

🧪 Try it

python3 client/mini_client.py

Now name the roles in what you see: mini_client.py is playing host AND client (it launches the child and owns the socket); school_server.py is the instrument; and in part 3, the scripted calls stand in for the model proposing. Then run with --drive — now YOU are the model, and notice: you can only propose; the host mediates and the client does the touching.

✅ Verify — what you should see

In the scripted run, → lines are the client (socket) speaking and ← lines the server; nothing the model would say ever appears on the wire. In --drive you type a request for a call and the host turns it into tools/call.

🏁 What you just proved

The three roles are separable in code: MiniHost (room + socket) and school_server.py (instrument) meet only at the wire; the model never touches the socket.

⚠️ Common mistakes

calling the whole app 'the client' — the client is one connection to one server; the host owns the user, the model and the permission decisions
expecting the server to know about your other servers or the conversation — it sees only its own wire
assuming the model can call tools directly — it can only propose; the host mediates (lesson 07)

🏭 Why this matters in production: "who decides what" is your security architecture. Put permission prompts, allow-lists and logs in the host, because that is the only place that sees both the model's proposal and the user.

⏭️ Next

What exactly can an instrument offer? The three shelves: tools, resources, prompts.

git checkout lesson-03-primitives

← Previouswhy mcp Next →primitives

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