MCP UI + WebMCP

Bidirectional integration between AI assistants and embedded web applications

Quick Start • Architecture • Packages • Docs

Try It Live

Live Chat UI: mcp-ui.mcp-b.ai Full App Demo: beattheclankers.com

Visit beattheclankers.com to see the full application with embedded iframe. Test the tools yourself using the MCP-B Chrome Extension.

What This Does

AI assistants invoke tools that render interactive web apps. Those apps can register new tools back to the AI. This combines MCP UI resources with WebMCP bidirectional tool registration.

Flow:

AI calls showTicTacToeGame
MCP server returns UI resource with iframe
Game loads and registers tictactoe_move, tictactoe_reset, etc.
AI can now play the game using dynamically registered tools

This pattern works for any embedded application: forms, visualizations, interactive demos, configuration UIs.

Quick Start

Create a New App (Recommended)

Use our interactive CLI to scaffold a new project:

npx @mcp-b/create-webmcp-app

Choose between:

Vanilla - Pure HTML/CSS/JavaScript (no build step!)
React - React + TypeScript + Vite (full-featured)

Then:

cd your-project
pnpm dev

Or Run the Demo

# Install dependencies
pnpm install

# Run both apps (MCP server + Chat UI)
pnpm dev

Open http://localhost:5173 and ask the AI to show you a TicTacToe game.

Requirements

Node.js 24.3.0+ (see .nvmrc)
pnpm 10.14.0+

Architecture

Key Principle: Decoupled Architecture

The chat UI and embedded apps have no custom knowledge of each other. They communicate exclusively through standard protocols:

Chat UI discovers tools via the MCP protocol (HTTP/SSE)
Embedded apps register tools via the WebMCP protocol (postMessage)
Prompts and tools declared in the MCP server are automatically discovered and available in the UI

No hardcoding, no configuration files. Just standards-based protocols enabling dynamic composition.

WebMCP vs MCP-B

WebMCP is the W3C standard specification for bidirectional tool registration in browsers, defining the navigator.modelContext API. MCP-B is the reference implementation and polyfill that makes WebMCP available today.

WebMCP: Standards-based API specification (W3C Web Machine Learning Community Group)
MCP-B: Reference implementation providing:
- Polyfill for navigator.modelContext before browser support
- NPM packages (@mcp-b/react-webmcp, @mcp-b/transports, etc.)
- Translation bridge between WebMCP and MCP protocols
- Browser extension for testing

System Architecture

flowchart TB
    subgraph ChatUI["Chat UI Browser Context"]
        UI[AI Chat Interface]
        HTTP_CLIENT["HTTP MCP Client<br/>@modelcontextprotocol/sdk"]
        WEBMCP_MGR["WebMCP Integration<br/>useWebMCPIntegration"]
        IFRAME["Iframe Container<br/>Side Panel"]

        UI --> HTTP_CLIENT
        UI --> WEBMCP_MGR
        WEBMCP_MGR --> IFRAME
    end

    subgraph MCPServer["MCP Server - Cloudflare Worker"]
        TOOLS["Tool Registry<br/>showTicTacToeGame, etc."]
        ASSETS["Static Asset Server<br/>Serves mini-apps"]

        TOOLS -.->|Returns UI Resource| ASSETS
    end

    subgraph EmbeddedApp["Embedded App Iframe Context"]
        APP["Mini-App React<br/>TicTacToe, etc."]
        WEBMCP_INIT["MCP-B Polyfill<br/>@mcp-b/global"]
        HOOKS["useWebMCP Hooks<br/>@mcp-b/react-webmcp"]
        TRANSPORT_CHILD["IframeChildTransport<br/>@mcp-b/transports"]

        APP --> HOOKS
        HOOKS --> WEBMCP_INIT
        WEBMCP_INIT --> TRANSPORT_CHILD
    end

    HTTP_CLIENT <-->|HTTP/SSE MCP Protocol| TOOLS
    ASSETS -->|iframe src| APP
    WEBMCP_MGR <-->|IframeParentTransport postMessage| TRANSPORT_CHILD

    style WEBMCP_INIT fill:#e1f5ff
    style HOOKS fill:#e1f5ff
    style TRANSPORT_CHILD fill:#e1f5ff
    style WEBMCP_MGR fill:#e1f5ff

Complete Flow: Tool Call to Bidirectional Communication

