Structured Tool Output in MCP

Structured tool output is a way for an MCP tool to return its result as clean JSON data, not only as text. The data goes in a structuredContent field, and an optional outputSchema on the tool says what shape that data will have. Code can then use the result directly, without parsing a paragraph.

Status in the 2026-07-28 spec: core (optional per tool). Structured output was added in 2025-06-18 and loosened in 2026-07-28 so it can carry any JSON value.

This page is based on the "Structured Content" and "Output Schema" sections of the 2026-07-28 Tools page, checked on 28 October 2026.

What structured output is

Every tool result has a content array. That array holds what the spec calls unstructured content: text blocks, images, audio, resource links and embedded resources. It works well when the result is meant for a person or a model to read.

Structured content is different. The spec says it is "returned as a JSON value in the structuredContent field of a result." It is meant for code: a client app, a dashboard, or another program in a workflow.

The spec adds a clarifying note. structuredContent "is server-produced result data and is unrelated to LLM 'structured outputs' (schema-constrained model generation)." The two features share a name but do different jobs.

Why it exists

Before structured output, a tool that returned a temperature had to put it in a sentence. Any client that wanted the number had to parse the text, which breaks easily.

The 2025-06-18 changelog added "support for structured tool output" to fix this. The spec lists the benefits of an output schema: strict validation, type information for programming languages, guidance for clients and models on how to parse results, and better documentation.

How it works

A tool declares an outputSchema. When called, it returns data in structuredContent that conforms to that schema, plus a text copy. Here is the spec's example response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "resultType": "complete",
    "content": [
      {
        "type": "text",
        "text": "{\"temperature\": 22.5, \"conditions\": \"Partly cloudy\", \"humidity\": 65}"
      }
    ],
    "structuredContent": {
      "temperature": 22.5,
      "conditions": "Partly cloudy",
      "humidity": 65
    }
  }
}

The rules are short:

• Servers MUST return structured results that conform to the output schema, if one is provided.
• Clients SHOULD validate structured results against that schema.
• A tool that returns structured content SHOULD also return the serialized JSON in a text block, for backward compatibility.

The output schema itself is covered in MCP tool input and output schemas.

Arrays and other values

The 2026-07-28 spec shows a list_users tool whose output schema is "type": "array". Its structuredContent is a plain array of user objects. The text block holds a readable one-line summary of the two users, not the raw JSON. That example shows the text copy does not have to be raw JSON.

Structured output and state handles

The spec's guidance on stateful tools uses structured output too. A create_basket tool returns { "basket_id": "bsk_a1b2c3" } in structuredContent. Later calls pass that ID as an argument. This is how servers keep state now that the protocol has no sessions, as explained in why MCP became stateless.

What changed across spec versions

The 2026-07-28 change matters for list-style tools. Before, a server had to wrap an array in an object, such as { "users": [...] }. Now it can return the array directly. Older clients may still expect an object, so check your client support before you switch.

Every result in 2026-07-28 also carries resultType: "complete". A tool that needs user input first returns input_required instead, and only the final result carries the structured data. See multi-round-trip requests.

Common mistakes

1. Dropping the text copy. Clients that do not read structuredContent will see nothing useful. The spec says SHOULD for a reason.
2. Returning data that does not match the schema. That breaks a MUST rule, and validating clients may reject the result.
3. Confusing it with model structured outputs. The spec calls them unrelated. Structured tool output is data your server produces, not a constraint on what the model writes.
4. Putting errors in structuredContent alone. Errors belong in a result with isError: true and a readable message, so the model can recover. See how MCP servers report tool errors.
5. Using arrays without checking clients. Root-level arrays are new in 2026-07-28. A client built for 2025-11-25 may not accept them.

For a broader look at result formats, see MCP content types.

Next step

Structured output covers the happy path. Read how MCP servers report tool errors to handle the rest, or go back to the MCP specification reference.

Frequently asked questions