MCP-UI

https://mcpui.dev/
Admin
MCP-UI provides SDKs and components for building rich, interactive user interfaces for AI tools...
Tokens:49,422
Snippets:359
Trust Score:7.2
Update:16 hours ago
Show doc for...
Tokens:
Raw
### Basic Setup: Creating UI Resources with mcp_ui_server

Source: https://mcpui.dev/guide/server/ruby/usage-examples

Shows how to require the gem and create UI resources with direct HTML or external URLs, using text or blob encoding. Includes expected JSON output for each example.

```ruby
require 'mcp_ui_server'
require 'json'

# Example 1: Direct HTML, delivered as text
resource1 = McpUiServer.create_ui_resource(
  uri: 'ui://my-component/instance-1',
  content: { type: :raw_html, htmlString: '<p>Hello World</p>' },
  encoding: :text
)
puts "Resource 1: #{JSON.pretty_generate(resource1)}"
# Output for Resource 1:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://my-component/instance-1",
#     "mimeType": "text/html;profile=mcp-app",
#     "text": "<p>Hello World</p>"
#   }
# }

# Example 2: Direct HTML, delivered as a Base64 blob
resource2 = McpUiServer.create_ui_resource(
  uri: 'ui://my-component/instance-2',
  content: { type: :raw_html, htmlString: '<h1>Complex HTML</h1>' },
  encoding: :blob
)
puts "Resource 2 (blob will be Base64): #{JSON.pretty_generate(resource2)}"
# Output for Resource 2:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://my-component/instance-2",
#     "mimeType": "text/html;profile=mcp-app",
#     "blob": "PGgxPkNvbXBsZXggSFRNTDwvaDE+"
#   }
# }

# Example 3: External URL, text encoding
dashboard_url = 'https://my.analytics.com/dashboard/123'
resource3 = McpUiServer.create_ui_resource(
  uri: 'ui://analytics-dashboard/main',
  content: { type: :external_url, iframeUrl: dashboard_url },
  encoding: :text
)
puts "Resource 3: #{JSON.pretty_generate(resource3)}"
# Output for Resource 3:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://analytics-dashboard/main",
#     "mimeType": "text/html;profile=mcp-app",
#     "text": "https://my.analytics.com/dashboard/123"
#   }
# }

# Example 4: External URL, blob encoding (URL is Base64 encoded)
chart_api_url = 'https://charts.example.com/api?type=pie&data=1,2,3'
resource4 = McpUiServer.create_ui_resource(
  uri: 'ui://live-chart/session-xyz',
  content: { type: :external_url, iframeUrl: chart_api_url },
  encoding: :blob
)
puts "Resource 4 (blob will be Base64 of URL): #{JSON.pretty_generate(resource4)}"
# Output for Resource 4:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://live-chart/session-xyz",
#     "mimeType": "text/html;profile=mcp-app",
#     "blob": "aHR0cHM6Ly9jaGFydHMuZXhhbXBsZS5jb20vYXBpP3R5cGU9cGllJmRhdGE9MSwyLDM="
#   }
# }

# These resource objects would then be included in the 'content' array
# of a toolResult in an MCP interaction.
```

--------------------------------

### Install mcp-ui-server with uv

Source: https://mcpui.dev/guide/server/python/overview

Install the package using uv.

```bash
uv add mcp-ui-server
```

--------------------------------

### Install @mcp-ui/server and @modelcontextprotocol/ext-apps

Source: https://mcpui.dev/guide/server/typescript/usage-examples

Install the required packages for using @mcp-ui/server with the MCP Apps pattern.

```bash
npm i @mcp-ui/server @modelcontextprotocol/ext-apps
```

--------------------------------

### Install dependencies with uv

Source: https://mcpui.dev/guide/server/python/walkthrough

Installs the mcp and mcp-ui-server packages using uv.

```bash
uv add mcp mcp-ui-server
```

--------------------------------

### Install MCP UI client and SDK dependencies

Source: https://mcpui.dev/guide/client/walkthrough

Install the @mcp-ui/client, @modelcontextprotocol/sdk, and @modelcontextprotocol/ext-apps packages.

```bash
npm install @mcp-ui/client @modelcontextprotocol/sdk @modelcontextprotocol/ext-apps
```

--------------------------------

### Install dependencies with bundle install

Source: https://mcpui.dev/guide/server/ruby/walkthrough

Installs the gems defined in the Gemfile.

```sh
bundle install

```

--------------------------------

### Build and start MCP server (mcp-apps-demo)

Source: https://mcpui.dev/guide/client/walkthrough

Run these commands in the mcp-apps-demo directory to build and start the MCP server on port 3001.

```bash
# In the mcp-apps-demo directory
npm run build && npm start
```

--------------------------------