sequenceDiagram
    participant User
    participant AI as AI Assistant
    participant HTTP as HTTP MCP Client
    participant Server as MCP Server
    participant Iframe as Iframe Container
    participant App as Embedded App
    participant WebMCP as WebMCP Manager

    %% Initial tool call that returns UI
    User->>AI: "Show me TicTacToe"
    AI->>HTTP: callTool(showTicTacToeGame)
    HTTP->>Server: HTTP Request
    Server-->>HTTP: UI Resource (externalUrl)
    HTTP-->>AI: Tool Result
    AI->>Iframe: Render UI Resource

    %% Iframe loads and WebMCP connection established
    Note over Iframe,App: Iframe loads mini-app
    Iframe->>App: Load src URL
    App->>App: initializeWebModelContext<br/>(@mcp-b/global)
    App->>WebMCP: postMessage(iframe-ready)
    WebMCP->>App: postMessage(parent-ready)

    %% MCP-B Transport Setup
    Note over WebMCP,App: MCP-B Transport Layer
    WebMCP->>WebMCP: Create IframeParentTransport<br/>(@mcp-b/transports)
    App->>App: IframeChildTransport ready<br/>(auto-created by @mcp-b/global)
    WebMCP->>App: MCP: listTools()
    App-->>WebMCP: Tools: [tictactoe_move, tictactoe_reset, ...]
    WebMCP->>WebMCP: registerWebMcpTools(tools, sourceId)

    %% Tool registration complete
    Note over AI,App: Embedded tools now available
    AI->>AI: Merge HTTP tools + WebMCP tools

    %% User invokes WebMCP tool
    User->>AI: "Make a move at position 4"
    AI->>WebMCP: callTool(tictactoe_move, {position: 4})
    WebMCP->>App: MCP: callTool via IframeParentTransport
    App->>App: useWebMCP handler executes
    App->>App: Update game state
    App-->>WebMCP: Tool Result (markdown + state)
    WebMCP-->>AI: Tool Result
    AI-->>User: "Moved to position 4..."

    %% Dynamic tool updates
    Note over App,WebMCP: Tool list can change dynamically
    App->>WebMCP: MCP: notifications/tools/list_changed
    WebMCP->>App: MCP: listTools()
    App-->>WebMCP: Updated tool list
    WebMCP->>WebMCP: registerWebMcpTools(newTools, sourceId)

Key Components

Chat UI (Parent Context)

HTTP MCP Client (@modelcontextprotocol/sdk): Connects to remote MCP server via HTTP/SSE for initial tools
WebMCP Integration (useWebMCPIntegration.ts): Manages WebMCP clients and tools from iframes
Iframe Lifecycle (useIframeLifecycle.ts): Sets up MCP-B transport for each iframe
Tool Routing: Routes calls to HTTP MCP or WebMCP clients based on source ID
IframeParentTransport (@mcp-b/transports): Bidirectional communication channel to embedded apps

Embedded Apps (Iframe Context)

MCP-B Polyfill (@mcp-b/global): Implements navigator.modelContext API
useWebMCP Hook (@mcp-b/react-webmcp): Registers tools with automatic lifecycle management
IframeChildTransport (@mcp-b/transports): Receives tool calls from parent via postMessage
Parent Communication (useParentCommunication.ts): Readiness protocol and notifications

MCP Server

Tool Registry: Exposes tools like showTicTacToeGame that return UI resources
UI Resource Types: Supports externalUrl, rawHtml, and remoteDom
Static Assets: Serves bundled mini-apps for iframe embedding

MCP UI Resources

Three resource types supported (learn more):

Type	Use Case	Implementation
`externalUrl`	Embedded mini-apps	iframe with URL
`rawHtml`	Simple markup	Sanitized HTML
`remoteDom`	Dynamic content	JavaScript-generated DOM

→ MCP-UI Server SDK | → MCP-UI Client SDK

WebMCP Tool Registration

Mini-apps register tools using the useWebMCP hook from @mcp-b/react-webmcp (docs):

import { useWebMCP } from '@mcp-b/react-webmcp';

useWebMCP({
  name: "tictactoe_move",
  description: "Make a move at position",
  schema: z.object({
    position: z.number().min(0).max(8)
  }),
  handler: async ({ position }) => {
    // Execute move
    return {
      content: [{
        type: "text",
        text: `Moved to position ${position}`
      }]
    };
  }
});

The AI can immediately invoke tictactoe_move as if it were a native MCP tool.

MCP-B Packages:

@mcp-b/react-webmcp - React hooks for WebMCP (docs)
@mcp-b/transports - Transport layer implementations (docs)
@mcp-b/core - Core WebMCP functionality (docs)

→ MCP-B Quick Start | → MCP-B Examples | → All NPM Packages

Packages

Apps

chat-ui

React chat interface with MCP client and WebMCP integration. Connects to MCP servers via HTTP, displays UI resources, handles dynamic tool registration.

Tech: React 19, Vite, Tailwind CSS 4, Vercel AI SDK

→ Documentation

mcp-server

MCP server implementation on Cloudflare Workers. Serves static mini-apps, implements MCP protocol with UI extensions.

Tech: Cloudflare Workers, Hono, @modelcontextprotocol/sdk

→ Documentation

create-webmcp-app

Interactive CLI for scaffolding new WebMCP applications with template selection.

Tech: Node.js, TypeScript

→ Documentation

Templates

react

React + TypeScript + Vite template for building production-ready MCP servers with embedded UIs.

→ Documentation

vanilla

Pure HTML/CSS/JavaScript template with no build step required - perfect for learning.

→ Documentation

Tests

e2e

Playwright test suite verifying integration between chat UI and MCP server.

→ Documentation

Commands

