@@ -85,7 +85,7 @@ Return a list of messages instead of a `str`:
 --8<-- "docs_src/prompts/tutorial002.py"
 ```
 
-* `UserMessage` and `AssistantMessage` come from `mcp.server.mcpserver.prompts.base`. Hand them a `str` and they wrap it in `TextContent` for you. The role is the class name.
+* `UserMessage` and `AssistantMessage` come from `mcp.server.mcpserver`. Hand them a `str` and they wrap it in `TextContent` for you. The role is the class name.
 * `Message` is their common base. Use it as the return annotation.
 
 Rendering `debug_error` now produces three messages, in order:
@@ -134,17 +134,172 @@ The `prompts/list` entry now carries everything a client needs to draw a good fo
 ```
 
 !!! info
-    If you have read **[Tools](tools.md)**, you already know everything on this page. Same decorator, same
+    If you have read **[Tools](tools.md)**, you already know everything up to this point. Same decorator, same
     docstring-as-description, same `Annotated`/`Field`. The only things that change are who
     triggers it (the user) and where the result goes (into the conversation).
 
+## More than text
+
+A prompt message does not have to be text. Wherever `UserMessage` and `AssistantMessage` (the message classes from `mcp.server.mcpserver`) take a `str`, they also take a **content block**: any of the kinds a tool result can carry, which **[Images, audio & icons](media.md)** shows a tool producing one by one. This section uses two: an **embedded resource**, which carries a whole document along with its URI and MIME type, and an **image**.
+
+### Embedding a file
+
+A code review goes better when the reviewer has the team's style guide open. The Code Helper team keeps theirs in `style-guide.md`, next to `server.py`. Hand it to the model as a message of its own, ahead of the code:
+
+```python title="server.py" hl_lines="5 12 21 23"
+--8<-- "docs_src/prompts/tutorial004.py"
+```
+
+* `@mcp.resource(...)` publishes the file at `style://python`, the way **[Resources](resources.md)** describes. Embedding does not depend on this line, but with it the URI inside the message is one a client can actually read back.
+* `TextResourceContents` is what a client receives when it reads a text resource: a `uri`, a `mime_type`, and the `text`. Here the `text` comes from calling `style_guide()` directly (the decorator hands your function back unchanged), so the resource and the prompt serve one file from one place, read fresh on every render.
+* `EmbeddedResource(resource=...)` is the content block that carries the document, and `UserMessage` takes it in place of a `str`. A block has no role of its own; the message supplies one. `EmbeddedResource` and `TextResourceContents` are protocol types from `mcp.types`.
+
+Put a `style-guide.md` beside `server.py` (two bullet points of Markdown will do), then render `review_code`. The guide arrives as the first message and the request that refers to it as the second:
+
+```json
+{
+  "description": "Review a piece of code against the team style guide.",
+  "messages": [
+    {
+      "role": "user",
+      "content": {
+        "type": "resource",
+        "resource": {
+          "uri": "style://python",
+          "mimeType": "text/markdown",
+          "text": "* Prefer early returns.\n* No bare `except:`.\n"
+        }
+      }
+    },
+    {
+      "role": "user",
+      "content": {
+        "type": "text",
+        "text": "Review this code against the style guide above:\n\ndef add(a, b): return a + b"
+      }
+    }
+  ],
+  "resultType": "complete"
+}
+```
+
+You could paste the guide into the second message's f-string and the model would read the same words. Embedding it tells the client that this message is a document, with a URI and a format, so the client can show it as an attachment rather than a screenful of prose in the user's turn, and can read `style://python` again later. The model receives the file verbatim rather than folded into a sentence, and because the copy travels inside the message there is no `resources/read` round trip. Keep instructions in strings; send reference material (a style guide, a schema, the file under review) as an embedded resource.
+
+A binary document embeds the same way with `BlobResourceContents` (also in `mcp.types`) in place of `TextResourceContents`: base64-encode the bytes into its `blob` field with `base64.b64encode(data).decode()` and give it the real `mime_type` (`application/pdf`, say). The spec requires a URI and a MIME type on every embedded resource; the SDK types do not enforce `mime_type`, so setting it is yours to remember. For a picture the model should look at, an image block (below) is the better fit.
+
+!!! info
+    An embedded resource is a copy. When the document is large, or the client may not want it
+    at all, send a pointer instead: `ResourceLink(name="style_guide", uri="style://python",
+    mime_type="text/markdown")`, also from `mcp.types`, goes into a `UserMessage` the same way.
+    Nothing is embedded; the client reads the URI with `resources/read` if and when it wants the
+    contents, which only works when the URI really is one of your resources.
+
+### Attaching an image
+
+A message can also carry a picture, as an `ImageContent` block, for a model that accepts images. The Code Helper project keeps its architecture diagram beside the code as `architecture.png`:
+
+```python title="server.py" hl_lines="4 15"
+--8<-- "docs_src/prompts/tutorial005.py"
+```
+
+* `Image` is the helper from **[Images, audio & icons](media.md)**. Give it `path=` and the MIME type is guessed from the suffix (`.png` is announced as `image/png`); for bytes already in memory, give it `data=` plus an explicit `format=`.
+* `UserMessage` converts it: the file is read and base64-encoded when the prompt renders, and the message carries the protocol's `ImageContent`. `Audio(...)` becomes an `AudioContent` the same way.
+* `component` is an ordinary prompt argument, and prompt arguments are always strings. A user cannot pass a picture in through one, so the image is something the server already has (a file on disk, a chart it just rendered) and the argument only supplies the words.
+
+Any PNG named `architecture.png` beside `server.py` works. The client receives the diagram, then the question:
+
+```json
+{
+  "description": "Explain one component using the architecture diagram.",
+  "messages": [
+    {
+      "role": "user",
+      "content": {"type": "image", "data": "iVBORw0KGgoAAAANSUhEUg...", "mimeType": "image/png"}
+    },
+    {
+      "role": "user",
+      "content": {
+        "type": "text",
+        "text": "Where does the payment gateway sit in this architecture, and what does it talk to?"
+      }
+    }
+  ],
+  "resultType": "complete"
+}
+```
+
+`data` is the whole file, base64-encoded (cut short here).
+
+!!! tip
+    When every message is from the user, you can skip the wrappers: a prompt function may return
+    an `Image`, a content block, or a list mixing them with strings, and each item becomes one
+    user message, in order. `return [Image(path=DIAGRAM_FILE), f"Where does {component} sit..."]`
+    renders exactly the two messages above. You only need `UserMessage` / `AssistantMessage`
+    when one of the messages is an `assistant` turn.
+
+A client needs nothing extra to receive these. In the Python `Client`, the `content` of each message in `get_prompt(...)`'s `messages` is typed as the same content-block union a tool result uses (`TextContent`, `ImageContent`, `AudioContent`, `ResourceLink`, `EmbeddedResource`). Narrow with `isinstance(block, EmbeddedResource)` or `isinstance(block, ImageContent)` before touching `.resource` or `.data`, as **[The Client](../client/index.md)** does with tool results.
+
+## Changing the list at runtime
+
+A decorated prompt exists from the moment the module is imported. The menu can also change while clients are connected: a user who keeps typing the same instruction ("explain this, line by line") wants it as an entry of its own, next to `review_code`.
+
+Saving one is something the model does when the user asks, which makes it a tool. The tool does two things: register a prompt while the server is running, then tell connected clients that the list changed.
+
+```python title="server.py" hl_lines="3 21-23"
+--8<-- "docs_src/prompts/tutorial006.py"
+```
+
+* `mcp.add_prompt(...)` takes a `Prompt` object, not a bare function. `Prompt.from_function` builds one from `template` exactly as `@mcp.prompt()` would, arguments included, so the new entry gets one required `code` argument. Pass `name=` and `description=`: left to default they come from the function, and every function this tool defines is called `template` and has no docstring.
+* `ctx` is the parameter annotated `Context`. The SDK injects it and the model never sees it: `save_template`'s input schema has two properties, `name` and `instruction`. **[The Context](../handlers/context.md)** is the page about that object.
+* `await ctx.notify_prompts_changed()` publishes the change to every `2026-07-28` client whose `subscriptions/listen` stream asked for prompt-list changes. With no such stream open it is a no-op, so there is nothing to check before calling it. **[Subscriptions](../handlers/subscriptions.md)** under *Inside your handler* is the page on those streams.
+* `await ctx.session.send_prompt_list_changed()` sends the same notification to the client that made this call, if it is a pre-2026 client, down the stream its session keeps open. Other pre-2026 sessions are not told; they see the change on their next `prompts/list`. Neither line reaches the other era's clients, and neither raises when there is nobody to tell, so call both. **[Serving legacy clients](../run/legacy-clients.md)** explains the split.
+
+Call `save_template` with `name="explain"` and `instruction="Explain what this code does, line by line."`. `prompts/list` includes `explain` the moment `add_prompt` returns; the notification exists only to tell clients that are already connected to ask again. On a `subscriptions/listen` stream it is one frame:
+
+```json
+{"method": "notifications/prompts/list_changed",
+ "params": {"_meta": {"io.modelcontextprotocol/subscriptionId": "listen-1"}}}
+```
+
+It names no prompt, only the stream it arrived on. A pre-2026 client receives the bare `{"method": "notifications/prompts/list_changed"}` on its session's stream instead. Either way the client calls `prompts/list` again and finds the new entry beside `review_code`:
+
+```json
+{
+  "name": "explain",
+  "description": "Explain what this code does, line by line.",
+  "arguments": [
+    {"name": "code", "required": true}
+  ]
+}
+```
+
+In the Python `Client`, the `subscriptions/listen` stream is `async with client.listen(prompts_list_changed=True) as sub:` and each change arrives as a `PromptsListChanged` event; **[Subscriptions](../client/subscriptions.md)** under *Clients* covers that end.
+
+!!! check
+    Save `explain` a second time with different wording. The tool answers
+    `Saved 'explain' to the prompt menu.` again, `prompts/list` still shows the first description,
+    `prompts/get` still renders the first text, and the server logs one warning:
+
+    ```text
+    Prompt already exists: explain
+    ```
+
+    `add_prompt` keeps the entry it has and ignores the new one. `mcp.remove_prompt(name)` is its
+    reverse and wants the same two notification calls after it; unlike `add_prompt` it raises
+    `ValueError` for a name it does not have. Replacing a template is remove (if it exists), then
+    add, then notify.
+
+Publish when the *menu* changes: an entry added, removed or replaced. When only the text behind an existing entry changes there is nothing to announce, because `prompts/get` renders it fresh every time.
+
 ## Recap
 
 * `@mcp.prompt()` on a function makes it a prompt. Name from the function, description from the docstring.
 * Prompts are **user-controlled**: the client lists them, the user picks one and fills in the arguments.
 * Arguments are a flat list of named strings (no schema). A parameter with a default is optional.
 * Return a `str` and it becomes one user message. Return a list of `UserMessage` / `AssistantMessage` to seed a multi-turn conversation.
 * `title=` and `Field(description=...)` are what a client puts in its UI.
+* A message is not limited to text. Wrap an `EmbeddedResource` in a `UserMessage` to attach a document with its URI and MIME type, or an `Image` to attach a picture.
 * A missing required argument fails the whole request. There is no per-prompt error result.
+* The menu can change while clients are connected: `mcp.add_prompt(Prompt.from_function(...))` or `mcp.remove_prompt(name)`, then `await ctx.notify_prompts_changed()` for listening `2026-07-28` clients and `await ctx.session.send_prompt_list_changed()` for a pre-2026 caller.
 
 Server-side autocomplete for a prompt's (or a resource template's) arguments is **[Completions](completions.md)**.
@@ -1,5 +1,5 @@
 from mcp.server import MCPServer
-from mcp.server.mcpserver.prompts.base import AssistantMessage, Message, UserMessage
+from mcp.server.mcpserver import AssistantMessage, Message, UserMessage
 
 mcp = MCPServer("Code Helper")
 
 
@@ -0,0 +1,25 @@
+from pathlib import Path
+
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Message, UserMessage
+from mcp.types import EmbeddedResource, TextResourceContents
+
+mcp = MCPServer("Code Helper")
+
+STYLE_GUIDE_FILE = Path(__file__).parent / "style-guide.md"  # or the path to your file on disk
+
+
+@mcp.resource("style://python", mime_type="text/markdown")
+def style_guide() -> str:
+    """The team's Python style guide."""
+    return STYLE_GUIDE_FILE.read_text(encoding="utf-8")
+
+
+@mcp.prompt()
+def review_code(code: str) -> list[Message]:
+    """Review a piece of code against the team style guide."""
+    guide = TextResourceContents(uri="style://python", mime_type="text/markdown", text=style_guide())
+    return [
+        UserMessage(EmbeddedResource(resource=guide)),
+        UserMessage(f"Review this code against the style guide above:\n\n{code}"),
+    ]
@@ -0,0 +1,17 @@
+from pathlib import Path
+
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Image, Message, UserMessage
+
+mcp = MCPServer("Code Helper")
+
+DIAGRAM_FILE = Path(__file__).parent / "architecture.png"  # or the path to your file on disk
+
+
+@mcp.prompt()
+def explain_component(component: str) -> list[Message]:
+    """Explain one component using the architecture diagram."""
+    return [
+        UserMessage(Image(path=DIAGRAM_FILE)),
+        UserMessage(f"Where does {component} sit in this architecture, and what does it talk to?"),
+    ]
@@ -0,0 +1,24 @@
+from mcp.server import MCPServer
+from mcp.server.mcpserver import Context
+from mcp.server.mcpserver.prompts import Prompt
+
+mcp = MCPServer("Code Helper")
+
+
+@mcp.prompt()
+def review_code(code: str) -> str:
+    """Review a piece of code."""
+    return f"Please review this code:\n\n{code}"
+
+
+@mcp.tool()
+async def save_template(name: str, instruction: str, ctx: Context) -> str:
+    """Save an instruction as a prompt the user can pick from the menu."""
+
+    def template(code: str) -> str:
+        return f"{instruction}\n\n{code}"
+
+    mcp.add_prompt(Prompt.from_function(template, name=name, description=instruction))
+    await ctx.notify_prompts_changed()
+    await ctx.session.send_prompt_list_changed()
+    return f"Saved '{name}' to the prompt menu."