Why is MCP structuredContent missing even though the tool call succeeded?

Capture the raw tools/call result first. If structuredContent is present on the wire but absent from the model or UI, the loss is in the client, bridge or transcription layer rather than the MCP server. Current client issue reports document this class of failure.

What happens when an MCP tool declares outputSchema?

If outputSchema is defined, the server MUST return structured content that conforms to that schema and clients SHOULD validate the result against it.

Can MCP 2026-07-28 structuredContent be an array or scalar?

Yes. MCP 2026-07-28 allows structuredContent to be any JSON value, including arrays and scalar values, so older clients that assume an object root can create compatibility failures.

Editorial

Research guide · MCP tool results · 13 September 2026

MCP structuredContent missing: debug outputSchema and empty tool results

Q: Should an MCP tool return both content and structuredContent?

The MCP tools specification says that for backwards compatibility a tool returning structured content SHOULD also return the serialized JSON in a TextContent block. This is a compatibility recommendation, not a requirement to duplicate every result in every implementation.

An MCP tool can complete successfully while the model still sees an empty result, only one output channel, or a schema error. The fastest way to debug that is to separate what the server returned on the wire from what the client, bridge and model actually received.

Published 13 September 2026 · sources checked 13 September 2026

structuredContent

Machine-readable tool result channel

outputSchema

Optional declared JSON Schema for the result

SHOULD

Spec guidance to mirror structured JSON into TextContent for backwards compatibility

2026-07-28

Revision that permits any JSON value, not only an object root

Protocol boundary

What MCP actually requires from structured tool output

MCP tools can declare an optional outputSchema and return a machine-readable structuredContent value. Under the current tools specification, when an output schema is declared the server MUST return structured content that conforms to it, and clients SHOULD validate that result.

The same specification gives an important compatibility rule: when a tool returns structured content it SHOULD also return the serialized JSON in a TextContent block for backwards compatibility. That is not a mandate to duplicate arbitrary prose. It is a practical way to keep older or lossy clients from turning a valid structured result into an apparently empty tool call.

MCP 2026-07-28 also widened structured results beyond object roots. structuredContent can now be any JSON value, including arrays and scalars. If an older client silently assumes every structured result is an object, an otherwise valid current server can appear broken.

Fast diagnosis

Find the layer where the result disappeared

Observed signal	Likely boundary	First action
Raw response has no structuredContent	Server or server-SDK serialization boundary	Inspect the actual tools/call result before changing the client.
Raw response has structuredContent; model cannot see it	Client, bridge or model-transcription boundary	Compare raw transport evidence with the model-visible function result.
content is visible; structuredContent disappears	Client strips or ignores the structured field	Test the same server with a second client before changing the schema.
structuredContent is visible; content disappears	Client prefers/transcribes one result channel	Keep the two channels semantically consistent and isolate the client behavior.
Array/scalar result fails but object works	Older object-only assumption	Verify the negotiated revision and test a current 2026-07-28 implementation.
outputSchema validation fails	Declared schema and returned structured value disagree	Validate the exact returned JSON value against the published outputSchema.

Ten-minute probe

Test content-only, structured-only and both with fresh markers

1. Generate a unique marker inside the tool call. Do not put the marker in the prompt or tool definition; you want proof that the returned value crossed the result boundary.
2. Return text only. Put the marker in a normal TextContent block and record whether the model can repeat it exactly.
3. Return structured content only. Put the marker only in structuredContent and record both the raw JSON-RPC result and what the model receives.
4. Return both channels. Put the same payload in structuredContent and serialized JSON text. If this works while structured-only fails, you have a compatibility signal rather than proof that the server schema is wrong.
5. Compare transport to transcription. Save the exact server response and the client/model-visible tool result. That comparison tells you whether data disappeared before or after the MCP transport boundary.
6. Repeat with an array or scalar if relevant. A 2026-07-28 client should not require every structured result to be an object unless your tool's own output schema says so.

Compatibility pattern

Return one semantic result through two compatible channels

When broad client compatibility matters, keep the structured value authoritative and mirror the same information as serialized JSON text. That follows the specification's backwards-compatibility recommendation and makes client-side field loss easier to detect.

const payload = { orderId: "ord_123", status: "ready" };

return {
  content: [{ type: "text", text: JSON.stringify(payload) }],
  structuredContent: payload,
};

If you declare outputSchema, validate payload against that exact schema in tests. Do not use the text mirror to hide a structured result that violates the contract.

Current implementation evidence

Fresh client bugs show both directions of result loss

An open Antigravity issue filed on 6 September 2026 reports a 2026-07-28 MCP tool whose structuredContent-only result reached the raw server response but was unavailable to the model; text-only and results containing both fields worked in the reporter's reproduction. That is client-specific evidence, not a new protocol rule.

An open Codex issue filed on 13 August 2026 reports the opposite-looking transcription failure: a tool returned both content and structuredContent, but the app-side function output exposed the structured object and dropped the text block. Direct stdio evidence in the report showed the server had returned both fields.

Together these reports make one diagnostic principle especially valuable: never infer what the server sent from what the model saw. Capture both sides of the boundary before rewriting your tool result contract.

Avoid false fixes

Do not weaken a valid contract to accommodate an unidentified client bug

Do not remove outputSchema just to make an error disappear. First determine whether the returned value actually violates the schema or the client mishandles a valid result.
Do not treat transport success as model visibility. A successful tools/call proves the call completed, not that every result field survived the client pipeline.
Do not fork semantics between content and structuredContent. If both carry the same result, keep them consistent so a client choosing either channel does not change the meaning.
Do not assume object-only structured output on 2026-07-28. Arrays and scalar JSON values are valid when allowed by the tool's schema.

Next checks

Once tool output is visible, verify the rest of the MCP path

Transport

Fix HeaderMismatch and Mcp-Param failures

Trust

Verify an MCP server before connecting

Authorization

Troubleshoot MCP OAuth 401/403

Machine API

Inspect zFinia's machine-service catalogue

Sources

Model Context Protocol 2026-07-28 — Tools — outputSchema, structuredContent, backwards-compatible TextContent mirroring and non-object structured values.
google-antigravity/antigravity-cli #953 — structured-only tool-result visibility report, opened 6 September 2026.
openai/codex #38287 — content/structuredContent transcription report, opened 13 August 2026.