MCP structured output: outputSchema and structuredContent explained
How MCP tools return typed data: declare an outputSchema, return structuredContent, and let clients read results without parsing text. Covers arrays, primitives, and unions in MCP 2026-07-28.
An MCP tool returns structured output by declaring an outputSchema and putting its data in the result's structuredContent field. The schema is published in tools/list, so a client knows the shape before it calls the tool, and the data arrives as JSON it can use directly. Since MCP 2026-07-28, structuredContent can be any JSON value, not only an object.
This guide follows the repository's structured output example.
What is the difference between content and structuredContent?
A tool result has two places for data, with different readers:
content | structuredContent | |
|---|---|---|
| Holds | Blocks of text, images, audio, or resources | One JSON value |
| Suits | Text for people and models to read | Code: clients, agents, and UI that need fields |
| Described | Not described ahead of time | By the tool's outputSchema |
| Validated | No | Against outputSchema when one is declared |
Return both when you can. With xmcp you return the data once: when structuredContent has no content next to it, xmcp adds a text block with the same data as a JSON string, so clients that only read text still get the result.
How do I return an object?
Export an outputSchema as a map of Zod fields and return the data under structuredContent:
The client receives both forms:
If the data does not match the schema, the call fails. Undeclared keys are rejected too, so the schema stays an accurate description of what the tool returns.
How do I return an array, a number, or a union?
Use a complete Zod schema as the outputSchema. A complete schema can describe any JSON value, and a tool that has one can return its data directly:
Returning the array is shorthand for { structuredContent: array }. The same works for a primitive:
And for a result with more than one shape, such as found or not found:
| Tool | outputSchema | structuredContent |
|---|---|---|
get-weather | A map of Zod fields | {"city":"Rosario", ...} |
list-forecast | z.array(z.object(...)) | [{"day":"Mon","high":24,"low":15}, ...] |
count-alerts | z.number().int().min(0) | 2 |
find-station | z.union([...]) | {"found":true, ...} or {"found":false} |
What do older clients receive?
Before 2026-07-28, structuredContent had to be an object. For clients on earlier revisions, the MCP SDK wraps other values under a result key, in the published schema and in the result:
| Tool call | 2026-07-28 client | 2025-11-25 client |
|---|---|---|
count-alerts | "structuredContent": 2 | "structuredContent": {"result": 2} |
You write the tool once. The wrapping happens per request, based on the protocol version the client sent.
How does a client read structured output?
Call the tool and use structuredContent. With xmcp/client:
There is no JSON to parse out of a text block. See How to call an MCP server from TypeScript for the client API.
Run the example
Use Node.js 22.12 or later and pnpm. From a checkout of the xmcp repository:
In another terminal:
It prints one line per forecast day. The example's README has curl requests for both protocol revisions.
Common questions
Is outputSchema required to return structuredContent?
No. structuredContent works without a schema. Declare outputSchema when you want clients to know the shape in advance and want the server to validate what it returns.
Should I still return text content?
Yes, for clients that only render content. xmcp generates it when you return only structured data, so you do not have to write both.
Can structuredContent be an array?
Yes, since MCP 2026-07-28. It can be any JSON value: an object, an array, a string, a number, a boolean, or null. Clients on earlier revisions receive non-object values wrapped as { "result": value }.
What happens when the output does not match the schema?
The call fails with an error instead of returning the data. The schema is enforced on the server, so a client never receives data that breaks the contract the tool published.
Can xmcp infer the output schema from my TypeScript types?
No. Schema inference covers tool inputs. Output schemas are declared with Zod.
Next steps
- Tools reference for every return format.
- MCP 2026-07-28: what changed for the rest of the revision.
