# MCP UI Playground

A runnable lab for comparing plain MCP results, FastMCP Prefab UI, server-interactive MCP Apps,
and a raw HTML MCP Apps bridge inside ChatGPT and other compatible hosts.

## Run locally

```bash
uv sync --dev
uv run mcpui-playground
```

The Streamable HTTP endpoint is `http://127.0.0.1:8775/mcp`.

Inspect it with:

```bash
npx @modelcontextprotocol/inspector@latest
```

Or open FastMCP's local Apps preview:

```bash
uv run fastmcp dev apps src/mcpui_playground/server.py:mcp
```

## Experiments

| Tool | Expected experience |
| --- | --- |
| `get_lab_snapshot` | Plain JSON-like structured data, usable in every MCP client |
| `show_terminal_dashboard` | Markdown table and ASCII bars for terminal-only clients |
| `show_metrics_dashboard` | Metrics, tabs, charts, search, sorting, and an accordion |
| `open_experiment_notebook` | Form submissions and buttons calling app-only server tools |
| `open_scenario_studio` | Sliders, numeric edits, row reordering, draggable bars, and server save/reset |
| `inspect_host_bridge` | Raw tool result, host context, and a measured UI-to-server ping |

## Preview

![MCP UI metrics dashboard](artifacts/metrics-dashboard.png)

The local FastMCP host also exercises server callbacks and the raw MCP Apps bridge. Screenshots and
Codex CLI probe outputs are indexed in [`artifacts/README.md`](artifacts/README.md).

## Connect from ChatGPT web

This checkout is deployed on the machine's existing Tailscale Funnel at:

```text
https://riema.taile42c02.ts.net/mcpui/mcp
```

In ChatGPT, enable **Settings -> Security and login -> Developer mode**, open the Plugins directory,
select the plus button, and add the URL above. After tool scanning succeeds, start a new chat, enable
the development plugin, and try:

```text
Open the MCP UI Lab metrics dashboard and then open the experiment notebook.
```

The endpoint is intentionally unauthenticated and serves only synthetic, process-local demo data.
It shares the standard HTTPS port through a `/mcpui` Funnel mount; the existing Jacobian `/mcp`
route remains separate.
See [research notes](docs/research-notes.md) for protocol details, constraints, and primary sources.

Pinned upstream source references are cataloged in [`references/README.md`](references/README.md).
Materialize them locally with `./scripts/sync-references.sh`.

## Use from Codex CLI

Codex CLI can call the same MCP server, but its terminal UI does not embed the MCP App iframe. Add
the local service and use the terminal-native fallback. The editable scenario also supports a
conversational update-and-redraw loop:

```bash
codex mcp add mcpui-playground --url http://127.0.0.1:8775/mcp
codex "Call show_terminal_dashboard from mcpui-playground and display it verbatim."
codex "Set ui_opens to 2000 with update_scenario_metric, then call show_scenario_terminal."
```

The Prefab tool is still useful to Codex as structured data: Codex receives and can reason over its
component tree, while a compatible web host performs the interactive rendering. See
[`docs/codex-cli-findings.md`](docs/codex-cli-findings.md) for the recorded probe.

## Verify

```bash
uv run pytest
uv run ruff check .
```