Skip to main content

transports.mcp_ui

MCP-UI protocol adapter.

Implements the MCP-UI (Model Context Protocol UI) for agent-runtimes using the Python mcp-ui-server SDK.

Protocol Reference: https://mcpui.dev

MCP-UI provides:

  • Interactive UI resources in agent responses
  • Support for HTML, external URLs, and Remote DOM content
  • Secure sandboxed iframe execution
  • Two-way communication between UI and host
  • Flexible metadata for UI customization
  • Identity context support for OAuth token propagation

MCPUITransport Objects​

class MCPUITransport(BaseTransport)

MCP-UI protocol adapter.

Wraps agent responses to include interactive UI resources using the MCP-UI protocol standard.

The adapter allows agents to return rich, interactive UI components that can be rendered in the client application using the @mcp-ui/client React components or web components.

Example:

```python
from agent_runtimes.agents import PydanticAIAgent
from agent_runtimes.transports import MCPUITransport

agent = PydanticAIAgent(...)
adapter = MCPUITransport(agent)

# Agent can return UI resources in responses
response = await adapter.handle_request({
    "message": "Show me a dashboard",
    "session_id": "session-123"
})

# Response will include UIResource objects that can be rendered
# using <UIResourceRenderer /> from @mcp-ui/client
```

__init__​

def __init__(agent: BaseAgent,
             enable_ui_transforms: bool = True,
             default_frame_size: tuple[str, str] | None = None)

Initialize the MCP-UI adapter.

Arguments:

  • agent - The agent to adapt.
  • enable_ui_transforms - Whether to automatically transform agent responses into UI resources when appropriate.
  • default_frame_size - Default iframe dimensions as CSS strings, e.g., ("800px", "600px") or ("100%", "80vh").

protocol_name​

@property
def protocol_name() -> str

Get the protocol name.

create_html_resource​

def create_html_resource(
        uri: str,
        html: str,
        metadata: dict[str, Any] | None = None,
        frame_size: tuple[str, str] | None = None) -> UIResource

Create an HTML UI resource.

Arguments:

  • uri - Resource URI (must start with 'ui://').
  • html - HTML content string.
  • metadata - Optional metadata dictionary.
  • frame_size - Optional frame size override (width, height).

Returns:

UIResource ready to include in agent responses.

create_external_url_resource​

def create_external_url_resource(
        uri: str,
        url: str,
        metadata: dict[str, Any] | None = None,
        frame_size: tuple[str, str] | None = None) -> UIResource

Create an external URL UI resource.

Arguments:

  • uri - Resource URI (must start with 'ui://').
  • url - External URL to display in iframe.
  • metadata - Optional metadata dictionary.
  • frame_size - Optional frame size override (width, height).

Returns:

UIResource ready to include in agent responses.

create_remote_dom_resource​

def create_remote_dom_resource(
        uri: str,
        script: str,
        framework: str = "react",
        metadata: dict[str, Any] | None = None,
        frame_size: tuple[str, str] | None = None) -> UIResource

Create a Remote DOM UI resource.

Arguments:

  • uri - Resource URI (must start with 'ui://').
  • script - JavaScript code defining the UI.
  • framework - Framework to use ('react' or 'webcomponents').
  • metadata - Optional metadata dictionary.
  • frame_size - Optional frame size override (width, height).

Returns:

UIResource ready to include in agent responses.

handle_request​

async def handle_request(request: dict[str, Any]) -> dict[str, Any]

Handle an MCP-UI request.

Processes the request through the agent and optionally transforms the response to include UI resources.

Arguments:

  • request - Request data containing:
    • message: User message
    • session_id: Optional session identifier
    • ui_options: Optional UI configuration
    • identities: Optional OAuth identities (list of {provider, accessToken})

Returns:

Response with potential UI resources in the content array.

handle_stream​

async def handle_stream(
        request: dict[str, Any]) -> AsyncIterator[dict[str, Any]]

Handle a streaming MCP-UI request.

Streams agent responses and UI resources as they become available.

Arguments:

  • request - Request data with optional identities key for OAuth tokens.

    Yields​

    dict[str, Any] Stream events with text deltas and UI resources.

initialize​

async def initialize() -> None

Initialize the adapter.