docs: embedded resources and resource links on the media page

The media page claimed to cover everything a tool can return besides
text but stopped at Image/Audio. Add "Embedding a resource" (a tool
returning an EmbeddedResource with the registered resource's URI and
MIME type; TextResourceContents vs BlobResourceContents) and "Linking to
a resource" (a mixed list result with a ResourceLink the client follows,
plus the dangling-link failure), with two new docs_src modules and the
tests that pin every claim.

No-Verification-Needed: docs, docs_src examples and tests only

Author: maxisbey

docs/servers/index.md

@@ -18,7 +18,8 @@ Around the three primitives, the rest of what a server declares:
 * **[Completions](completions.md)** is server-side autocomplete for prompt
   and resource-template arguments.
 * **[Images, audio & icons](media.md)** covers everything a tool can
-  return besides text, and the icons a client shows next to your server.
+  return besides text (images, audio, embedded documents, links to
+  resources), and the icons a client shows next to your server.
 * **[Handling errors](handling-errors.md)** explains the difference between an
   error the model can recover from and one it must never see.
 

docs/servers/media.md

@@ -2,7 +2,7 @@
 
 Text is not the only thing a tool can return.
 
-The SDK ships two helpers for binary results (**`Image`** and **`Audio`**) and an **`Icon`** type for giving your server, tools, resources, and prompts a face in the client's UI.
+The SDK ships two helpers for binary results (**`Image`** and **`Audio`**) and an **`Icon`** type for giving your server, tools, resources, and prompts a face in the client's UI. Two protocol types cover results that are documents rather than pictures or sound: an **`EmbeddedResource`** carries a resource's contents inside the result, and a **`ResourceLink`** points at one for the client to read.
 
 ## Returning an image
 
@@ -31,7 +31,9 @@ Two things to notice:
 !!! info
     `ImageContent` and `AudioContent` live in `mcp.types`, right next to the `TextContent`
     that a plain `str` result becomes (**[Tools](tools.md)**). A tool result is a list of content blocks; `Image` and `Audio` are
-    the shortest way to produce the two binary kinds.
+    the shortest way to produce the two binary kinds. The other two kinds, `EmbeddedResource` and
+    `ResourceLink`, are for documents rather than media: one carries the contents, the other points
+    at them. Each has its own section below.
 
 ### Try it
 
@@ -62,7 +64,7 @@ Same deal: a file on disk in, base64 and a MIME type out, no output schema.
 
 ## Bytes or a file
 
