MCP‑UI: Declarative Reactive Rich UI Components Extension for MCP

[gunta]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

Idea: MCP‑UI — Declarative Reactive Rich UI Components Extension for MCP

Related issue: https://github.com/orgs/modelcontextprotocol/discussions/287 this one is for complex, reactive, rich UIs.
Just like https://github.com/21st-dev/magic-mcp

“Text is perfect for many flows, but sometimes users just need a button.”
Me, after building five MCP tools that had to invent their own UI layer every time.

---

1 · Motivation

The current MCP spec focuses on text‑in / text‑out.
That’s ideal for chat, but limiting for:

• interactive widgets (stopwatch, counter, map, chart)
• data‑heavy CRUD dashboards
• beautiful component libraries like magic‑mcp that already render HTML/React

Right now every tool invents its own contract. I’d like to standardise that once, so any MCP client can:

1. Detect a UI payload.
2. Render it safely (iframe or React Server Components), or
3. Render it natively in the host framework (React, Vue, React Native) when isolation isn’t required.
4. Optimise data fetching and caching automatically.

---

2 · Design Goals

Goal	Why it matters
Declarative & JSON	Easy to inspect, diff, cache, and stream.
Framework‑agnostic	One definition → React, Vue, Svelte, Expo RN, Web Components.
Native Host Rendering	First‑class support for React, Vue, React Native components when iframe/RSC sandboxing isn’t needed.
Zero‑config CRUD	List / detail / create / update / delete out of the box.
First‑class querying	Prefetch, pagination, mutations via TanStack Query or SWR.
Security by default	Sandboxed iframe or RSC realm; strict CSP.
Versionable / Overridable	Clear headers, semantic versioning, and slot‑in overrides.

---

3 · Proposed Wire Format

3.1 Mime type

• application/vnd.mcp.ui+json — JSON payload
• (optional) application/vnd.mcp.ui+rsc — streamed React Server Components

3.2 Top‑level shape

{
  "mimeType": "application/vnd.mcp.ui+json",
  "data": {
    "$schema": "https://mcp.dev/ui-schema/v1",
    "version": "1.0.0",
    "components": {
      /* one stanza per MCP model or widget */
    }
  }
}

### 3.3 Component stanza
```jsonc
"User": {
  "type": "crud",                       // crud | readonly | component
  "schemaRef": "/mcp/schema#User",      // link to MCP model
  "operations": ["list","detail","create","update","delete"],
  "queries": {                          // preferred data layer
    "react": "tanstack",
    "vue":   "swr"
  },
  "overrides": {                        // optional .lite.tsx overrides
    "listItem": "./components/custom/UserListItem.lite.tsx"
  }
}

---

4 · Example Build Pipeline

Mitosis looks like a good default to have here.

1. CLI (npx mcp-ui pull) downloads application/vnd.mcp.ui+json.
2. Converts JSON → Mitosis (universal component AST).
3. Runs mitosis compile --target react (or vue/svelte/web/native).
4. Drops code in components/generated/* with header:

// AUTO‑GENERATED by MCP‑UI v1.0.0 – DO NOT EDIT

5. Developers optionally add Tailwind classes or swap override files.

5 · Example Generated React (truncated)

// AUTO‑GENERATED by MCP‑UI v1.0.0 – DO NOT EDIT
import { useQuery, useMutation } from '@tanstack/react-query';

export default function UserList() {
  const { data, error, isLoading } = useQuery(['User'], fetchUsers);
  if (isLoading) return <div>Loading…</div>;
  if (error)     return <div>Error!</div>;

  return (
    <ul>
      {data.map(u => <UserListItem key={u.id} user={u} />)}
    </ul>
  );
}

6 · Security Model

• HTML or JSON UI MAY render in <iframe sandbox> with:
  sandbox="allow-same-origin allow-scripts" (no top‑nav, no forms).
• RSC variant (vnd.mcp.ui+rsc) keeps code on the server; still isolated via a “realm” or RSC boundary.
• Native mode (React/Vue/RN) can be used when the MCP client is trusted, bypassing iframe for seamless UX.

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other