# Development
pnpm dev                        # Run all apps (chat-ui + mcp-server)
pnpm --filter chat-ui dev       # Chat UI only
pnpm --filter mcp-server dev    # MCP server only

# Templates (run manually from template directories)
cd templates/react && pnpm dev
cd templates/vanilla && pnpm dev

# Build & Quality
pnpm build                      # Build all packages
pnpm typecheck                  # Type-check
pnpm lint                       # Lint all packages
pnpm check                      # Run lint + typecheck

# Testing
pnpm test                       # Run E2E tests
pnpm test:ui                    # Interactive Playwright UI
pnpm test:debug                 # Debug mode

Deployment

MCP Server → Cloudflare Workers

cd apps/mcp-server
pnpm build
pnpm deploy  # or: wrangler deploy

Configure .prod.vars with your worker URL.

Chat UI → Cloudflare Pages

cd apps/chat-ui
pnpm build
wrangler pages deploy dist

Configure .env.production with your MCP server URL.

See ENVIRONMENT_SETUP.md for detailed configuration.

Documentation

Getting Started

AGENTS.md - Navigation hub for AI agents
CONTRIBUTING.md - Development standards

Architecture

ARCHITECTURE.md - Design decisions
EMBEDDING_PROTOCOL.md - WebMCP protocol
How to Customize - Create mini-apps

Configuration

ENVIRONMENT_SETUP.md - Environment variables
TESTING.md - Test infrastructure

Tech Stack

Monorepo: Turborepo + pnpm workspaces
Frontend: React 19, TypeScript 5.8, Vite 7
MCP: @modelcontextprotocol/sdk, @mcp-ui packages
WebMCP: @mcp-b packages for bidirectional tool registration
AI: Vercel AI SDK with Anthropic provider
Runtime: Cloudflare Workers + Durable Objects
Testing: Playwright 1.49

Contributing

Fork, experiment, report issues, submit improvements.

See CONTRIBUTING.md for development standards.

Resources

MCP-UI (UI Resources)

MCP-UI Introduction - Overview of MCP UI resources
Protocol Details - Resource types and implementation
Server SDK (TypeScript) - Build MCP servers with UI support
Client SDK - Render UI resources in your client
GitHub - Source code and examples

MCP-B (WebMCP / Bidirectional Tools)

Documentation:

MCP-B Documentation - Getting started with WebMCP
Quick Start - Get WebMCP running in minutes
Core Concepts - Architecture and system design
Examples - Ready-to-use implementations

NPM Packages:

@mcp-b/react-webmcp - React hooks for WebMCP (docs)
@mcp-b/transports - Transport layer implementations (docs)
@mcp-b/core - Core WebMCP functionality (docs)
@mcp-b/server - Server-side WebMCP support (docs)
All Packages - Complete package repository

Live Demos & Tools:

beattheclankers.com - Full application with embedded iframe
mcp-ui.mcp-b.ai - Live chat UI demo
mcp-b.ai - Interactive examples
MCP-B Chrome Extension - Test tools in your browser

Specification:

WebMCP Specification - W3C Web Machine Learning Community Group
WebMCP Explainer - Technical proposal and API details

Model Context Protocol

MCP Documentation - Official protocol documentation
MCP Specification - Technical specification
MCP GitHub - Specification repository

Deployment & Infrastructure

Cloudflare Workers - Serverless runtime
Cloudflare Durable Objects - Stateful coordination
Playwright - E2E testing framework

License

This project uses multiple licenses:

Chat UI (apps/chat-ui/): AGPL-3.0 - See apps/chat-ui/LICENSE
All other packages: Apache-2.0 - See LICENSE

Name		Name	Last commit message	Last commit date
Latest commit History 104 Commits
.github		.github
.vscode		.vscode
apps		apps
docs		docs
tests/e2e		tests/e2e
.gitignore		.gitignore
.nvmrc		.nvmrc
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
REFACTORING_ANALYSIS.md		REFACTORING_ANALYSIS.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
turbo.json		turbo.json

License

WebMCP-org/mcp-ui-webmcp

Folders and files

Latest commit

History

Repository files navigation

MCP UI + WebMCP

Try It Live

What This Does

Quick Start

Create a New App (Recommended)

Or Run the Demo

Requirements

Architecture

Key Principle: Decoupled Architecture

WebMCP vs MCP-B

System Architecture

Complete Flow: Tool Call to Bidirectional Communication

Key Components

Chat UI (Parent Context)

Embedded Apps (Iframe Context)

MCP Server

MCP UI Resources

WebMCP Tool Registration

Packages

Apps

chat-ui

mcp-server

create-webmcp-app

Templates

react

vanilla

Tests

e2e

Commands

Deployment

MCP Server → Cloudflare Workers

Chat UI → Cloudflare Pages

Documentation

Getting Started

Architecture

Configuration

Tech Stack

Contributing

Resources

MCP-UI (UI Resources)

MCP-B (WebMCP / Bidirectional Tools)

Model Context Protocol

Deployment & Infrastructure

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages