feat: capability-based widget rendering using MCP Apps client negotiation

[jirispilka]

Problem

Widget rendering is currently gated behind a server-side ui=openai URL parameter. This is wrong for two reasons:

1. It's not spec-compliant — MCP Apps (SEP-1865) defines a proper capability negotiation mechanism: clients advertise io.modelcontextprotocol/ui in their capabilities during initialize, and servers should use this to decide whether to expose widget metadata.
2. It couples widget support to a proprietary mode — any client that wants widgets has to know to pass ui=openai, which is an Apify-specific convention, not a standard.

What should happen

During the MCP initialize handshake, the server should inspect the client's capabilities. If the client supports text/html;profile=mcp-app (MCP Apps), expose widget metadata (_meta.ui.*) in tool definitions. If not, serve text-only responses — no widget metadata, no resource URIs.

This is already partially scaffolded (see res/TODO-mcp-apps-migration.md) but the capability flag is currently informational only.

Additional consideration: opt-out switch

Even when a client supports MCP Apps, it may be useful to allow disabling widgets:

• Users who prefer plain text responses
• Testing scenarios where widget rendering gets in the way
• Debugging to isolate issues

A query parameter mcp-apps=off would let anyone explicitly opt out of widget rendering regardless of client capabilities.

Internal repo impact

This change will require updates in apify-mcp-server-internal — the hosted server passes ui=openai today and will need to be updated to align with the new capability-based approach.

Related

• Client-side changes for MCP Apps #535 (client migration to MCP Apps SDK)
• res/TODO-mcp-apps-migration.md — "Mode decoupling" section

[jirispilka]

@MQ37 what do you think about this proposal?

[MQ37]

Once the widgets are polished we can add this capability-based logic to automatically enable the widgets unless explicitly disabled. Since we are already going to use ?ui=true (and ?ui=openai for backwards compat) I would be for ?ui=false query param to explicitly disable the widget rendering and for the CLI I would use --ui off or --ui-off. Whad do you think? @jirispilka