Render MCP Apps in Claude threads through Claude Code's control channel

[broomva]

Problem

MCP Apps render only in Codex threads. CodexAdapterV2 implements ProviderAdapterV2McpApps; ClaudeAdapterV2 does not. So in a Claude thread, a tool that declares _meta.ui.resourceUri shows up as a plain tool row, and the app never appears.

Why it's small now

Claude Code already exposes everything the interface needs, through its own control channel. That means T3 doesn't need a second MCP client:

• mcpServerStatus() returns each tool's _meta.ui (resourceUri, visibility).
• readMcpResource(server, uri) reads ui:// documents. The SDK documents it as being for hosts that render MCP Apps.
• The mcp_call control request with result_not_for_model: true runs a tool without a model turn. The CLI advertises it as mcp_call_result_not_for_model_v1.

One gap remains: the SDK has no public method for mcp_call, so the branch sends it through the query's request() channel. A public SDK method would remove that.

The change

Branch: https://github.com/broomva/t3code/tree/claude-mcp-apps (2 commits on 729924af29, 7 files)

• ClaudeAdapterV2 implements mcpApps (listTools, callTool, readResource) against the live query.
• Capture. When an MCP tool call completes and its tool declares a ui:// resource, the adapter saves the document with snapshotMcpApp, as Codex does. The row's toolName becomes server.tool, so the existing web and mobile clients match the app reference unchanged.
• Names and metadata:
  • Tool names are mapped back from Claude's normalised form (cad.view → mcp__bits-and-bolts__cad_view).
  • readOnly is reported as readOnlyHint.
  • inputSchema defaults to { "type": "object" }, because mcp_status omits schemas and apps read hostContext.toolInfo.tool.
• Bumps @anthropic-ai/claude-agent-sdk to ^0.3.303.
• Failure handling. If capture fails, the row stays a plain tool row. Capture times out after 20 s. New session-query methods are optional, so sessions without them behave as today.

Verification

• Typecheck. tsc-rs --noEmit for apps/server is clean.
• Tests:
  • A new adapter test covers capture, callTool and readResource, plus unit tests for the name and metadata mapping.
  • Breaking the capture or naming logic in four different ways makes each of those tests fail.
• Suites. Claude, Codex and mcpApps pass 474/475. The one failure (moves the root's foreground subagents to the background before a steer) times out the same way on unpatched main with the original SDK.
• Live. I ran the dev server with a Claude Sonnet 5.5 thread and openai/mcp-extensions bits-and-bolts:
  • cad.library and cad.view render.
  • The app's own cad.savePreviews calls go through T3's confirmation and write to the server's catalog.

Not covered yet

• MCP calls made inside subagents. Capture skips child threads.
• The iOS client. It should work, since mobile renders saved app references, but I haven't tried it.

Question

Would you take this as a PR? I'm happy to adjust the scope, for example to rely only on capability detection, or to drop the request() path until the SDK exposes mcp_call.

[CouchRiv]

I carried this forward on current main as draft #28739 and would like a maintainer decision on direction and scope.

What has changed since this was proposed: @anthropic-ai/claude-agent-sdk 0.3.280 added Query.readMcpResource() and the tools' _meta.ui in mcpServerStatus(), which removes the blocker #16236 named ("Claude's SDK has no resource read yet"). Following that PR's contract, the draft implements the three mcpApps methods and the capture in ClaudeAdapterV2 the same way CodexAdapterV2 does: the row stays running past the turn's end until the page is stored, plain-row fallback on any failure, interrupt and process exit handled, tests in the wake harness, and a real Haiku run with before/after captures.

Two choices only maintainers can make:

1. App-initiated tool calls. The SDK types the mcp_call control request (with result_not_for_model) but has no public method for it yet (Typed SDK surface for out-of-band MCP tool calls / resources (MCP Apps support) anthropics/claude-agent-sdk-typescript#380). The draft sends it through the query's request channel in one place, and T3 asks before every app tool call in Claude threads because mcp_call skips Claude Code's permission rules. The alternative is to wait for T3code/opencode provider model favorites menu #380.
2. Announcing the host. Claude Code only announces io.modelcontextprotocol/ui to MCP servers when CLAUDE_CODE_MCP_APPS_HOST=1 is set, and that variable is not documented. Without it, many servers do not attach their apps. Announcing it without working app tool calls would break servers that defer writes to an app form (fix(server): MCP App forms now show when a write tool defers to them #23850), which is why the draft ships both together.

Would you take #28739 with those two choices, or prefer render-only until #380 lands? Credit to @broomva for the original design.