MCP servers and clients · Chapter 15 of 16

Capstone: Bazaar Bhai's server and assistant

By the end of this chapter you have built, end to end, what Rajat asked for in chapter 1: one MCP server for all of Bazaar Bhai's apps, with tools, resources and a prompt, served over stdio and HTTP, guarded by the policy and tested; and an assistant that answers through it with the lab model. Then you take a change request against the clock. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Clients and production
  • 5 tasks
  • Python
  • In the all labs plan

The first 2 chapters of MCP servers and clients are free. This one comes with the all labs plan.

Why you need this

Every piece exists somewhere in this lab: tools with schemas (chapter 5), resources (6), prompts (7), the host's loop (9), errors a model can act on (10), HTTP (12), a gate and an audit log (13), tests that catch bugs (14). A real server needs all of them together, in one file that other people can trust.

Rajat wants to stop commissioning integrations: "every new app talks to the one server, full stop." Gopal wants answers his store managers can rely on. Nisha has a checklist, and nothing ships until every box is ticked. Simran reviews the tests.

What you build: 5 tasks

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

  1. Task 1

    bazaar_server.py: the read-only tools

    In bazaar_server.py, an MCPServer named bazaar-bhai with instructions, which copies /workspace/data/bazaar.db to WORK, /tmp/bazaar-capstone.db, when it starts (keep the paths in module variables WORK and AUDIT). Four tools annotated read_only_hint=True, with descriptions, store ids checked by the pattern ^BB\d{2}$ and product ids by ^P\d{3}$ in the schema, and an unknown store or product a ToolError that names it:

    stock_level(store_id, product_id), returning store_id, product_id and units (0 when the store does not carry it); price_of(product_id), returning product_id, name, price and mrp; search_products(product_name), the sorted ids of the products whose name contains it, ignoring case; reorder_suggestion(store_id, product_id), returning store_id, product_id, units, reorder_level and cases by policy 5.3 (back to three times the reorder level, rounded up to whole cases of case_size; 0 when units is not below the level).

  2. Task 2

    bazaar_server.py: the gate, the data and the prompt

    Add draft_purchase_order(store_id, product_id, cases), chapter 13's gate on WORK: read_only_hint=False and a description that says it changes data; drafts only (quantity cases times case_size, unit_cost the price times 0.8 rounded to 2 decimals, total unit_cost times quantity rounded to 2 decimals, the next PO- id, ordered 2026-10-22); above ₹25,000 a ToolError naming Rajat and nothing saved; one JSON line per draft in AUDIT, /tmp/bazaar-capstone.log, with at, by (BAZAAR_USER, or unknown), tool, order_id and total; it returns order_id, status and total.

    Add the resources bazaar://policy (policy.md, text/markdown) and bazaar://stores (a JSON list of every store's id, area and manager, by id), and the prompt restock_plan(store_id), one message naming the store and its products below the reorder level. The file serves over stdio, or over streamable HTTP on 127.0.0.1, port 8002, when run with --http.

  3. Task 3

    assistant.py: the assistant

    In assistant.py, write async def ask(question, client, model="lab-chat", max_steps=5): chapter 9's loop offering only the server's read-only tools (and never running a tool it did not offer), with a system message that calls tool results untrusted. It returns the model's answer.

    When run, start bazaar_server.py over stdio and, for each of the five questions in the starter, in order, print > and the question, then the answer on the next line. No SQL in this file.

  4. Task 4

    test_bazaar.py: tests anyone's server must pass

    In test_bazaar.py, write pytest tests for bazaar_server.py in memory, each from a fresh copy of the database (a fixture copies it into tmp_path and points bazaar_server.WORK and bazaar_server.AUDIT there): the four read-only tools on inputs that can tell right from wrong, a draft saved and logged, an order above ₹25,000 refused with no log line, the resources and the prompt.

    The check runs them on your server and on its own correct one (both must pass), then on six copies of its own with one mistake each (each must make a test fail). Test only what tasks 1 and 2 promise.

  5. Task 5 · interview question

    Interview: a change request, supplier_of

    Time yourself: 20 minutes. Gopal needs to know who supplies a product. Add supplier_of(product_id) to bazaar_server.py: read-only, the product id checked by the schema, returning supplier_id, name, city and lead_days from the suppliers table, and a ToolError naming an unknown product.

    Add a test named test_supplier_of to test_bazaar.py that checks it against the database: it must pass on your server and fail on a copy whose supplier_of returns the wrong supplier.

What you will learn

  • bazaar_server.py: the read-only tools
  • bazaar_server.py: the gate, the data and the prompt
  • assistant.py: the assistant
  • test_bazaar.py: tests anyone's server must pass
  • Interview: a change request, supplier_of

More in Clients and production

Build "Capstone: Bazaar Bhai's server and assistant" yourself

Bazaar Bhai, a chain of 40 kirana stores in Jaipur, exposes its stock and orders once, to every AI tool. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of MCP servers and clients are free. This one comes with the all labs plan.