modelcontextprotocol--python-sdk/examples/stories/stickynotes/README.md

stickynotes

The "real app" capstone: tools mutate a sticky-notes board held in the server's lifespan context, each note is a note:///{id} resource, notifications/resources/list_changed fires on add/remove, and remove_all blocks on a form-mode elicitation so the user must explicitly confirm a destructive clear.

Run it

# stdio (default — the client spawns the server as a subprocess)
uv run python -m stories.stickynotes.client

# HTTP — the client self-hosts the server on a free port, runs, then tears it down
uv run python -m stories.stickynotes.client --http
# same, against the lowlevel-API server variant
uv run python -m stories.stickynotes.client --http --server server_lowlevel

What to look at

• client.py main → Client(target, mode=mode, elicitation_callback=..., message_handler=...) — the construction is the example: callbacks are plain constructor kwargs, and mode= is explicit. The scripted elicitation answer and the list_changed event are locals of main, so every connection starts clean.
• server.py lifespan → Board — long-lived mutable state belongs in the lifespan context, never a module global. Tools reach it via ctx.request_context.lifespan_context; this 2-hop path is interim and will shorten to ctx.state.* in a later release.
• add_note / remove_note — mcp.add_resource(FunctionResource(...)) registers a concrete resource at runtime; ctx.session.send_resource_list_changed() tells connected clients to re-list. Gap: MCPServer has no public remove_resource() yet, so remove_note reaches a private attribute — do not copy that line. server_lowlevel.py shows the clean equivalent: on_list_resources reads the board and builds the list fresh per call, so removal is just board.notes.pop(...) with no registry mutation.
• remove_all → ctx.elicit(...) — push-style server→client elicitation needs a back-channel and an advertised client capability, so it only runs on the legacy-era legs. On a modern connection there is no server→client request channel; the modern equivalent is the multi-round-trip InputRequiredResult flow (see mrtr/, not yet implemented). The client branches on client.protocol_version.

Caveats

• list_changed and ctx.elicit() are skipped on modern legs: the notification needs a standalone stream and ctx.elicit() would raise NoBackChannelError. main branches on client.protocol_version in HANDSHAKE_PROTOCOL_VERSIONS.

Spec

• Tools
• Resources
• Elicitation

See also

tools/, resources/, legacy_elicitation/, lifespan/, standalone_get/ (list_changed over the GET stream).