### Start React development server

Source: https://mcpui.dev/guide/client/walkthrough

Run this command to start the React development server for the client application.

```bash
npm run dev
```

--------------------------------

### Install gem with bundle install

Source: https://mcpui.dev/guide/server/ruby/overview

Execute this command to install the gem using Bundler.

```bash
$ bundle install
```

--------------------------------

### Install MCP and mcp-ui dependencies

Source: https://mcpui.dev/guide/server/typescript/walkthrough

Install the Model Context Protocol SDK and the @mcp-ui/server package.

```bash
npm install @modelcontextprotocol/sdk @mcp-ui/server
```

--------------------------------

### Install gem with gem install

Source: https://mcpui.dev/guide/server/ruby/overview

Execute this command to install the gem directly.

```bash
$ gem install mcp_ui_server
```

--------------------------------

### Server (MCP Tool) - Ruby Example

Source: https://mcpui.dev/guide/introduction

Ruby example showing how to create a UI resource using the mcp_ui_server gem's create_ui_resource method and return it in an MCP response.

```ruby
require 'mcp_ui_server'

resource = McpUiServer.create_ui_resource(
  uri: 'ui://my-tool/dashboard',
  content: { type: :raw_html, htmlString: '<h1>Dashboard</h1>' },
  encoding: :text
)

# Return in MCP response
{ content: [resource] }
```

--------------------------------

### Complete MCP App Example with MCP-UI

Source: https://mcpui.dev/guide/mcp-apps

A full example of an MCP app using Express, the MCP SDK, and MCP-UI. It sets up a server, creates a UI resource with raw HTML, registers the resource and a tool, and links the tool to the UI resource via _meta. The example is from the mcp-apps-demo repository.

```typescript
import express from 'express';
import cors from 'cors';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { createUIResource } from '@mcp-ui/server';
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { z } from 'zod';

const app = express();
app.use(cors({ origin: '*', exposedHeaders: ['Mcp-Session-Id'] }));
app.use(express.json());

// ... (transport setup)

const server = new McpServer({ name: 'demo', version: '1.0.0' });

const graphUI = await createUIResource({
  uri: 'ui://demo/graph',
  encoding: 'text',
  content: {
    type: 'rawHtml',
    htmlString: `
      <!DOCTYPE html>
      <html>
      <head>
        <style>
          body { font-family: system-ui; padding: 20px; }
          .data { background: #f5f5f5; padding: 10px; border-radius: 8px; }
        </style>
      </head>
      <body>
        <h1>graph</h1>
        <div class="data" id="data">Waiting for data...</div>
        <button onclick="sendPrompt()">Ask Follow-up</button>

        <script>
          window.addEventListener('message', (e) => {
            if (e.data.type === 'ui-lifecycle-iframe-render-data') {
              document.getElementById('data').textContent =
                JSON.stringify(e.data.payload.renderData, null, 2);
            }
          });

          function sendPrompt() {
            window.parent.postMessage({
              type: 'prompt',
              payload: { prompt: 'Tell me more about this data' }
            }, '*');
          }

          window.parent.postMessage({ type: 'ui-lifecycle-iframe-ready' }, '*');
        </script>
      </body>
      </html>
    `,
  },
});

// Register the UI resource
registerAppResource(
  server,
  'graph_ui',
  graphUI.resource.uri,
  {},
  async () => ({
    contents: [graphUI.resource]
  })
);

// Register the tool with _meta linking to the UI resource
registerAppTool(
  server,
  'show_graph',
  {
    description: 'Display an interactive graph',
    inputSchema: {
      title: z.string().describe('Graph title'),
    },
    // For MCP Apps hosts - points to the registered resource
    _meta: {
      ui: {
        resourceUri: graphUI.resource.uri
      }
    }
  },
  async ({ title }) => {
    // Create embedded resource for MCP-UI hosts
    const embeddedResource = await createUIResource({
      uri: `ui://demo/graph/${encodeURIComponent(title)}`,
      encoding: 'text',
      content: {
        type: 'rawHtml',
        htmlString: `<html><body><h1>Graph: ${title}</h1></body></html>`,
      },
    });

    return {
      content: [
        { type: 'text', text: `Graph: ${title}` },
        embeddedResource  // Included for MCP-UI hosts
      ],
    };
  }
);

// ... (server setup)
```

--------------------------------

### Install Ruby SDK

Source: https://mcpui.dev/guide/getting-started

Install the Ruby SDK using gem. Requires Ruby v3.x.

```bash
gem install mcp_ui_server
```

--------------------------------

### Install dependencies with pip

Source: https://mcpui.dev/guide/server/python/walkthrough

Alternative installation using pip for the same packages.

```bash
pip install mcp mcp-ui-server
```

--------------------------------

### Server (MCP Tool) - TypeScript Example

Source: https://mcpui.dev/guide/introduction

TypeScript example showing how to create a UI resource with createUIResource, register it with registerAppResource, and register a tool with registerAppTool that references the UI resource via _meta.ui.resourceUri.

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { createUIResource } from '@mcp-ui/server';
import { z } from 'zod';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

const dashboardUI = await createUIResource({
  uri: 'ui://my-tool/dashboard',
  content: { type: 'rawHtml', htmlString: '<h1>Dashboard</h1>' },
  encoding: 'text'
});

registerAppResource(server, 'dashboard_ui', dashboardUI.resource.uri, {}, async () => ({
  contents: [dashboardUI.resource]
}));

registerAppTool(server, 'show_dashboard', {
  description: 'Show dashboard',
  inputSchema: {},
  _meta: { ui: { resourceUri: dashboardUI.resource.uri } }
}, async () => {
  return { content: [{ type: 'text', text: 'Dashboard loaded' }] };
});
```

--------------------------------

### Complete iframe example with async handling

Source: https://mcpui.dev/guide/protocol-details

Full HTML/JavaScript example showing how to send async messages with messageId, track pending requests, and handle acknowledgment and response messages. Includes cleanup of pending requests on response.

```html
<button onclick="handleAsyncAction()">Async Action</button>
<div id="status">Ready</div>
<div id="result"></div>

<script>
  let messageCounter = 0;
  const pendingRequests = new Map();

  function generateMessageId() {
    return `msg-${Date.now()}-${++messageCounter}`;
  }

  function handleAsyncAction() {
    const messageId = generateMessageId();
    const statusEl = document.getElementById('status');
    const resultEl = document.getElementById('result');
    
    statusEl.textContent = 'Sending request...';
    
    // Store the request context
    pendingRequests.set(messageId, { 
      startTime: Date.now(),
      action: 'async-tool-call'
    });
    
    // Send the message with messageId
    window.parent.postMessage({
      type: 'tool',
      messageId: messageId,
      payload: { 
        toolName: 'processData', 
        params: { data: 'example data', timestamp: Date.now() }
      }
    }, '*');
  }

  // Listen for responses from the host
  window.addEventListener('message', (event) => {
    const message = event.data;
    
    if (!message.messageId || !pendingRequests.has(message.messageId)) {
      return; // Not for us or unknown request
    }
    
    const statusEl = document.getElementById('status');
    const resultEl = document.getElementById('result');
    const request = pendingRequests.get(message.messageId);
    
    switch (message.type) {
      case 'ui-message-received':
        statusEl.textContent = 'Request acknowledged, processing...';
        break;
        
      case 'ui-message-response':
        if (message.payload.error) {
          statusEl.textContent = 'Error occurred!';
          resultEl.innerHTML = `<div style="color: red;">Error: ${JSON.stringify(message.payload.error)}</div>`;
          pendingRequests.delete(message.messageId);
          break;
        }
        statusEl.textContent = 'Completed successfully!';
        resultEl.innerHTML = `<pre>${JSON.stringify(message.payload.response, null, 2)}</pre>`;
        pendingRequests.delete(message.messageId);
        break;
    }
  });
</script>
```

--------------------------------

### Install Python SDK

Source: https://mcpui.dev/guide/getting-started

Install the Python SDK using pip. Requires Python v3.10+.

```bash
pip install mcp-ui-server
```

--------------------------------

### AppRenderer Quick Example (tsx)

Source: https://mcpui.dev/guide/client/app-renderer

Shows how to use the AppRenderer component with a client, tool name, sandbox URL, and event handlers. The example uses a ref of type AppRendererHandle and passes toolInput, toolResult, and hostContext.

```tsx
import { AppRenderer, type AppRendererHandle } from '@mcp-ui/client';

function ToolUI({ client, toolName, toolInput, toolResult }) {
  const appRef = useRef<AppRendererHandle>(null);

  return (
    <AppRenderer
      ref={appRef}
      client={client}
      toolName={toolName}
      sandbox={{ url: new URL('http://localhost:8765/sandbox_proxy.html') }}
      toolInput={toolInput}
      toolResult={toolResult}
      hostContext={{ theme: 'dark' }}
      onOpenLink={async ({ url }) => {
        window.open(url, '_blank');
        return {};
      }}
      onMessage={async (params) => {
        console.log('Message from tool UI:', params);
        return {};
      }}
      onError={(error) => console.error('Tool UI error:', error)}
    />
  );
}
```

--------------------------------

### Install TypeScript Server and Client SDKs

Source: https://mcpui.dev/guide/getting-started

Install the server and client SDKs for TypeScript using npm. Requires Node.js v22.x and pnpm v9 or later.

```bash
# Server SDK
npm install @mcp-ui/server @modelcontextprotocol/ext-apps

# Client SDK
npm install @mcp-ui/client
```

--------------------------------

### Clone and Install MCP UI

Source: https://mcpui.dev/guide/getting-started

Clones the MCP UI repository and installs dependencies using pnpm.

```bash
git clone https://github.com/idosal/mcp-ui.git
cd mcp-ui
pnpm install
```

--------------------------------

### Start the Ruby MCP server with shutdown handling

Source: https://mcpui.dev/guide/server/ruby/walkthrough

Adds the server startup code to server.rb, including a trap for INT signal to shut down gracefully. Prints a message and starts the server on http://localhost:8081/mcp.

```ruby
# Start the server and handle shutdown
trap('INT') { http_server.shutdown }
puts 'MCP server running on http://localhost:8081/mcp'
http_server.start
```

--------------------------------

### Run the server with npx ts-node server.ts

Source: https://mcpui.dev/guide/server/typescript/walkthrough

Use this command to start the TypeScript server. It should be run from the project directory.

```bash
npx ts-node server.ts
```

--------------------------------

### Create React project with Vite

Source: https://mcpui.dev/guide/client/walkthrough

Commands to scaffold a new React TypeScript project using Vite and install dependencies.

```bash
npm create vite@latest my-mcp-client -- --template react-ts
cd my-mcp-client
npm install
```

--------------------------------

### FastMCP integration with create_ui_resource

Source: https://mcpui.dev/guide/server/python/usage-examples

Shows how to define FastMCP tools that return UIResource objects created via create_ui_resource. The example includes two tools: show_dashboard and show_welcome, each returning a list containing a UIResource. The server is run with mcp.run().

```python
import argparse
from mcp.server.fastmcp import FastMCP
from mcp_ui_server import create_ui_resource
from mcp_ui_server.core import UIResource

# Create FastMCP instance
mcp = FastMCP("my-server")

@mcp.tool()
def show_dashboard() -> list[UIResource]:
    """Display an analytics dashboard."""
    ui_resource = create_ui_resource({
        "uri": "ui://dashboard/analytics",
        "content": {
            "type": "externalUrl",
            "iframeUrl": "https://my.analytics.com/dashboard"
        },
        "encoding": "text"
    })
    return [ui_resource]

@mcp.tool()
def show_welcome() -> list[UIResource]:
    """Display a welcome message."""
    ui_resource = create_ui_resource({
        "uri": "ui://welcome/main",
        "content": {
            "type": "rawHtml",
            "htmlString": "<h1>Welcome to My MCP Server!</h1><p>How can I help you today?</p>"
        },
        "encoding": "text"
    })
    return [ui_resource]

if __name__ == "__main__":
    mcp.run()
```

--------------------------------

### Error handling for invalid URI with create_ui_resource

Source: https://mcpui.dev/guide/server/python/usage-examples

Demonstrates catching InvalidURIError when create_ui_resource is called with a URI that does not start with 'ui://'. The example shows the exception message format: 'URI must start with 'ui://' but got: invalid://should-be-ui'.

```python
from mcp_ui_server.exceptions import InvalidURIError

try:
    create_ui_resource({
        "uri": "invalid://should-be-ui",
        "content": {
            "type": "externalUrl", 
            "iframeUrl": "https://example.com"
        },
        "encoding": "text"
    })
except InvalidURIError as e:
    print(f"Caught expected error: {e}")
    # URI must start with 'ui://' but got: invalid://should-be-ui
```

--------------------------------

### Build mcp-ui-server from source

Source: https://mcpui.dev/guide/server/python/overview

Build the package from source using uv.

```bash
uv build
```

--------------------------------

### Create project directory and initialize with uv

Source: https://mcpui.dev/guide/server/python/walkthrough

Commands to create a new directory and initialize a Python project with uv (recommended) or pip.

```bash
# Create a new directory
mkdir my-mcp-server
cd my-mcp-server

# Initialize with uv (recommended) or pip
uv init
# or: python -m venv venv && source venv/bin/activate
```

--------------------------------

### Server Side: Create a tool with interactive UI using _meta.ui.resourceUri

Source: https://mcpui.dev/

Use @modelcontextprotocol/ext-apps/server and @mcp-ui/server to create a UI resource and register a tool that links to it via _meta.ui.resourceUri. The example shows creating a rawHtml resource, registering it, and registering a tool with the UI metadata.

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { createUIResource } from '@mcp-ui/server';
import { z } from 'zod';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

// Create the UI resource
const widgetUI = createUIResource({
  uri: 'ui://my-server/widget',
  content: { type: 'rawHtml', htmlString: '<h1>Interactive Widget</h1>' },
  encoding: 'text',
});

// Register the resource handler
registerAppResource(server, 'widget_ui', widgetUI.resource.uri, {}, async () => ({
  contents: [widgetUI.resource]
}));

// Register the tool with _meta.ui.resourceUri
registerAppTool(server, 'show_widget', {
  description: 'Show interactive widget',
  inputSchema: { query: z.string() },
  _meta: { ui: { resourceUri: widgetUI.resource.uri } }  // Links tool to UI
}, async ({ query }) => {
  return { content: [{ type: 'text', text: `Query: ${query}` }] };
});
```

--------------------------------

### Install Express and CORS dependencies

Source: https://mcpui.dev/guide/server/typescript/walkthrough

Install the necessary dependencies for an Express server: express, cors, and their TypeScript types.

```bash
npm install express cors @types/express @types/cors
```

--------------------------------

### Build All Packages

Source: https://mcpui.dev/guide/getting-started

Builds all packages except the documentation package.

```bash
pnpm --filter=!@mcp-ui/docs build
```

--------------------------------

### Set Up WEBrick HTTP Server with MCPServlet

Source: https://mcpui.dev/guide/server/ruby/walkthrough

Adds to server.rb to create a WEBrick HTTP server on port 8081, define an MCPServlet that handles POST and OPTIONS requests, and mount it at /mcp.

```ruby
# --- WEBrick HTTP Server Setup ---
http_server = WEBrick::HTTPServer.new(Port: 8081)

# Create a servlet to handle requests to /mcp
class MCPServlet < WEBrick::HTTPServlet::AbstractServlet
  def initialize(server, mcp_instance)
    super(server)
    @mcp = mcp_instance
  end

  # Handle pre-flight CORS requests
  def do_OPTIONS(_request, response)
    response.status = 200
    response['Access-Control-Allow-Origin'] = '*'
    response['Access-Control-Allow-Methods'] = 'POST, OPTIONS'
    response['Access-Control-Allow-Headers'] = 'Content-Type, Accept'
  end

  def do_POST(request, response)
    response['Access-control-Allow-Origin'] = '*'
    response.status = 200
    response['Content-Type'] = 'application/json'
    response.body = @mcp.handle_json(request.body)
  end
end

# Mount the servlet at the /mcp endpoint
http_server.mount('/mcp', MCPServlet, mcp_server)
```

--------------------------------

### Create UI resources with create_ui_resource

Source: https://mcpui.dev/guide/server/python/usage-examples

Shows four examples of creating UI resources: raw HTML as text, raw HTML as a Base64 blob, external URL as text, and external URL as a Base64 blob. Each resource is printed as JSON. The resulting resource objects are meant to be included in the 'content' array of a toolResult in an MCP interaction.

```python
from mcp_ui_server import create_ui_resource

# Example 1: Direct HTML, delivered as text
resource1 = create_ui_resource({
    "uri": "ui://my-component/instance-1",
    "content": {
        "type": "rawHtml", 
        "htmlString": "<p>Hello World</p>"
    },
    "encoding": "text"
})

print("Resource 1:", resource1.model_dump_json(indent=2))
# Output for Resource 1:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://my-component/instance-1",
#     "mimeType": "text/html;profile=mcp-app",
#     "text": "<p>Hello World</p>"
#   }
# }

# Example 2: Direct HTML, delivered as a Base64 blob
resource2 = create_ui_resource({
    "uri": "ui://my-component/instance-2",
    "content": {
        "type": "rawHtml", 
        "htmlString": "<h1>Complex HTML</h1>"
    },
    "encoding": "blob"
})

print("Resource 2 (blob will be Base64):", resource2.model_dump_json(indent=2))
# Output for Resource 2:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://my-component/instance-2",
#     "mimeType": "text/html;profile=mcp-app",
#     "blob": "PGgxPkNvbXBsZXggSFRNTDwvaDE+"
#   }
# }

# Example 3: External URL, text encoding
dashboard_url = "https://my.analytics.com/dashboard/123"
resource3 = create_ui_resource({
    "uri": "ui://analytics-dashboard/main",
    "content": {
        "type": "externalUrl", 
        "iframeUrl": dashboard_url
    },
    "encoding": "text"
})

print("Resource 3:", resource3.model_dump_json(indent=2))
# Output for Resource 3:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://analytics-dashboard/main",
#     "mimeType": "text/html;profile=mcp-app",
#     "text": "https://my.analytics.com/dashboard/123"
#   }
# }

# Example 4: External URL, blob encoding (URL is Base64 encoded)
chart_api_url = "https://charts.example.com/api?type=pie&data=1,2,3"
resource4 = create_ui_resource({
    "uri": "ui://live-chart/session-xyz",
    "content": {
        "type": "externalUrl", 
        "iframeUrl": chart_api_url
    },
    "encoding": "blob"
})

print("Resource 4 (blob will be Base64 of URL):", resource4.model_dump_json(indent=2))
# Output for Resource 4:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://live-chart/session-xyz",
#     "mimeType": "text/html;profile=mcp-app",
#     "blob": "aHR0cHM6Ly9jaGFydHMuZXhhbXBsZS5jb20vYXBpP3R5cGU9cGllJmRhdGE9MSwyLDM="
#   }
# }

# These resource objects would then be included in the 'content' array
# of a toolResult in an MCP interaction.
```

--------------------------------

### Catch error from createUIResource with invalid URI

Source: https://mcpui.dev/guide/server/typescript/usage-examples

Use this snippet to handle errors thrown by createUIResource when an invalid URI (not starting with 'ui://') is provided. The error message 'MCP-UI SDK: URI must start with 'ui://'.' is logged to the console.

```typescript
try {
  await createUIResource({
    uri: 'invalid://should-be-ui',
    content: { type: 'externalUrl', iframeUrl: 'https://example.com' },
    encoding: 'text',
  });
} catch (e: any) {
  console.error('Caught expected error:', e.message);
  // MCP-UI SDK: URI must start with 'ui://'.
}
```

--------------------------------

### Complete server.py for Python MCP server with UI resources

Source: https://mcpui.dev/guide/server/python/walkthrough

Full server.py file that creates a FastMCP instance and defines four tools returning UI resources: greet, show_dashboard, show_external_site, and show_interactive_demo. Includes argument parsing to choose between stdio and HTTP (SSE) transport, with a default port of 3000.

```python
import argparse
from mcp.server.fastmcp import FastMCP
from mcp_ui_server import create_ui_resource
from mcp_ui_server.core import UIResource

# Create FastMCP instance
mcp = FastMCP("my-mcp-server")

@mcp.tool()
def greet() -> list[UIResource]:
    """A simple greeting tool that returns a UI resource."""
    ui_resource = create_ui_resource({
        "uri": "ui://greeting/simple",
        "content": {
            "type": "rawHtml",
            "htmlString": """
                <div style="padding: 20px; text-align: center; font-family: Arial, sans-serif;">
                    <h1 style="color: #2563eb;">Hello from Python MCP Server!</h1>
                    <p>This UI resource was generated server-side using mcp-ui-server.</p>
                </div>
            """
        },
        "encoding": "text"
    })
    return [ui_resource]

@mcp.tool()
def show_dashboard() -> list[UIResource]:
    """Display a sample dashboard with metrics."""
    dashboard_html = """
    <div style="padding: 20px; font-family: Arial, sans-serif;">
        <h1>Server Dashboard</h1>
        <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 16px; margin-top: 20px;">
            <div style="background: #f0f9ff; border: 1px solid #0ea5e9; border-radius: 8px; padding: 16px;">
                <h3 style="margin-top: 0; color: #0369a1;">Active Connections</h3>
                <p style="font-size: 24px; font-weight: bold; margin: 0; color: #0c4a6e;">42</p>
            </div>
            <div style="background: #f0fdf4; border: 1px solid #22c55e; border-radius: 8px; padding: 16px;">
                <h3 style="margin-top: 0; color: #15803d;">CPU Usage</h3>
                <p style="font-size: 24px; font-weight: bold; margin: 0; color: #14532d;">23%</p>
            </div>
        </div>
    </div>
    """
    
    ui_resource = create_ui_resource({
        "uri": "ui://dashboard/main",
        "content": {
            "type": "rawHtml",
            "htmlString": dashboard_html
        },
        "encoding": "text"
    })
    return [ui_resource]

@mcp.tool()
def show_external_site() -> list[UIResource]:
    """Display an external website in an iframe."""
    ui_resource = create_ui_resource({
        "uri": "ui://external/example",
        "content": {
            "type": "externalUrl",
            "iframeUrl": "https://example.com"
        },
        "encoding": "text"
    })
    return [ui_resource]

