The Project: Nare's Notes Assistant

Every lesson in this course is set in one small lab, on one project. The lab is made up. All people, notes, bookings, tokens, secrets, dates and events in the project are fictional and simulated. The real cases that open each lesson are separate, cited, and clearly marked as real.

The lab

Nare runs a small sleep and memory research lab with two colleagues, Priya and Tomas. The lab is planning a nap study: a group of participants learn word pairs, some nap in the sleep lab while wearing EEG caps, and the lab measures what they recall afterwards. Nare keeps her research notes as Markdown files in one folder: meeting notes, a reading list, half-formed ideas about naps and recall.

Money in this course is in US dollars, the currency the model providers price in. The project spends almost none: the only costs are model fees, which course-guide/02 prices.

The problem

Nare uses four AI applications in a normal week: a desktop chat assistant, an AI code editor for her analysis scripts, a command-line coding agent, and a small assistant the lab is building for itself. She wants every one of them to answer "what did we decide about the nap study?" from her notes. Then Tomas wants the same assistants to see the lab's equipment calendar, and Priya wants her reference manager. Without a shared protocol, every pairing of application and tool system is another piece of custom glue: 4 applications times 6 tool systems is 24 integrations to write and keep working.

Nare wants a notes assistant that:

1. Answers questions from her notes, in any AI application that speaks MCP, and cites the note it used.
2. Says plainly when the notes do not answer the question, instead of guessing.
3. Saves a new note when asked, only after she approves it, and never overwrites an existing note.
4. Works alongside the lab calendar and the reference manager, without mixing up their tools.
5. Can be reached over HTTP from Priya's and Tomas's computers, with Priya and Tomas able to read but not write.
6. Does not obey instructions hidden in a note or in another server's tool descriptions, and never leaks what it reads to a log.

You are the engineer building it.

What this course uses the project for

This course is about the Model Context Protocol: why it exists, what goes over the wire, how to build servers and hosts, how to authorise and secure them, and how to run them in production. The notes assistant is the instrument. It is deliberately small (eight notes, two tools) so that the protocol, not the domain, is what you learn, and so you can check every answer by reading the notes yourself.

It is not the BrightCart store of the AI Engineering course, the Harbourline Freight engagement of the Forward Deployed Engineer course, the returns desk of the Agentic AI Engineer course or the Quillpath support desk of the LLMs course. The Agentic AI Engineer course's Module 4 teaches MCP as one tool in an agent stack; this course goes deeper on every point and links to it where the two overlap.

The people

One minor name recurs: the Motor lab, the other group that shares the EEG caps, appears in the calendar's bookings. Other minor characters may appear in a single lesson. The main cast above does not change.

The lab's systems

Nare's lab has six tool systems. The course builds servers for the first three; the other three appear only in Module 1's arithmetic and as made-up servers in Module 6.

Fixed names

Every module calls the server's parts by the same names, so that code from one module works in the next.

The notes server (final form from Module 5, with authorisation from Module 7):

create_note is marked read_only_hint=False and destructive_hint=False. It is not destructive, because it cannot overwrite anything; the host still asks Nare before calling it, because its rule is "anything that is not read-only needs approval". Lessons keep that wording.

