Platform MCP Tool Widget Coordinate

Rendering a Custom MCP Tool Output With a Widget

Coordinate two object-based Custom Lightning Types (CLTs) and an HXL widget to render the output of a custom MCP server tool whose implementation is an Apex @InvocableMethod. This skill never authors content directly — it loads and invokes leaf skills in dependency order, gates progress on user approval, and runs validation gates before reporting completion.

Ownership boundary — this skill owns only:

1. the MCP-tool use case — resolving the tool's output shape and orchestrating the leaf skills in the right order; and
2. the envelope CLT's default `renderer.json` — the one artifact it authors inline, bridging the envelope to the widget.

The CLTs are authored by platform-custom-lightning-type-generate, and all widget metadata (schema + body + .uiwidget-meta.xml) is authored and validated by platform-widget-generate. This skill never writes widget metadata and never modifies the Apex class — it supplies each leaf skill its inputs and wires the result together.

Scope

Custom MCP server tools backed by an Apex Invocable Action only. The MCP tool returns the platform's invocable-action result envelope — an object with actionName, isSuccess, and an outputValues node that carries the tool's real payload. To render this envelope with a widget, model it as two object-based CLTs (lightning__objectType) of equal standing — the only reason there are two is that one must reference the other by name (a CLT cannot reference itself), so they need distinct deployed names. Name and describe each by what it actually models — never by an invented role-label pair like "Payload CLT"/"Envelope CLT" or "Inner CLT"/"Outer CLT":

• The CLT that mimics the tool-result envelope, named <toolApiName>. Its outputValues property is typed to the other CLT via c__<responseCLT> (the CLT-reference prefix — see the namespace note below).
• The CLT that is the exact shape of the Invocable Action's response (@InvocableVariable fields on the @InvocableMethod response class), named <toolApiName>Response — "Response" is not an invented role word; it is the word the Apex source itself uses for that class.

The widget grounds on the response fields (flat), and the default `renderer.json` in the envelope CLT bridges the envelope nesting to the flat widget via {!$attrs.outputValues.<field>}.

Namespace prefix provenance (`c__` / `@apexClassType/<ns>__…`): the Actions REST describe returns bare, unprefixed class names (Outer$Inner) and no namespace — the prefix is the org's CLT namespace, added by this skill. It is c__ in a namespace-less org (the common case, used literally throughout this doc) or the package namespace <ns>__ in a packaged org (read from the class's NamespacePrefix; default to c only when the org has none). Every c__ below is this prefix.

Out of scope, route elsewhere:

• Customizing an Apex-backed agent action output (Apex-backed CLT @apexClassType/..., single CLT, surface-specific renderer) → platform-lightning-type-widget-coordinate.
• A standalone widget with no MCP tool / Lightning Type → platform-widget-generate.
• Authoring only a CLT or only an Apex class → platform-custom-lightning-type-generate / platform-apex-generate.

Beta cardinality: the invocable-action result is a bulk array (content[]). For the beta release this skill models and renders a single response — the first element of content[]. The CLT envelope models one result object, not the content[] wrapper.

How this differs from platform-lightning-type-widget-coordinate

Phase Graph

Per-phase pattern: load the skill fresh → execute its workflow → verify outputs → checkpoint before the next phase. Even if you remember a leaf skill's content, skills evolve — always load fresh.

Phase 1 — Input selection

Determine where the payload shape comes from. Prefer the sources top-to-bottom:

Capture the tool API name (used to name all artifacts — see the naming convention below).

Source priority: live/authoritative schema sources beat parsing a local class, which beats a pasted example. In order:

1. `action` if an action API name and an authenticated org are available. The Actions REST API describe is the same schema the platform itself exposes, so it needs no request/helper filtering and gives real field types.
2. `sample` if a runtime JSON sample is pasted (runtime response — explicit and current).
3. `apex` if an Apex class exists locally AND none of the above apply (fallback only — may be stale relative to what's actually deployed behind the action).

If none are available, STOP and ask the user for an action name, a class, a sample, or a schema.

Phase 2 — Payload discovery

FIRST Read references/mcp-tool-output-discovery.md (REQUIRED — do NOT run Phase 2 from this summary alone), then execute the procedure for the chosen source. The reference is authoritative for the full per-source procedures, the field-type mapping tables, and the nested/list handling; the pointers below are only a map to it: