# MCP Notes Server Example

The companion code for the [Model Context Protocol course](https://www.youtube.com/watch?v=XmFTYnGpPTs) on the Mind & Matter YouTube channel, from Advanced AI Systems Research Corporation (AAIRC).

It's a small notebook server and client built with the official [MCP Python SDK](https://pypi.org/project/mcp/). The same code works over both the stateless `2026-07-28` protocol and the older `initialize` handshake.

The course is presented by Maya, an AI avatar.

## Quick start

You need Python 3.10 or newer.

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

python notes_client.py auto      # discover first, fall back to the handshake if needed
python notes_client.py legacy    # force the initialize handshake
```

Expected output includes:

```text
tools: ['search_notes', 'add_note', 'reindex']
add_note -> saved note 'stdio'
  progress 1.0/3.0: pass 1 of 3
  progress 2.0/3.0: pass 2 of 3
  progress 3.0/3.0: pass 3 of 3
reindex -> index rebuilt
notes://mcp -> MCP connects AI apps to tools and data.
```

## What's here

| File | What it shows | Course chapter |
|---|---|---|
| `notes_server.py` | Tools, structured output, annotations, progress, a resource template and a prompt | 12 |
| `notes_server_plus.py` | A delete tool that asks the user to confirm | 12 |
| `notes_client.py` | A client that launches the server over stdio and uses each feature | 13 |
| `confirm_client.py` | Answering the server's confirmation question | 12 |
| `agent.py` | A small agent: Claude decides, the MCP server acts | 13 |
| `wiretap.py`, `traced_client.py` | Log every JSON-RPC message between client and server | 3, 13 |
| `wire_*.log` | Sample message traces from both protocol versions | 3, 4, 7 |

## See the protocol on the wire

```bash
python traced_client.py auto
python confirm_client.py auto      # input_required, then a retry
python confirm_client.py legacy    # a mid-call elicitation/create request
```

These commands append to the `wire_*.log` files in this folder.

## Run the agent

```bash
python agent.py --fake                               # offline, uses a scripted model
python agent.py "What do my notes say about MCP?"    # needs Anthropic credentials
```

## What was tested

With `mcp` 2.3.0 on Python 3.12, these all ran successfully: `notes_client.py`, `confirm_client.py` and `traced_client.py` in both `auto` and `legacy` modes, and `agent.py --fake`.

The live Claude mode of `agent.py` has not been run. The fake mode tests the MCP side and the tool conversion, but not a real model.

## This is teaching code

Notes live in memory and disappear when the server stops. There's no authentication, and `delete_note` has no per-user access checks. Before using these patterns in production, add the input validation, access control and safeguards covered in the course's security chapter.

## License

[MIT](LICENSE)