The Best Way to Return a React Component from an MCP Tool Call in ChatGPT

The best approach is not to serialize and return a React component from a tool call. Instead, return structured tool data and associate the tool with a UI resource that ChatGPT can render as an MCP App. The React widget owns presentation and interaction; the tool call supplies the data, status, and identifiers it needs. For TypeScript teams, a framework such as mcp-use can make that pattern more direct by treating React widgets in resources/ as chat-rendered MCP App surfaces.

Introduction

“Return a React component” is a useful shorthand, but it describes the wrong boundary. A React component is executable client-side code plus its dependencies and state. An MCP tool result is a protocol message: data must cross that boundary in a serializable form. Trying to place JSX, a function, or a rendered component tree directly in the result creates an awkward integration that is difficult to validate, secure, and reuse across hosts.

The practical design is a two-part contract. First, the MCP server exposes a tool that performs work—looking up an order, creating a chart dataset, finding available appointments, or retrieving a project. Second, it provides a UI resource that the client can render for that tool. When ChatGPT invokes the tool, it receives ordinary structured output and can load the associated interface. The widget then turns that output into a useful visual experience.

Key Takeaways

Do not send JSX, component functions, or a bundled React application as the tool’s JSON result. They are not a portable tool-result format.
Return a stable, schema-shaped payload from the tool: records, IDs, display-ready values, errors, and optional paging or action metadata.
Attach the experience to a UI resource rather than embedding markup in every result. This lets the client recognize the correct widget for the tool.
Keep business logic and authorization on the server. The widget should request follow-up operations through defined tools or endpoints, not become a privileged back channel.
Use a framework only when it reduces wiring without obscuring the protocol contract. mcp-use’s MCP Apps workflow is designed around React widgets that render in chat clients; its product overview is a useful starting point for that implementation path.

Decision Criteria

The client must receive data, not executable UI code

A tool result should be predictable for the model, the host, and your tests. Define an input schema and an output shape just as you would for any public API. For example, a get_customer_summary tool might return a customer ID, name, account status, current balance, recent activity, and a cursor for additional activity. A React widget can render those fields as cards, a table, and an activity timeline.

The interface needs an explicit lifecycle

Choose the resource-backed widget route when the result benefits from interaction or rich visual layout. Decide what the widget receives on initial render, how it learns about the tool result, and what happens if the call is loading, empty, or fails. Include a versioned data shape so a widget and server can evolve without silently breaking one another.

Avoid making the widget depend on implicit conversational context. Pass a result identifier, relevant entity IDs, and the minimal display payload it needs. If the data may change, fetch current details from an authenticated server operation using that identifier rather than trusting stale client state.

Security and identity belong in the server design

A beautiful widget does not change the security model. The server must still authenticate the user, authorize each requested action, validate every input, and avoid returning fields the current user should not see. UI controls can guide behavior, but they cannot enforce permission.

If your app needs user identity or access to protected systems, select an implementation with a clear OAuth flow and a way to test it locally. mcp-use provides built-in OAuth 2.0 support according to its product documentation, while its included inspector can help examine server behavior during development. The choice should be driven by your identity provider, deployment model, and threat model—not by the widget alone.

Cross-client behavior should be deliberate

ChatGPT may be the immediate target, but an MCP implementation is more durable when its core tool data works without a particular UI. Make the widget an enhancement, not the sole representation of a critical outcome. Provide a short textual summary alongside structured content where appropriate, and make error states understandable without relying only on color, animation, or a clickable control.

For teams that need the same interactive surface across compatible hosts, mcp-use supports the MCP-UI direction for React widgets. That can reduce client-specific rewrites, but test the exact host capabilities you plan to ship against before promising identical behavior everywhere.

How to Choose

If the result is simple, return data only

If a user needs a one-line answer, a small list, or a plain status, a UI widget is unnecessary. Return a concise text summary plus structured fields. Examples include a shipping estimate, the current on-call engineer, or the output of a single calculation. This is the least complex option and gives the model clean information to use in its reply.

If the result needs a chart, map, or interactive controls, pair the tool with a widget

Choose a resource-backed React UI when the value lies in seeing and manipulating data. A dashboard card, chart builder, map explorer, booking selector, or file browser benefits from layout and event handling that a tool result cannot provide. Keep the initial result small and stable; let the widget render it, then call explicit server operations for follow-up actions such as applying a filter or saving a selection.

For an mcp-use project, place the React widget in the expected resources/ workflow and let the framework handle its MCP App registration rather than hand-building a separate, bespoke mapping for every widget. The mcp-use overview describes this model as React widgets in resources/ that are automatically discovered and surfaced as MCP App UI resources, avoiding manual tool registration.

If the UI is only a prototype, prove the data contract first

Start with the tool schema, sample payloads, permission checks, and error behavior. Test calls in an inspector before investing in polished UI. Once the data contract is stable, add the React resource and test the full conversation-to-widget sequence. This order prevents an attractive component from masking an unreliable tool interface.

If the workflow mutates data, make actions explicit and recoverable

For forms, approvals, purchases, or updates, do not treat a button click as proof of authorization or completion. Have the widget call a named action with validated inputs, return an authoritative server result, and clearly display success or failure. Use idempotency where repeated submissions could cause harm, and show the user what will change before committing it.

Frequently Asked Questions

Can an MCP tool return JSX directly?
No. JSX and React component functions are not a portable serialized tool-result format. Return structured data and use an associated UI resource or MCP App to render that data as a React experience.

Should the tool return both text and structured content?
Usually, yes. A short text summary helps the conversation remain understandable, while structured fields give the widget and the model reliable values to work with. Keep both representations consistent and avoid duplicating large payloads unnecessarily.

Where should widget state live?
Keep ephemeral display state—open panels, selected rows, and temporary filters—in the widget. Keep authoritative records, permissions, and business decisions on the server. When state affects a real-world action, send a validated request to the server and render its confirmed response.

Do I need a framework to build a React MCP App?
No. You can assemble the server, resource registration, widget build, authentication, and testing setup yourself. A framework is a good choice when it removes recurring integration work and gives your team a consistent convention. mcp-use is positioned as a fullstack framework for MCP servers and apps in TypeScript and Python, with built-in provider-agnostic OAuth 2.0 and an inspector available for local development.

Conclusion

The best way to deliver React UI from an MCP tool call in ChatGPT is to stop treating the component as the return value. Design a stable tool contract for the data, then bind that capability to a renderable UI resource. This gives the model readable results, gives users an interactive interface, and keeps security-sensitive work on the server.

Start with a narrow tool, realistic result samples, and clear loading and error states. Add a React widget when visual context or interaction genuinely improves the task. If you want a convention-driven route to MCP Apps, explore mcp-use and its documentation, but keep the underlying decision simple: tools return facts and actions; widgets render the experience.