MCP server project · Chapter 1 of 12

What MCP is

By the end of this chapter you can say what MCP is and why DabbaDrop wants it, name the parts of an AI assistant (the host, the model, the clients, the servers), read the JSON-RPC messages a client and a server send each other, and run DabbaDrop's first MCP server with one tool, find_slots, that any assistant can discover and call. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: The protocol
  • 3 tasks
  • Python
  • Free chapter

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.

Why you need this

Members have started asking their own AI assistants to order lunch. In October DabbaDrop's team kept 4 integrations going: a custom GPT action for one member, a Python script for an office manager who uses Claude Desktop, a plugin for the support team's IDE, and the ordering agent with tools of its own. All four did the same five things (find a dish, find a slot, order, list orders, pay), four different ways. Each one needed Tara's password or an admin's cookie to work. The office script ran with Bhavna's admin session, so it could see every member's orders, not only the office manager's.

Farah, the founder, wants one way in for every assistant from launch week (Monday 2 November 2026). Each assistant should connect the same way, find the same tools, and act for one member only. Kunal, DabbaDrop's senior developer, builds it with you over 12 chapters.

The ordering API cannot do this on its own: it is built for DabbaDrop's app, and every new assistant means one more integration. DabbaDrop needs one standard that every assistant already speaks. That standard is MCP.

The lesson

What MCP is

MCP, the Model Context Protocol, is an open standard for how an AI assistant talks to a service. Without it, every assistant needs its own code for every service: 4 assistants and 1 DabbaDrop meant 4 integrations, and 4 assistants and 10 services would mean 40. With MCP, each service writes one server, each assistant writes one client, and any client can talk to any server. That is N plus M, not N times M.

An AI assistant is made of a few parts. Learn their names now; every chapter uses them.

  • The host is the app the person uses: Claude Desktop, VS Code, DabbaDrop's own chat. It runs the conversation and shows the screens.
  • The model is the language model inside the host. It reads the conversation and writes text, or asks for a tool to be called.
  • A client lives inside the host. It keeps one connection to one server. A host with three servers has three clients.
  • A server is a program that offers things to clients. DabbaDrop's server is the one you build.

The model never talks to your server: it asks the host, the host's client sends a message to the server, and the answer comes back the same way.

Tools, resources and prompts

A server can offer three kinds of thing. The difference is who decides when each is used.

  • Tools are actions or lookups: find_slots, later place_order. The model decides when to call one, from its name, its description and its arguments.
  • Resources are things to read, each with a URI, like a menu page. The app (the host) decides which to read and give to the model. Chapter 4 builds them.
  • Prompts are ready-made messages, like "plan my week". The member picks one, the way you pick a menu item. Chapter 5 builds them.

This chapter has one tool.

Tour of the codebase

The ordering backend is the take-home of Project: DabbaDrop's ordering backend, given whole and unchanged. The MCP server lives beside it in mcp_server/:

