Motivation

The MCP spec allows attaching arbitraray metadata to resources, tool responses, etc. This is helpful in some mcp-ui use cases.
One concrete use case is thats some MCP servers want to return the same UI - but sending multiple resources for using in different contexts (for example if it's in a single card, inside of a grid, in a sidebar, etc).
In addition, there might be additional metadata about the resource that the servers would want to convey to the client (for example - possible query params for customizing an iframe, etc)

The Spec Solution

The proper way to convey this kind of information would be to utilize the _meta property, that can be added to individual resources or to the entire tool response:

{
  type: 'resource',
  resource: {
     ... the mcp ui resource
  },
  _meta: {
    'ui-preferred-context': 'sidebar',
    'ui-supported-query-params': ['css', 'preset', 'llmDescription', ...],
    'mcpui.dev/ui-preferred-frame-size': [300, 400],
    ...
  },
}

The Problem

Currently mcp-ui generates the resource itself using createUIResource) - which does not accept metadata. it's possible to "hang" the _meta field after the creation, but that feels "hacky", and we also might want to communicate UI metadata in a standard way that could be picked up on the client side of UIResourceRenderer.

Suggestion

Add a metadata key to the createUIResource(...) call:

const interactiveForm = createUIResource({
  uri: 'ui://user-form/1',
  content: {
    type: 'externalUrl',
    iframeUrl: 'https://yourapp.com'
  },
  encoding: 'text',
  metadata: {
      'preferred-frame-size': [300, 400],
      'preferred-context': 'sidebar'
   },
});

Then it will generate this object:

{
      'mcpui.dev/ui-preferred-frame-size': [300, 400],
      'mcpui.dev/ui-preferred-context': 'sidebar'
}

Note that namespacing is specifically allowed in the spec.

The <UIResourceRenderer> will be able to read and use the mcpui.dev/ui-.... properties as UI hints on the client side.

Questions

1. Do we even want to handle the _meta property? We can leave it to the users to hang it and interpret it themselves
2. If we do - do we want to handle only mcpui.dev/ui-.... properties (we add the prefix and we recognize it on the client side) - or do we want to allow the user to add any arbitrary metadata?
3. How do we handle the metadata on the client side? We can handle things like preferred-frame-size automatically, but for things like "preferred context" the agent would need to access this metadata to choose the best resource to show. Will we add getResourceMetadata(...) function?