@mcp.tool()
def show_interactive_demo() -> list[UIResource]:
    """Show an interactive demo with buttons that send intents."""
    interactive_html = """
    <div style="padding: 20px; font-family: Arial, sans-serif;">
        <h2>Interactive Demo</h2>
        <p>Click the button below to send an intent back to the parent:</p>
        
        <button onclick="sendIntent()" 
                style="background: #2563eb; color: white; padding: 10px 20px; border: none; border-radius: 4px; cursor: pointer;">
            Send Intent
        </button>
        
        <div id="status" style="margin-top: 20px; padding: 10px; background: #f3f4f6; border-radius: 4px;">
            Ready
        </div>
    </div>
    
    <script>
        function sendIntent() {
            const status = document.getElementById('status');
            status.innerHTML = 'Intent sent!';
            
            if (window.parent) {
                window.parent.postMessage({
                    type: 'intent',
                    payload: {
                        intent: 'demo_interaction',
                        params: { source: 'python-server', timestamp: new Date().toISOString() }
                    }
                }, '*');
            }
        }
    </script>
    """
    
    ui_resource = create_ui_resource({
        "uri": "ui://demo/interactive",
        "content": {
            "type": "rawHtml",
            "htmlString": interactive_html
        },
        "encoding": "text"
    })
    return [ui_resource]

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="My MCP Server")
    parser.add_argument("--http", action="store_true", help="Use HTTP transport instead of stdio")
    parser.add_argument("--port", type=int, default=3000, help="Port for HTTP transport (default: 3000)")
    args = parser.parse_args()

    if args.http:
        print("🚀 Starting MCP server on HTTP (SSE transport)")
        print("📡 Server will use SSE transport settings")
        mcp.settings.port = args.port
        mcp.run(transport="sse")
    else:
        print("🚀 Starting MCP server with stdio transport")
        mcp.run()
```

--------------------------------

### Run server in stdio mode

Source: https://mcpui.dev/guide/server/python/walkthrough

Starts the Python MCP server in stdio mode for command-line clients.

```bash
python server.py
```

--------------------------------

### Run server in HTTP mode

Source: https://mcpui.dev/guide/server/python/walkthrough

Starts the Python MCP server in HTTP mode on port 3000 for web clients.

```bash
python server.py --http --port 3000
```

--------------------------------

### Create server.py with FastMCP and UI resource

Source: https://mcpui.dev/guide/server/python/walkthrough

Defines a FastMCP server with a greet tool that returns a UI resource. Supports both stdio and HTTP (SSE) transports via command-line arguments.

```python
import argparse
from mcp.server.fastmcp import FastMCP
from mcp_ui_server import create_ui_resource
from mcp_ui_server.core import UIResource

# Create FastMCP instance
mcp = FastMCP("my-mcp-server")

@mcp.tool()
def greet() -> list[UIResource]:
    """A simple greeting tool that returns a UI resource."""
    ui_resource = create_ui_resource({
        "uri": "ui://greeting/simple",
        "content": {
            "type": "rawHtml",
            "htmlString": """
                <div style="padding: 20px; text-align: center; font-family: Arial, sans-serif;">
                    <h1 style="color: #2563eb;">Hello from Python MCP Server!</h1>
                    <p>This UI resource was generated server-side using mcp-ui-server.</p>
                </div>
            """
        },
        "encoding": "text"
    })
    return [ui_resource]

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="My MCP Server")
    parser.add_argument("--http", action="store_true", help="Use HTTP transport instead of stdio")
    parser.add_argument("--port", type=int, default=3000, help="Port for HTTP transport (default: 3000)")
    args = parser.parse_args()

    if args.http:
        print("🚀 Starting MCP server on HTTP (SSE transport)")
        mcp.settings.port = args.port
        mcp.run(transport="sse")
    else:
        print("🚀 Starting MCP server with stdio transport")
        mcp.run()
```

--------------------------------

### AppRenderer Component Usage

Source: https://mcpui.dev/guide/client/app-renderer

Example of using the AppRenderer component in a React host application to render an MCP tool UI.

```APIDOC
## AppRenderer Component

### Description
Renders an MCP tool UI in a host application, handling the complete lifecycle: resource fetching, sandbox setup, JSON-RPC communication, and tool input/result delivery.

### Props

#### Core Props
- **client** (`Client`) - Optional MCP client for automatic resource fetching and MCP request forwarding. Omit to use custom handlers instead.
- **toolName** (`string`) - Name of the MCP tool to render UI for.
- **sandbox** (`SandboxConfig`) - Sandbox configuration with the proxy URL and optional CSP.
- **html** (`string`) - Optional pre-fetched HTML. If provided, skips all resource fetching.
- **toolResourceUri** (`string`) - Optional pre-fetched resource URI. If not provided, fetched via the client.
- **toolInput** (`Record<string, unknown>`) - Tool arguments to pass to the guest UI once it initializes.
- **toolResult** (`CallToolResult`) - Tool execution result to pass to the guest UI.
- **toolInputPartial** (`object`) - Partial/streaming tool input to send progressively.
- **toolCancelled** (`boolean`) - Set to `true` to notify the guest UI that tool execution was cancelled.
- **hostContext** (`McpUiHostContext`) - Host context (theme, locale, viewport, etc.) to pass to the guest UI.

