A chat that hands you back a real screen — not just words.

Picture a chatbot that could do more than talk. It could run your program. It could grab a live number. It could show you a real, working screen — without you leaving the chat to go find it. That is hard to build.

The moment you try to build that, you hit problems that have nothing to do with your actual idea. The chat app might hand each message to a brand new copy of your program — one that remembers nothing from before. Get that wrong, and your second reply comes from a stranger. A stranger who never saw the first message, and has no idea it matters.

Once your program can answer, you still need something real to put on the screen. It has to behave the same in an ordinary web page and inside the chat itself. Build those as two separate things, and they quietly drift apart. One breaks. Nobody notices — because nobody was testing the one that broke.

And every hour something sits open on the internet, waiting for a chat app to call it, is an hour it's also open to anyone else. That's true before you've written a single line of the feature you actually wanted.

The problem

MCP Studio is a ready-made project you can copy and run. Clone it, and you get a page for testing by hand. You also get one web address a chat app can call, and five ready-made dashboard screens. All of it is already connected together.

Underneath, this project follows one shared rule. That rule lets a chat call out to real software. It can run a function, fetch data, or hand back a screen — instead of only words. Chat apps that support this rule can talk to any project built this way, not just this one.

One piece of this project is a small interactive screen — not a link you click away to, but something that shows up right inside the chat itself. MCP Studio ships one, built once, that works both as an ordinary web page and inside a live chat.

The big idea

The screen you see inside the chat is not a second copy of the one you tested in your browser. It is the exact same one.

Here's the trick: build the screen once, and let the place it's shown decide how it gets delivered. In an ordinary browser, it talks straight to the chat address. Inside a real chat, the chat app hands it that exact same screen through its own connection — and tells it what colors and size to use.

That's not just convenient. It's a rule: if a feature works in your browser test but not inside a real chat, it isn't done. There's no such thing as 'it works, just not in the real place it needs to work.'

The aha

Built once. Shown twice. It can never quietly become two different screens.

This project runs on MCP — Model Context Protocol. MCP is a shared set of rules that let an AI chat call out to real software. It can run a function, fetch data, or hand back a screen — instead of only sentences. One level down, the choices here are specific and deliberate. Each one is written down as a short decision-and-consequence record.

The address the chat app calls, /api/mcp, is stateless — meaning each incoming request gets a brand-new server and connection object, used once and thrown away. Nothing about the first message survives to see the second, on the server side. That's what lets it run on hosting that creates and destroys server instances on demand, rather than keeping one instance permanently assigned to one conversation.

The front door is deliberately narrow. Incoming requests are capped at 32 KiB — kibibytes, units of 1,024 bytes, so a little over 32,000 bytes. Every input is checked against a strict schema (an exact description of the shape data must take) before anything runs. Responses are never stored or cached, and cross-origin access is allowed only where explicitly listed, rather than left open by default.

The five dashboard designs live in one typed catalog file. Every entry carries a stable ID, its category, the original designer's name, and a direct link to the source design — attribution that travels with the pattern instead of getting lost when it's reused.

Architecture

Data flow

Three shapes of work this starter is built for.

In the real world

Node.js 22.13.0 or newer is required — the package.json engines field enforces it — along with npm or pnpm.

npm run install:ci ; pnpm install

1. Install dependencies Run npm run install:ci (runs scripts/install-pnpm.sh) or pnpm install directly.
2. Start the dev server Run npm run dev (or pnpm dev). You'll get a local address serving the test bench at /: a tool tester, a resource inspector, and a template builder, in tabs.
3. Run a tool Pick a tool such as show_dashboard, run it, and watch the raw request and response appear next to a live preview of the screen it returns — the same screen, rendered instantly, no second copy quietly drifting out of sync.
4. Build and check Run npm run build (bundles the widget, then builds the framework output), then npm run lint, npm run typecheck, and npm run test to confirm it holds together.
5. Run the built server locally Run npm run start to serve the compiled output through Wrangler — the local development tool for Cloudflare Workers, a hosting style that creates a fresh server instance per request instead of keeping one running full time.
6. Connect it to a real conversation Deploy to a public web address, add it — as .../api/mcp — in ChatGPT's developer settings, and try the prompt: 'Use MCP Studio to show the starter dashboard.'

Every claim above traces back to a retrieval index built over this repository: 347 passages, 1 component, 34 public symbols, and 35 entrypoint commands, encoded at 384 dimensions.