MCP structuredContent: content vs _meta

MCP Apps SDK MCP App tool results have three data channels. Pick the channel based on who should read the data.

Field	Read by	Use it for
`content`	Model, host, View, text-only clients	Short readable summaries, errors, and fallback output.
`structuredContent`	Model, host, View, typed clients	JSON the model may reason over and the View can render.
`_meta`	Host and View only	IDs, traces, cache hints, large lookup maps, and data the model should not see.

structuredContent is not private. If the model should not see a field, put that field in _meta or fetch it later through an app-only tool.

JSON Values and Protocol Versions

The allowed structuredContent shape depends on the protocol surface:

Surface	Allowed shape
Core MCP `2025-11-25` tool result	JSON object
Core MCP `2026-07-28` tool result	Any JSON value: object, array, string, number, boolean, or null
MCP Apps SDK 2.0 `ontoolresult`	`unknown`, because it can carry any current core tool result value
MCP Apps `updateModelContext()`	JSON object (`Record<string, unknown>`)
sunpeak convention-based `outputSchema` export	Zod raw shape, wrapped in `z.object()` by the framework

For an app that must work across both core MCP revisions, keep tool result data object-shaped. If a modern-only server returns an array, scalar, or null, declare an outputSchema with that exact root type and make sure every client and Host supports core MCP 2026-07-28.

Current sunpeak HTTP server wrappers use the SDK 2.0 legacy compatibility transport. They wrap non-object tool result values as { result: value } on a 2025-11-25 connection. sunpeak’s file-based outputSchema export is also an object shape. Return an object when you want the same View data shape on legacy and modern connections.

This tool result rule does not change updateModelContext(). Its structuredContent field remains an object in the MCP Apps 2026-01-26 protocol.

Recommended Shape

Return content and structuredContent from model-visible UI tools:

return {
  content: [{ type: 'text', text: 'Found 12 matching orders.' }],
  structuredContent: {
    orders: orders.map((order) => ({
      id: order.id,
      status: order.status,
      total: order.total,
    })),
    nextCursor,
  },
  _meta: {
    traceId,
    ordersById: Object.fromEntries(orders.map((order) => [order.id, order])),
  },
};

The model can answer from the summary and typed fields. The View can render without parsing text. The full lookup map stays out of model context.

What Goes Where

Put summaries in `content`

Use content for the shortest useful text answer:

What happened.
Counts, statuses, totals, or selected identifiers.
Recoverable error messages.
A text fallback for hosts that do not render MCP Apps.

Avoid dumping large tables or raw JSON into content. It makes the conversation harder for the model and the user to scan.

Put model-safe UI data in `structuredContent`

Use structuredContent for JSON that the View renders and the model may read:

Cards, rows, chart series, map markers, media metadata, and form defaults.
IDs and cursors the model may refer to later.
State that should match an outputSchema.

If the data is sensitive, too large, or not useful to the model, do not put it here. When you consume structuredContent, validate its shape or check whether the field exists. Do not use a truthy check because false, 0, an empty string, and null can be valid modern results.

Put component-only data in `_meta`

Use _meta for data that should reach the iframe but not the model:

Trace IDs, request IDs, cache keys, and feature flags.
Large dictionaries that help the View render details on demand.
Raw records when structuredContent contains a redacted or summarized shape.

Do not put facts the model needs in _meta. The model should be able to answer the next user turn from content, structuredContent, and any later updateModelContext calls.

App-only Helper Tools

App-only tools still return normal MCP tool results. Set _meta.ui.visibility: ["app"] on the tool so the model cannot call it directly, then return the data the View needs.

registerAppTool(
  server,
  'load-order-detail',
  {
    description: 'Load private order detail for the current app view.',
    inputSchema: z.object({ orderId: z.string() }),
    _meta: { ui: { visibility: ['app'] } },
  },
  async ({ orderId }) => {
    const detail = await loadOrderDetail(orderId);

    return {
      content: [{ type: 'text', text: 'Loaded order detail.' }],
      structuredContent: { orderId, status: detail.status },
      _meta: { detail },
    };
  }
);

Use this pattern when the View needs extra data after the initial render, but the model does not need that full payload.

Common Mistakes

Mistake	Why it breaks	Fix
Only returning `structuredContent`	Text-only clients have no readable fallback.	Add a short `content` text block.
Putting all UI data in `content`	The View has to parse prose or JSON text.	Put typed data in `structuredContent`.
Treating `structuredContent` as private	The model may read it.	Move private fields to `_meta`.
Testing `structuredContent` by truthiness	Valid values such as `false`, `0`, and `null` look absent.	Validate against `outputSchema` or check whether the field exists.
Returning a non-object through a legacy connection	Core MCP `2025-11-25` only supports object-shaped structured results.	Wrap the value in an object or require core MCP `2026-07-28`.
Hiding answer-critical facts in `_meta`	The model cannot rely on component-only data.	Put model-needed facts in `content` or `structuredContent`.
Omitting `outputSchema`	Clients cannot validate the typed result shape.	Add `outputSchema` for structured UI payloads.

For schema library requirements, runtime validation behavior, and examples for server and app-side tools, see MCP App inputSchema and outputSchema Validation.

Tool Results and Model Context

Keep model context in sync after the View changes.

Tool and Resource Contract

Check the full server-side MCP App contract.

Add a UI to an MCP Tool

Convert a normal MCP tool into a UI-rendering app.

Tool _meta

Link tools to Views and control tool visibility.

Core MCP 2026 Tool Results

Read the current structured content and output schema requirements.

Tool Schemas

Define and validate inputSchema and outputSchema contracts.

Overview

App

MCP

React

Server

Styling

Types

MCP structuredContent: content vs _meta

JSON Values and Protocol Versions

Recommended Shape

What Goes Where

Put summaries in `content`

Put model-safe UI data in `structuredContent`

Put component-only data in `_meta`

App-only Helper Tools

Common Mistakes

Tool Results and Model Context

Tool and Resource Contract

Add a UI to an MCP Tool

Tool _meta

Core MCP 2026 Tool Results

Tool Schemas

​JSON Values and Protocol Versions

​Recommended Shape

​What Goes Where

​Put summaries in content

​Put model-safe UI data in structuredContent

​Put component-only data in _meta

​App-only Helper Tools

​Common Mistakes

​Related

Tool Results and Model Context

Tool and Resource Contract

Add a UI to an MCP Tool

Tool _meta

Core MCP 2026 Tool Results

Tool Schemas

JSON Values and Protocol Versions

Recommended Shape

What Goes Where

Put summaries in `content`

Put model-safe UI data in `structuredContent`

Put component-only data in `_meta`

App-only Helper Tools

Common Mistakes

Related