Salesforce’s Headless Experience Layer brings widgets to MCP clients

An agent retrieves customer reviews from Salesforce. It has the right data, but returns a paragraph when the user needs a scannable card. Salesforce’s October 7 walkthrough of Headless Experience Layer (HXL) addresses that presentation problem: define a widget once, then bind it to an Agentforce action or an MCP tool for clients that support MCP Apps. HXL is in beta. The useful question for builders is not whether every chat window suddenly supports Salesforce UI. It is what has to line up for the card to render in each one.

The same widget, different output envelopes

HXL widgets are declarative JSON, not Lightning Web Components or React applications. A widget defines a tree of UI components and references attributes supplied by an action. A Custom Lightning Type (CLT) describes the data shape and maps the action’s output fields onto those attributes. The widget itself does not fetch data or calculate a rating; the action must supply display-ready values.

Salesforce’s example uses a fictional food-delivery app called Pronto. An Apex action returns a review count, an average rating, and individual reviews. The widget arranges those values into a card. In Agentforce, the CLT is typed to the Apex output; Agent Script names the CLT and marks the action output as displayable.

The MCP path needs more wiring. The MCP tool wraps the action output with fields such as actionName, isSuccess, and outputValues. Salesforce uses two nested CLTs for that shape: an inner type for the action response and an outer type for the MCP envelope. The outer type’s renderer maps into the same widget, but its binding paths go through outputValues. The MCP server then publishes a UI resource and points the tool at it. A client that supports MCP Apps can follow that resource and render the card.

This is a concrete instance of the MCP Apps extension: tool output can include an interactive interface, provided the host supports the extension. It is not a claim that ordinary MCP tool support automatically includes UI rendering. Host support varies, and Salesforce’s beta currently lists sendMessage and openLink as supported client actions for HXL widget interaction.

Where the boundaries still are

Salesforce’s pitch is “write once, render anywhere,” but the walkthrough describes different channel-specific bindings for Agentforce and MCP. The reusable part is the widget definition. The output contract and setup are not identical. If you change the Apex response shape, check both CLT mappings before calling the result portable.

Security needs the same precision. Salesforce says the widget displays only what the action returns, so the action’s sharing and field-level security checks matter. A card is not a new authorization layer. Neither the UI resource nor the fact that a client rendered it proves a user was entitled to every value in the tool response. Keep read and write permissions on the underlying action, and test them with accounts that have different access.

There is also a product-scope limit. HXL is a beta requiring an org setting and beta terms; Salesforce specifies API version 67.0 or later for the project. Its article names Claude and ChatGPT as MCP Apps-capable clients, but builders should still verify the exact target client and version they intend to support. A text response is a useful fallback if the client cannot render the resource.

A sensible test before rollout

Start with a read-only action returning a small, fixed shape. Build the widget and schema, and preview the layout in Salesforce’s HXL Playground. The Playground is a design aid, not a deployment test. Then try the same action in Agentforce and through a supported MCP client, checking that both show the same fields and that a restricted user cannot see a field they should not receive.

After that, change one field in the action response. Does validation catch a broken widget binding? Does the Agentforce card still render while the MCP version fails because the outer CLT points to an old path? Test a follow-up turn as well: Salesforce reports that its sample may render a card on the first question but answer in text later in the conversation. A successful first turn is not proof of consistent presentation.

Teams can browse the Salesforce Headless 360 MCP Server listing to understand Salesforce’s hosted MCP entry point, and use our MCP server evaluation guide for the connection and permission checks. The directory listing is not a compatibility test for HXL; widget rendering still needs verification in the actual org and client.

FAQ

Do all MCP clients show HXL widgets?

No. The client must support MCP Apps, and the Salesforce HXL beta must be enabled and configured. An MCP connection alone can return tool data without displaying a widget.

Can a widget fetch extra Salesforce data on its own?

No. In Salesforce’s described pattern, the action supplies values matching the CLT, and the widget presents them. Put data access, calculations, and permission checks in the action.

Is HXL a way to replace a full web app?

Not on the evidence of this beta. It is a way to present action results as interactive cards across supported agent surfaces. Test the supported components, client actions, accessibility, and fallback behavior against your actual workflow before replacing an existing interface.