-Both helpers also accept `data=` (raw bytes) instead of `path=`. That is the mode for bytes that never came from a file of their own — a database column, an HTTP response, something Pillow just drew:
+Both helpers also accept `data=` (raw bytes) instead of `path=`. That is the mode for bytes that never came from a file of their own (a database column, an HTTP response, something Pillow just drew):
 
 ```python title="server.py" hl_lines="14 15"
 --8<-- "docs_src/media/tutorial003.py"
@@ -81,6 +83,143 @@ A suffix it doesn't recognise falls back to `application/octet-stream`.
     `Audio` from MP3 bytes that way and the client is told `mime_type="audio/wav"`, then
     faithfully fails to decode it. When you pass `data=`, pass `format=`.
 
+## Embedding a resource
+
+An **embedded resource** is a document carried inside a tool result: its text or bytes, the URI it lives at, and a MIME type.
+
+A `str` result puts words in front of the model and an `Image` puts pixels there, but neither says what the content *is* or where it came from. An embedded resource does, which is what lets a client treat the block as a file rather than a string: it can render the Markdown, offer a download, or recognise a URI it already has open as context.
+
+Say the example server, a brand kit, publishes its usage guidelines as a resource at `brand://guidelines`. That is how the *application* reads them, as **[Resources](resources.md)** describes. To hand the same document to the *model* on request, return it from a tool:
+
+```python title="server.py" hl_lines="7 14 16-18"
+--8<-- "docs_src/media/tutorial005.py"
+```
+
+* `brand://guidelines` is an ordinary resource, declared exactly as it would be if no tool embedded it.
+* `brand_guidelines` is a tool that returns the same document as an `EmbeddedResource`. There is no SDK helper here as there is for images: `EmbeddedResource` and `TextResourceContents` are the protocol types from `mcp.types`, and the block you build goes into the result untouched.
+* The inner `TextResourceContents` holds the `uri`, the `mime_type`, and the `text`, exactly what a client receives when it reads a text resource. The text comes from calling `guidelines()` directly, an ordinary function call (the decorator hands your function back unchanged), so the resource and the tool serve one document from one place and the client needs no follow-up `resources/read`.
+
+On the wire that is one block whose `type` is `"resource"`, with the contents nested one level down, and no `structuredContent` key at all: like an `Image`, a document is content for the model to read, not data for the application to parse.
+
+```json
+{
+  "content": [
+    {
+      "type": "resource",
+      "resource": {
+        "uri": "brand://guidelines",
+        "mimeType": "text/markdown",
+        "text": "# Brand guidelines\n\nUse the primary colour for calls to action.\n"
+      }
+    }
+  ],
+  "isError": false,
+  "resultType": "complete"
+}
+```
+
+The URI does not have to name a registered resource: any scheme is legal, and the tool call succeeds either way. Prefer one that resolves, because the URI is what a client uses to reopen or refresh the document later, and to tell that this block and `brand://guidelines` are the same thing.
+
+### Text or bytes
+
+`TextResourceContents` carries `text`. A binary document (the full brand book as a PDF, say) goes in a `BlobResourceContents` instead, and the base64 encoding that `Image` did for you is now yours to do:
+
+```python
+import base64
+from pathlib import Path
+
+from mcp.types import BlobResourceContents, EmbeddedResource
+
+EmbeddedResource(
+    resource=BlobResourceContents(
+        uri="brand://book",
+        mime_type="application/pdf",
+        blob=base64.b64encode(Path("brand-book.pdf").read_bytes()).decode(),
+    )
+)
+```
+
+For a picture the model should *look at*, `Image` is still the better choice: an `ImageContent` is the block clients know to display, while what a client does with an embedded `image/png` blob is up to that client. Embed bytes for something that is genuinely a file, such as a PDF, a font, or an archive of assets.
+
+## Linking to a resource
+
+A **resource link** is a pointer: the URI and name of a resource the client can read, plus a little metadata about it, and none of its contents.
+
+Embedding copies the document into the result, which is wasteful when the document is large or the model may never need it. A logo PNG is tens of kilobytes that most callers only need to know exists; a link to it is a couple of hundred bytes, and the client decides whether to spend a `resources/read` on the rest.
+
+Put any PNG next to `server.py` as `logo.png`, publish it as a resource at `brand://logo`, and return one result that mixes text, an embedded document, and a link:
+
+```python title="server.py" hl_lines="17 24 30 32-39"
+--8<-- "docs_src/media/tutorial006.py"
+```
+
+* `brand://logo` is a resource whose function returns `bytes`, so a client that reads it receives a blob.
+* `brand_brief` returns a **list**, and each item becomes one content block, in order: the `str` becomes a `TextContent` and the two protocol blocks pass through untouched. This is how any tool returns several blocks of different kinds.
+* The guidelines are a few lines of Markdown the model needs now, so they are embedded. `annotations=` is a field of every content block and sits on the `EmbeddedResource` beside `resource=`, not inside the `TextResourceContents`; `audience=["assistant"]` marks the block as context for the model rather than something to display.
+* The logo is linked. `ResourceLink` has the fields of a `resources/list` entry: `name` and `uri` are required; `title`, `description`, `mime_type`, and `size` are what a client shows a person deciding whether to fetch it. `size` is the raw byte count before base64, so the client can also estimate what reading it would cost in context window.
+
+On the wire the three blocks arrive in order. The link is flat where the embedded resource is nested:
+
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "Follow the attached guidelines. The logo is linked; read it if you need the pixels."
+    },
+    {
+      "type": "resource",
+      "resource": {
+        "uri": "brand://guidelines",
+        "mimeType": "text/markdown",
+        "text": "# Brand guidelines\n\nUse the primary colour for calls to action.\n"
+      },
+      "annotations": {"audience": ["assistant"]}
+    },
+    {
+      "type": "resource_link",
+      "name": "logo",
+      "title": "Brand logo",
+      "uri": "brand://logo",
+      "description": "Full-colour logo, 2000 by 2000 pixels.",
+      "mimeType": "image/png",
+      "size": 48213
+    }
+  ],
+  "isError": false,
+  "resultType": "complete"
+}
+```
+
+None of the logo's bytes are in the result, only its description and size (`48213` here; yours is the size of whichever `logo.png` you used). A client that wants the pixels narrows the block to a `ResourceLink` and reads its URI like any other resource; what comes back is the logo as a blob:
+
+```python
+async def show_logo(client: Client, result: CallToolResult) -> None:
+    link = result.content[2]
+    assert isinstance(link, ResourceLink)  # narrow the union before touching .uri
+    logo = await client.read_resource(link.uri)
+    print(logo.contents)  # [BlobResourceContents(uri="brand://logo", mime_type="image/png", blob="iVBORw0KGgo...")]
+```
+
+That is two requests instead of one, and the second happens only if somebody wants it. As a rule, embed what the model needs now and can read (mostly text), and link what is large, optional, or one of many: a tool that finds forty matching files returns forty links, not forty files.
+
+!!! check
+    A link is a promise that `resources/read` will answer for that URI, and nothing checks the
+    promise when the tool returns. Add a second link, to `brand://wordmark`, without registering
+    a resource there: the tool call succeeds, and the client that follows the link is the one
+    that finds out.
+
+    ```text
+    mcp.shared.exceptions.MCPError: Unknown resource: brand://wordmark
+    ```
+
+    That is a JSON-RPC error (code `-32602`) raised at the caller, not a tool result the model
+    can read. A link does not have to appear in `resources/list` (a URI served by a resource
+    template never does), but it does have to resolve. Register the resource, then hand out its
+    address.
+
+A prompt message can carry either block too; **[Prompts](prompts.md#more-than-text)** shows a file embedded in one.
+
 ## Icons
 
 An `Icon` is metadata, not content. It doesn't carry the image; it points at one with a URI, and a client may fetch it and show it next to your server's name, a tool, a resource, or a prompt.
@@ -110,6 +249,9 @@ A tool's icons are on the `Tool` object from `tools/list`, a resource's on the `
 
 * Return an `Image` or `Audio` from a tool and the client receives an `ImageContent` / `AudioContent` block: your bytes base64-encoded, with a MIME type.
 * Build one from a `path=` and let the suffix decide the MIME type, or from in-memory `data=` plus an explicit `format=`.
+* Return an `EmbeddedResource` to put a whole document in the result: a `TextResourceContents` (or a `BlobResourceContents` with a base64 `blob`) carrying its `uri`, a MIME type, and the contents.
+* Return a `ResourceLink` to send only the pointer. The client follows it with `resources/read`, so link to URIs that resolve.
+* A list return value becomes one content block per item, so one result can mix text, media, documents and links.
 * Media results carry no `structured_content` and no output schema.
 * An `Icon` is a pointer: a `src` URI plus optional `mime_type`, `sizes`, and `theme`.
 * `icons=[...]` works on the server, on tools, on resources, and on prompts, and clients find them on the matching objects.

docs/servers/structured-output.md

@@ -210,7 +210,7 @@ The opposite, `structured_output=True`, turns the automatic detection into a req
 
 ## Content blocks and media
 
-Content blocks and media (`TextContent`, `EmbeddedResource`, `Image`, `Audio` and friends, on their own, as the items of a `list`, `tuple` or `Sequence`, or as the arms of a union) are opted out for you: they are for the model to read, so auto-detection derives no schema from them (**[Images, audio & icons](media.md)** covers `Image` and `Audio`). `structured_output=True` still forces one for the content-block classes.
+Content blocks and media (`TextContent`, `EmbeddedResource`, `Image`, `Audio` and friends, on their own, as the items of a `list`, `tuple` or `Sequence`, or as the arms of a union) are opted out for you: they are for the model to read, so auto-detection derives no schema from them (**[Images, audio & icons](media.md)** shows a tool returning each of them). `structured_output=True` still forces one for the content-block classes.
 
 ## A class without type hints
 

docs_src/media/tutorial005.py

@@ -0,0 +1,18 @@
+from mcp.server import MCPServer
+from mcp.types import EmbeddedResource, TextResourceContents
+
+mcp = MCPServer("Brand kit")
+
+
+@mcp.resource("brand://guidelines", mime_type="text/markdown")
+def guidelines() -> str:
+    """How to use the brand assets."""
+    return "# Brand guidelines\n\nUse the primary colour for calls to action.\n"
+
+
+@mcp.tool()
+def brand_guidelines() -> EmbeddedResource:
+    """The brand guidelines as a Markdown document."""
+    return EmbeddedResource(
+        resource=TextResourceContents(uri="brand://guidelines", mime_type="text/markdown", text=guidelines())
+    )

docs_src/media/tutorial006.py

@@ -0,0 +1,40 @@
+from pathlib import Path
+
+from mcp.server import MCPServer
+from mcp.types import Annotations, EmbeddedResource, ResourceLink, TextResourceContents
+
+mcp = MCPServer("Brand kit")
+
+LOGO_FILE = Path(__file__).parent / "logo.png"
+
+
+@mcp.resource("brand://guidelines", mime_type="text/markdown")
+def guidelines() -> str:
+    """How to use the brand assets."""
+    return "# Brand guidelines\n\nUse the primary colour for calls to action.\n"
+
+
+@mcp.resource("brand://logo", mime_type="image/png")
+def logo() -> bytes:
+    """The brand logo as a PNG."""
+    return LOGO_FILE.read_bytes()
+
+
+@mcp.tool()
+def brand_brief() -> list[str | EmbeddedResource | ResourceLink]:
+    """Everything needed to produce on-brand work."""
+    return [
+        "Follow the attached guidelines. The logo is linked; read it if you need the pixels.",
+        EmbeddedResource(
+            resource=TextResourceContents(uri="brand://guidelines", mime_type="text/markdown", text=guidelines()),
+            annotations=Annotations(audience=["assistant"]),
+        ),
+        ResourceLink(
+            name="logo",
+            title="Brand logo",
+            uri="brand://logo",
+            mime_type="image/png",
+            size=LOGO_FILE.stat().st_size,
+            description="Full-colour logo, 2000 by 2000 pixels.",
+        ),
+    ]