The calendar server (Module 6; Module 10 adds one tool): search_notes (read-only; searches the notes attached to bookings, and collides on purpose with the notes server's tool of the same name), list_bookings(week_of, resource) (read-only), book_slot(resource, day, booked_by, note) (not read-only; fails if the resource is booked that day), cancel_booking(booking_id) (destructive), calendar://bookings (resource), and from Module 10 check_availability(resource, week_of) (read-only).

The host (Module 6): namespaces tools as <server>__<tool>, for example notes__search_notes and calendar__search_notes, and adds one tool of its own, read_resource, so the model can open a note by its URI. With HostConfig(tool_search=True) it shows a second tool of its own, find_tools, instead of the full list (Module 6 Lesson 3).

Library names (from Module 1): NoteStore, Note, SearchHit, NoteError, NoteNotFound, NoteExists, InvalidNote, slugify, validate_note_id in store.py; chat(), ToolCall, ChatReply, LLM_PROVIDER, LLM_MODEL in llm.py. Lessons may add names; they do not rename these.

Fixed facts

The shared data (the notes, the bookings, the reference stand-in, the attack notes, the evaluation sets) is in 06-shared-data.md as code that writes every file. Nothing is downloaded.

Models

The hosted models are the course defaults in 02-setup-colab-and-llm-providers.md: Groq openai/gpt-oss-20b, Gemini gemini-3.5-flash-lite, or Ollama llama3.2:3b on your own computer, switched by one setting. Many lessons also use a scripted stand-in: a few lines of Python that pretend to be a model and always choose the same tool. It is free and repeatable, so it tests plumbing (the loop, the approval gate, the pinning check) and drives the attack demonstrations. Every lesson that uses one says so, and its output is never presented as what a model did. Whenever a lesson claims something about model behaviour, the output comes from a real model, run with real keys.

Dates

• Course date: Tuesday 13 October 2026. The specification, SDK and Inspector versions, model names and prices were checked on this day. Lessons say "(checked October 2026)".
• The project: Monday 7 September 2026 to Friday 9 October 2026, five weeks. Lessons are told in the present tense, as if you are there.
• The data date: Monday 7 September 2026, the first day. The eight notes are a snapshot of the folder that morning (DATA_AS_OF).

Key events

Lessons refer to these events. They are fixed, so that every module tells the same story. Week N starts on the Monday shown. All of them are simulated.

The course does not fix the assistant's accuracy, speed or cost in advance. Those numbers come from running your own code, and they are what your capstone write-up reports.

What you build, module by module

The repository, file by file

You build one repository, notes-assistant/, with one package, notes_assistant/. Lesson cells try ideas in the notebook; only the module labs write files into the repository (in your Google Drive, see course-guide/02). The table lists what each lab adds or changes. Scripts in examples/ are named mNN_*.py by module.

Labs write repository files with %%ensure, the course's cell magic from the Module 1 lab: it writes a missing file and keeps one the repository already has. Each lab first rebuilds every earlier lab's files the same way, so a learner who skipped a lab catches up. The rows above are what each lab adds; the test counts are the lab's own tests and, in brackets after the semicolon, the whole suite after that lab.

The packaged server from Module 5 changes three things against Module 3's examples/m03_server.py, and every later module uses the package:

• search_notes returns a list of hits, which the SDK wraps as {"result": [...]}. Code that read structured_content["hits"] reads structured_content["result"]. Each hit keeps note_id, title, score, snippet and uri.
• today is a function, passed by keyword and called on every save: build_server(store, *, today=date.today). Module 3 took a date. Lessons and tests always pass a fixed date (today=lambda: DATA_AS_OF).
• The server is MCPServer("notes", title="Nare's notes", version="0.5.0"). Module 4's confirming create_note, completion and import_zotero stay in examples/m04_*.py; the package's resources and prompt are plain.

The Module 7 upgrade. server.py is not rewritten. A code cell in the Module 7 lab (marked # Module 7 lab: upgrade) makes guarded edits and the cell after it applies them: build_server gains token_verifier=None, auth=None (left out, it is exactly the Module 5 server), each tool checks its scope when a verifier is present, and main() turns auth on for HTTP only, from NOTES_AUTH_ISSUER, NOTES_AUTH_JWKS_URL and NOTES_RESOURCE_URL. Every later lab pastes those two cells after the Module 5 server.py cells.

Settings. The package reads NOTES_DIR, NOTES_TRANSPORT, NOTES_HOST, NOTES_PORT (default 8050) and NOTES_LOG_LEVEL (Module 5), and NOTES_AUTH_ISSUER, NOTES_AUTH_JWKS_URL and NOTES_RESOURCE_URL (Module 7). The reindex server, examples/m05_reindex_server.py, also reads NOTES_INDEX (where the index file goes, default notes-index.json) and NOTES_REINDEX_DELAY (seconds per note, default 0.3, so progress and cancellation can be seen). The calendar reads CALENDAR_DELAY_SECONDS.

.gitignore. No lab before Module 11 writes one. Until then the labs commit by naming the project's files in git add, so logs, caches, .pins/ and the scratch folders stay out; Module 11 adds the file.

Two rules hold throughout. store.py never imports mcp: the notes logic stays testable without a protocol. And server.py stays thin while host.py owns policy (approval, namespacing, pinning, timeouts), so a change to one never forces a change to the other.

The finished notes assistant

• One MCP server over Nare's notes, served over stdio and Streamable HTTP, with two tools, two resources and a prompt
• A host that connects a model to two servers, namespaces their tools and asks before any write
• Answers that cite the note they came from, and a plain "the notes do not say" when they do not
• Token verification with audience and scope checks on the HTTP server
• Pinned tool definitions, an approval gate and tests for six attack classes
• Two stateless replicas, rate limits per person, redacted logs, tracing and a resumable bulk import
• An evaluation of tool choice and answers with a regression gate
• A repository with tests that pass, a README a stranger can follow, and a record of what broke

The one idea

A protocol is a promise between programs written by people who never meet. Most of this course is about keeping that promise honest: saying exactly what a tool does, refusing what it should not do, checking who is asking, and treating everything that arrives over the wire, including a tool's own description, as something to verify rather than obey.

Changes from the earlier version (for authors)

The earlier version of this course (/Courses/MCP/) used the same project. What was kept and what changed:

• Kept. The notes assistant, Nare, Priya and Tomas, the eight notes word for word, the anchor note, the store's rules, the tool, resource and prompt names, the calendar's bookings, the attack notes, the evaluation sets, the notes_assistant/ package name and the port bands.
• A fixed timeline. The earlier version had dated notes but no project calendar. The project now runs from 7 September to 9 October 2026, with DATA_AS_OF on 7 September and the events above.
• Models. The earlier default on Groq, llama-3.3-70b-versatile, was shut down on 16 August 2026. The course now uses the defaults shared by every course in this series (course-guide/02), and llm.py is built on LangChain instead of the openai client library.
• Real outputs only. The earlier version had no model key and marked model output "illustrative". Every model output in this course comes from a real run; scripted stand-ins remain for plumbing and attacks, and are labelled.
• One calendar. Modules 6 and 10 of the earlier version had two calendar servers with different bookings. There is now one, examples/calendar_server.py, with the bookings in course-guide/06; Module 10 adds check_availability to it.
• Dates in code. NoteStore.create stamped notes with date.today(), so outputs changed with the day you ran them. It now takes the date as an argument.
• Colab first. The earlier version ran from a terminal, with PYTHONPATH=., servers started in a second shell and curl. Lessons now write their files from cells, use top-level await, and run servers in background threads or subprocesses (course-guide/02).
• Versions. mcp 2.2.0 became 2.3.0; the Inspector 2.7.0 became 2.10.1 (Node.js 22.19.0 or newer).