Skip to content
Back to blog

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:

contentstructuredContent
HoldsBlocks of text, images, audio, or resourcesOne JSON value
SuitsText for people and models to readCode: clients, agents, and UI that need fields
DescribedNot described ahead of timeBy the tool's outputSchema
ValidatedNoAgainst 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:

src/tools/get-weather.ts

The client receives both forms:

JSON

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:

src/tools/list-forecast.ts

Returning the array is shorthand for { structuredContent: array }. The same works for a primitive:

src/tools/count-alerts.ts

And for a result with more than one shape, such as found or not found:

src/tools/find-station.ts
TooloutputSchemastructuredContent
get-weatherA map of Zod fields{"city":"Rosario", ...}
list-forecastz.array(z.object(...))[{"day":"Mon","high":24,"low":15}, ...]
count-alertsz.number().int().min(0)2
find-stationz.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 call2026-07-28 client2025-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:

client.mjs

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:

Shell

In another terminal:

Shell

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

One framework to rule them all