app/ alembic/ scripts/ tests/   the ordering API (the backend project's take-home)
mcp_server/__main__.py          python -m mcp_server: migrations, the seed, the server
mcp_server/main.py              create_app(): the ordering API with /mcp added
mcp_server/config.py            INSTRUCTIONS and mcp_settings (name, version, ...)
mcp_server/transport.py         POST /mcp: the SDK's HTTP endpoint, mounted in the API
mcp_server/dabba_api.py         DabbaApi, ApiError: the ordering API, called as a member
mcp_server/member.py            who a call acts for (Tara, user 2, until chapter 7)
mcp_server/descriptions.py      what each tool says about itself
mcp_server/tools/catalog.py     zone_named, find_slots: the first tool
mcp_server/peek.py              python -m mcp_server.peek: JSON-RPC by hand
mcp_server/server.py            yours: build_server (Task 1)
mcp_server/rpc.py               yours: message, reply_of, result_of (Task 2), kind (Task 3)

One process, one port: main.py takes the API's own create_app() and adds /mcp. But the tools never touch the ordering tables. find_slots calls the API with HTTP requests, as the member, the way the app on Tara's phone does (dabba_api.py). So the API's rules hold for every assistant, and the server log shows every call a tool made.

With the starter, the app does not start: main.py calls your build_server() when it loads.

$ python -m mcp_server
...
  File "/tmp/w/01-what-mcp-is-starter/mcp_server/server.py", line 32, in build_server
    raise NotImplementedError("Task 1: build_server is not written yet")
NotImplementedError: Task 1: build_server is not written yet

Once Task 1 is done:

$ python -m mcp_server
...
Migrations: up to date
INFO:     Will watch for changes in these directories: ['/tmp/w/01-what-mcp-is-solution/app', '/tmp/w/01-what-mcp-is-solution/mcp_server']
INFO:     Uvicorn running on http://127.0.0.1:8101 (Press CTRL+C to quit)
...
INFO:     Application startup complete.

(These runs were on port 8101; yours is on 8000.)

A server in a few lines

The official MCP Python SDK (mcp, version 2.3.0 here) does the protocol for you. Its server class is MCPServer. Version 1 of the SDK called the same class FastMCP (from mcp.server.fastmcp import FastMCP), so older code you read online uses that name.

Here is a server that is not DabbaDrop's, a made-up chutney shop, with one tool:

from mcp.server.mcpserver import MCPServer

server = MCPServer("chutney-shop", title="Chutney Shop", version="0.1.0", log_level="WARNING")


@server.tool(name="find_chutneys", description="The chutneys a zone's kitchen makes today.")
async def find_chutneys(zone: str, spicy: bool = False) -> list[str]:
    return ["Green chutney", "Imli chutney"]
  • The constructor holds what the server says about itself when a client connects: its name, a title for people, its version, and instructions, text that hosts often put in the model's prompt. log_level="WARNING" keeps the SDK's own log to warnings and errors.
  • server.tool(...) takes the tool's name and description and returns a decorator. Put it on a function, and the function is a tool. A decorator is only a function that takes a function, so you can also call it with one that lives in another module.
  • The parameters become the tool's input schema. The SDK reads the type hints: zone: str is a required string, spicy: bool = False an optional boolean.

Connected with the SDK's own client, in memory:

chutney-shop 0.1.0
find_chutneys {'type': 'object', 'properties': {'zone': {'title': 'Zone', 'type': 'string'}, 'spicy': {'default': False, 'title': 'Spicy', 'type': 'boolean'}}, 'required': ['zone'], 'title': 'find_chutneysArguments'}
False {'result': ['Green chutney', 'Imli chutney']}

The common mistake is @server.tool with no brackets. The server does not even load:

TypeError: The @tool decorator was used incorrectly. Did you forget to call it? Use @tool() instead of @tool

DabbaDrop's settings and instructions are already written in config.py, and find_slots is in tools/catalog.py. build_server puts them together, and makes a new server each time it is called: the HTTP endpoint makes one, and every check and test makes its own.

JSON-RPC 2.0: the messages

Every MCP message is a JSON-RPC 2.0 message. JSON-RPC is a small, old standard for "call a method on another program": plain JSON objects, each with "jsonrpc": "2.0". There are three kinds.

  • A request asks for something and wants an answer. It has an id (any number the sender picks), a method (what to do) and usually params (the arguments).
  • A reply answers one request. It carries the same id, and either a result (it worked) or an error with a code, a message and sometimes data (the request itself failed).
  • A notification has a method and no id. Nobody replies to it.

The id lets a client match replies to requests. The error codes are JSON-RPC's own: -32601 "Method not found", -32602 "Invalid params", -32600 "Invalid request", -32603 "Internal error".

The handshake, on the wire

Start the server and run python -m mcp_server.peek tools/list. Peek is a small client that uses your rpc.py, and it prints every message: -> what it sent, <- the HTTP status and what came back.

$ python -m mcp_server.peek tools/list
-> {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": {"name": "peek", "version": "1.0"}}}
<- 200 {"jsonrpc": "2.0", "id": 1, "result": {"capabilities": {"prompts": {"listChanged": false}, "resources": {"listChanged": false, "subscribe": false}, "tools": {"listChanged": false}}, "instructions": "DabbaDrop delivers home-style lunch dabbas in Mumbai: three kitchens, six zones (Andheri West, Goregaon, Malad, Dadar, Bandra, Thane) and half-hour lunch slots at 12:00, 12:30 and 13:00. Use these tools to find dishes and free slots, place orders and list the member's orders. Every call acts for one signed-in member. Prices are whole rupees; dates are Mumbai's (YYYY-MM-DD).", "protocolVersion": "2025-11-25", "serverInfo": {"name": "dabbadrop", "title": "DabbaDrop", "version": "1.0.0"}}}
-> {"jsonrpc": "2.0", "method": "notifications/initialized"}
<- 202 (no body)
-> {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}
<- 200 {"jsonrpc": "2.0", "id": 2, "result": {"tools": [{"description": "Wraps GET /zones/{zone_id}/slots for a day.", "inputSchema": {"properties": {"zone": {"title": "Zone", "type": "string"}, "date": {"title": "Date", "type": "string"}, "time": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "title": "Time"}}, "required": ["zone", "date"], "type": "object", "title": "find_slotsArguments"}, "name": "find_slots", "outputSchema": {"properties": {"result": {"items": {"additionalProperties": true, "type": "object"}, "title": "Result", "type": "array"}}, "required": ["result"], "type": "object", "title": "find_slotsOutput"}}]}}
...

Three messages, in this order, start every MCP conversation:

  1. initialize, a request. The client says which protocol version it speaks (a date: 2025-11-25), what it can do (capabilities) and who it is (clientInfo).
  2. Its result: the version the server agrees to, what the server offers (tools, resources, prompts), its serverInfo (your name, title and version) and its instructions.
  3. notifications/initialized, a notification: "I am ready". It has no id, so there is no reply, only HTTP 202 and an empty body.

Then the real work: tools/list gives every tool with its name, its description and its inputSchema, a JSON schema of its arguments (it came from the type hints). Chapter 3 makes those schemas much richer.

How the reply comes over HTTP

The server is at POST /mcp. Each message is one POST, and the reply is in the answer. With the SDK's defaults (chapter 6 changes them), two things are worth knowing now.

Replies come as server-sent events, a simple text format for streaming: blocks of lines, an empty line after each block. The JSON is on the lines that start with data:. This is the raw answer to initialize, with curl:

HTTP/1.1 200 OK
content-type: text/event-stream
mcp-session-id: 4f791201dec049738df44d6a276166a7
...

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"capabilities":{"prompts":{"listChanged":false}, ...

A body may hold more than one event (a progress notification, then the reply), and one event's JSON may be split over several data: lines. The reply is the event that carries an id. Your reply_of reads it. So the client must say it accepts both formats; with only accept: application/json, the server answers 406:

{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Not Acceptable: Client must accept both application/json and text/event-stream"}}

initialize starts a session. The mcp-session-id header names it, and every later request sends it back. Without it the server answers 400 Bad Request: Missing session ID; with one it does not know (after a restart, say) 404 Session not found. The request pane keeps the session id for you; after python -m mcp_server reloads, send "Start a session" again.

A tool call, and a tool that fails

The saved request "Call find_slots: Thane, Tuesday" sends tools/call with the tool's name and its arguments. Peek shows the same call:

-> {"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "find_slots", "arguments": {"zone": "Thane", "date": "2026-11-03", "time": "12:30"}}}
<- 200 {"jsonrpc": "2.0", "id": 2, "result": {"content": [{"text": "{\n  \"slot_id\": 80,\n  \"starts_at\": \"2026-11-03T12:30:00+05:30\",\n  \"ends_at\": \"2026-11-03T13:00:00+05:30\",\n  \"places_left\": 30\n}", "type": "text"}], "isError": false, "structuredContent": {"result": [{"slot_id": 80, "starts_at": "2026-11-03T12:30:00+05:30", "ends_at": "2026-11-03T13:00:00+05:30", "places_left": 30}]}}}

A tool's result has two copies of the answer: content, a list of parts for the model to read (here one text part per slot), and structuredContent, the data itself for code (a list is wrapped in {"result": [...]}). And isError.

The server log shows the call from the inside. The POST to /mcp, then the two API requests find_slots made, each on its own line:

{"id": "c1cbd6fc45db4dd9afa81c877ce2979f", "method": "POST", "path": "/mcp", "status": 200, "ms": 3.8, "user_id": null}
INFO:     127.0.0.1:53152 - "POST /mcp HTTP/1.1" 200 OK
{"id": "9a0b364bd1d845e5b3f1e9b1717acaa4", "method": "GET", "path": "/zones", "status": 200, "ms": 7.1, "user_id": null}
{"id": "336dddd57fea4f61a84310c2e1566d00", "method": "GET", "path": "/zones/6/slots", "status": 200, "ms": 7.9, "user_id": null}

Now two failures that look alike. find_slots for Powai, where DabbaDrop does not deliver:

<- 200 {"jsonrpc": "2.0", "id": 2, "result": {"content": [{"text": "Error executing tool find_slots: DabbaDrop does not deliver to Powai. It delivers to Andheri West, Goregaon, Malad, Dadar, Bandra, Thane.", "type": "text"}], "isError": true}}

And a method that does not exist, tools/lst:

<- 200 {"jsonrpc": "2.0", "id": 2, "error": {"code": -32601, "message": "Method not found", "data": "tools/lst"}}

Error -32601: Method not found

Look at where the failure sits. The first is a result; the second is an error. That difference is Task 3's question.

Your turn

  • Task 1, server.py, build_server: a new MCPServer named from the settings, titled DabbaDrop, with the version, the instructions and log level WARNING, and find_slots as its one tool with its description. The trap: returning the same server every time.
  • Task 2, rpc.py, message, reply_of, result_of: write a request or a notification as a dict, read the reply out of an HTTP answer (JSON, server-sent events, or an empty 202), and give back the result or raise RpcError. The trap: taking the first data: line, which may be a notification, or half of a reply.
  • Task 3, rpc.py, kind: request, notification, result, error or invalid. Kunal will ask: find_slots for Powai answered with "isError": true inside a "result". Was that a JSON-RPC error? Who reads that message?

Run python -m mcp_server, then send the saved requests in order: "Is the app up?", "Start a session (initialize)", "What tools are there?", the two find_slots calls and "A method that does not exist". Try python -m mcp_server.peek tools/list (it needs your Task 2). Then press Check. A kind that calls a tool's failure an error gets:

kind(find_slots' reply for Powai) returned "error"; the task wants "result"

What you build: 3 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    server.py: a server with one tool

    Write build_server() in mcp_server/server.py. It returns a new MCPServer named mcp_settings.name (dabbadrop), with the title DabbaDrop, the version mcp_settings.version, the instructions INSTRUCTIONS and log_level WARNING, and with one tool: find_slots from mcp_server/tools/catalog.py, named find_slots, described by DESCRIPTIONS["find_slots"].

    The Check connects an MCP client to your server in memory and reads what it says about itself: its name, title, version and instructions, and its tools (only find_slots, with that description and the parameters zone, date and time). Then it calls find_slots for Thane on 2026-11-03 (slots 79, 80 and 81) and at 12:30 (slot 80), and sends initialize to POST /mcp of the whole app.

  2. Task 2

    rpc.py: JSON-RPC messages by hand

    Write message, reply_of and result_of in mcp_server/rpc.py. message(id, method, params=None) returns {"jsonrpc": "2.0", "id", "method", "params"}, with no id key when id is None (a notification) and no params key when params is None. reply_of(content_type, body) returns the JSON-RPC reply in an HTTP answer: None for an empty body; the parsed JSON when the content type is not text/event-stream; for server-sent events, the JSON of the first event's data lines that has an id. result_of(reply) returns the reply's result, or raises RpcError(code, message, data) when it has an error.

    The Check builds requests and notifications with your message, sends them to POST /mcp of the whole app, and reads the server's real answers (server-sent events, and an empty 202) with your reply_of and result_of: tools/list gives find_slots, and a method that does not exist raises RpcError -32601.

  3. Task 3 · interview question

    Interview: rpc.py, what kind of message?

    Write kind(msg) in mcp_server/rpc.py. It returns "request" for a message with a method and an id, "notification" for a method and no id, "error" for an id and an error, "result" for an id and a result, and "invalid" for anything else: a value that is not a dict, or a dict whose jsonrpc is not "2.0".

    The Check sorts real messages from the server (an initialize request and its result, the initialized notification, the error for a method that does not exist, find_slots' answer for Powai) and a few broken ones.

    Kunal will ask: find_slots for Powai answered with "isError": true inside a "result". Was that a JSON-RPC error? Who reads that message?

What you will learn

  • What MCP is: one protocol between AI assistants and the services they use, so N assistants and M services need N plus M pieces of code, not N times M.
  • Hosts, clients and servers: who runs the model, who holds the connection, who offers the tools.
  • Tools, resources and prompts: the three things a server offers, and who decides when each is used.
  • JSON-RPC 2.0: requests, replies with a result or an error, and notifications, exactly as they go over the wire.
  • The initialize handshake: what a client and a server agree on before any tool is called.
  • The SDK's MCPServer: a server in a few lines, and a tool from a plain Python function.

More in The protocol

Build "What MCP is" yourself

DabbaDrop wants AI assistants like Claude Desktop to order for its members, safely. You build the MCP server that lets them, and only as the member who allowed it. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.