#### Event Handlers
- **onOpenLink** (`(params, extra) => Promise<McpUiOpenLinkResult>`) - Handler for open-link requests from the guest UI.
- **onMessage** (`(params, extra) => Promise<McpUiMessageResult>`) - Handler for message requests from the guest UI.
- **onLoggingMessage** (`(params) => void`) - Handler for logging messages from the guest UI.
- **onSizeChanged** (`(params) => void`) - Handler for size change notifications from the guest UI.
- **onError** (`(error: Error) => void`) - Callback invoked when an error occurs during setup or message handling.
- **onFallbackRequest** (`(request, extra) => Promise<Record<string, unknown>>`) - Catch-all for JSON-RPC requests not handled by built-in handlers.

#### MCP Request Handlers
- **onCallTool** (`(params, extra) => Promise<CallToolResult>`) - Handler for `tools/call` requests.
- **onListResources** (`(params, extra) => Promise<ListResourcesResult>`) - Handler for `resources/list` requests.
- **onListResourceTemplates** (`(params, extra) => Promise<ListResourceTemplatesResult>`) - Handler for `resources/templates/list` requests.
- **onReadResource** (`(params, extra) => Promise<ReadResourceResult>`) - Handler for `resources/read` requests.
- **onListPrompts** (`(params, extra) => Promise<ListPromptsResult>`) - Handler for `prompts/list` requests.

### Ref Methods
Access via `useRef<AppRendererHandle>`:
- **sendToolListChanged()** - Notify guest UI that the server's tool list has changed.
- **sendResourceListChanged()** - Notify guest UI that the server's resource list has changed.
- **sendPromptListChanged()** - Notify guest UI that the server's prompt list has changed.
- **teardownResource()** - Notify the guest UI before unmounting (graceful shutdown).

### Example
```tsx
import { AppRenderer, type AppRendererHandle } from '@mcp-ui/client';

function ToolUI({ client, toolName, toolInput, toolResult }) {
  const appRef = useRef<AppRendererHandle>(null);

  return (
    <AppRenderer
      ref={appRef}
      client={client}
      toolName={toolName}
      sandbox={{ url: new URL('http://localhost:8765/sandbox_proxy.html') }}
      toolInput={toolInput}
      toolResult={toolResult}
      hostContext={{ theme: 'dark' }}
      onOpenLink={async ({ url }) => {
        window.open(url, '_blank');
        return {};
      }}
      onMessage={async (params) => {
        console.log('Message from tool UI:', params);
        return {};
      }}
      onError={(error) => console.error('Tool UI error:', error)}
    />
  );
}
```
```

--------------------------------

### Server-side: Create MCP server with interactive UI using registerAppTool and registerAppResource

Source: https://mcpui.dev/guide/getting-started

Sets up an MCP server, creates a UI resource with interactive HTML, registers the resource handler, and registers a tool linked to the UI via _meta.ui.resourceUri. Uses the @modelcontextprotocol/ext-apps App class for communication.

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { createUIResource } from '@mcp-ui/server';
import { z } from 'zod';

// 1. Create your MCP server
const server = new McpServer({ name: 'my-server', version: '1.0.0' });

// 2. Create the UI resource with interactive HTML
const widgetUI = await createUIResource({
  uri: 'ui://my-server/widget',
  content: {
    type: 'rawHtml',
    htmlString: `
      <html>
        <body>
          <h1>Interactive Widget</h1>
          <button onclick="sendMessage()">Send Message</button>
          <div id="status">Ready</div>
          <script type="module">
            import { App } from 'https://esm.sh/@modelcontextprotocol/ext-apps@0.4.1';

            // Initialize the MCP Apps client
            const app = new App({ name: 'widget', version: '1.0.0' });

            // Listen for tool input
            app.ontoolinput = (params) => {
              document.getElementById('status').textContent =
                'Received: ' + JSON.stringify(params.input);
            };

            // Send a message to the conversation
            window.sendMessage = async () => {
              await app.sendMessage({
                role: 'user',
                content: [{ type: 'text', text: 'Tell me more about this widget' }]
              });
            };

            // Connect to the host
            await app.connect();
          </script>
        </body>
      </html>
    `,
  },
  encoding: 'text',
});

// 3. Register the resource handler
registerAppResource(
  server,
  'widget_ui',
  widgetUI.resource.uri,
  {},
  async () => ({
    contents: [widgetUI.resource]
  })
);

// 4. Register the tool with _meta.ui.resourceUri
registerAppTool(
  server,
  'show_widget',
  {
    description: 'Show an interactive widget',
    inputSchema: {
      query: z.string().describe('User query'),
    },
    _meta: {
      ui: {
        resourceUri: widgetUI.resource.uri  // Links tool to UI
      }
    }
  },
  async ({ query }) => {
    return {
      content: [{ type: 'text', text: `Processing: ${query}` }]
    };
  }
);
```
Tokens:
Raw