Open MCP Apps

open-mcp-apps

English | 简体中文

Give your AI a persistent, reusable UI. It builds the app once — you keep it forever.

open-mcp-apps is an open engine built on MCP Apps (ui://, io.modelcontextprotocol/ui) — an extension to the core Model Context Protocol specification, and the first official one, live since 26 January 2026. It gives any MCP-Apps-capable host (Claude Desktop, claude.ai, Codex, ChatGPT, …) three things the extension itself doesn't provide:

1. An app registry the AI can write to. Ask for a UI that doesn't exist — the AI reads the authoring guide, writes a single-file HTML app against a tiny window.oma API, and saves it. From that moment you can open it by name, in this chat and every future one.
2. Persistent, versioned data — separate from the UI. Apps bind to generic *collections* of items backed by SQLite plus an append-only change_event ledger. Every mutation is an idempotent domain command (command_id) with optimistic concurrency (expected_version). The AI and the human edit the same store — the widget is just a view.
3. A shell runtime so AI-written apps actually work. Serving ui://, the engine wraps the app with the official MCP App bridge, host theming (Claude's design tokens, light/dark), and the window.oma data API. What you write is a view; the protocol, persistence, idempotency and theming are the engine's problem.

**Which of those hosts *this* engine reaches. It runs on your machine and binds `127.0.0.1`, so it serves the hosts on that same machine: Claude Desktop, Claude Code, Codex, plus its own browser viewer. A browser host cannot reach a loopback server on your laptop, so claude.ai and ChatGPT web need a remote deployment** — today that means the hosted openmcp.app, which runs this same engine for you. Running that remote shape *yourself* is on the roadmap and not done.

Install

open-mcp-apps runs as a local MCP server. First get it connected to your host (below); then onboarding happens inside the host, separately — that's where the AI builds your first app.

From npm — nothing to clone

If you are comfortable editing your host's config file, point it at the published package and let npx fetch the engine. This path needs only Node 22 — no git, and no checkout for you to keep updated. Paste this into your host's MCP server config:

{

"mcpServers": { "open-mcp-apps": { "command": "npx", "args": ["-y", "@2nd1st/open-mcp-apps"] } } }

The one thing the installer below adds is registering the server into every host it finds. Either way the server seeds the system apps (settings, dashboard, App Store) when it starts, and your data lives in the same fixed per-user store, so you can move between an npx server and a cloned one without migrating anything.

A note on npm: this project publishes under the scoped name

@2nd1st/open-mcp-apps. The *unscoped*

open-mcp-apps on the registry is not this project — that name is held by an unrelated

package. Check for the @2nd1st/ prefix; the scope is the only thing telling the two apart.

With the installer — one command

Installing needs a shell, so the chat apps (Claude Desktop, Codex) can't install themselves — use one of these instead:

curl -fsSL https://raw.githubusercontent.com/2nd1st/open-mcp-apps/main/install.sh | sh

It opens a short picker to choose which hosts to register into — Claude Desktop, Claude Code, Codex — plus your permission preference. Skip it with -s -- --yes, or target one host with -s -- --host codex.

Where it puts the clone, before you pipe anything into a shell: ~/open-mcp-apps. Set OMA_DIR to put it somewhere else — curl -fsSL | OMA_DIR=~/src/oma sh. Re-running the one-liner updates that same clone in place instead of making a second one. Your apps and data are *not* in it (they live in the per-user store under Configuration), so the folder is safe to move or delete — and node uninstall.mjs does not delete it for you.

With a coding agent (Claude Code, Codex CLI — they have a shell), paste:

Read https://raw.githubusercontent.com/2nd1st/open-mcp-apps/main/install.md and follow it.

Either way, install.mjs registers the server into each host you pick, idempotently — it never clobbers your other servers, pins a stable node launcher (native SQLite ABI), reports what changed, and cleans up a pre-rename entry if one lingers. Your data lives in a fixed per-user store (not inside the clone), so every host shares the same apps and data.

From a clone — for development

git clone https://github.com/2nd1st/open-mcp-apps && cd open-mcp-apps

npm install node install.mjs # same picker as the one-liner above

To wire a clone into a host by hand instead, point it at the checkout — this is the shape install.mjs writes:

{

"mcpServers": { "open-mcp-apps": { "command": "node", "args": ["/absolute/path/to/open-mcp-apps/src/server.mjs"] } } }

Hosted

openmcp.app runs the engine for you. The engine in this repository binds 127.0.0.1 by design, so a self-hosted remote deployment is not a supported shape yet — see Status and roadmap.

Uninstall

node uninstall.mjs unregisters the server from every host it finds — but keeps your data: the shared store stays put, so re-installing later restores every app and all data. It also leaves the installer's clone (~/open-mcp-apps, or wherever OMA_DIR pointed) on disk — nothing here ever deletes that folder, so remove it yourself when you want the checkout gone.

node uninstall.mjs           # unregister from all detected hosts — keeps your data

node uninstall.mjs --purge # also delete the shared store (apps + data), irreversible node uninstall.mjs --check # read-only: show what's registered and what would change

Requirements

• Node 22 or newer, on macOS, Windows or Linux.
• `git` — only on the installer path. The npx path above needs neither git nor a checkout. The installer checks for both and stops with a message rather than half-installing if either is missing.
• A host that renders `ui://` if you want widgets *in the conversation*. Terminal hosts (Claude Code in a terminal, codex CLI) drive the same data by design and put the UI on a browser screen beside the terminal instead — one that can follow along, showing whatever the AI just opened. The per-host detail is in Host support.
• After installing or updating, fully quit and reopen the host (Cmd-Q, not just closing the window) — it keeps its old server process on the old data until fully quit.

Configuration

Every setting is an environment variable, set in the env block of your host's MCP server entry:

{

"mcpServers": { "open-mcp-apps": { "command": "npx", "args": ["-y", "@2nd1st/open-mcp-apps"], "env": { "OMA_VIEWER": "1", "PORT": "8787" } } } }

An app's own tool. Every app opens through open_app. To give one app its own open_ tool as well, pin it: Settings → Installed → the app → Own tool. The tool list changes only when you pin, unpin or delete a pinned app, and Claude.ai and ChatGPT show the new tool after you refresh the connector's tool list.

Where your data lives. The whole store is one SQLite file, open-mcp-apps.db, in ~/Library/Application Support/open-mcp-apps/ (macOS), %APPDATA%\open-mcp-apps\ (Windows), or $XDG_DATA_HOME else ~/.local/share/open-mcp-apps/ (Linux). It is outside any clone, which is why every host shares the same apps and data.

First-run permissions. The first few tool calls each show an approval dialog — pick "Always allow". The tool set is small and stable on purpose: read-only tools generally skip approval, and the single open_app tool covers opening *every* app (including ones the AI creates later) behind that one grant, so nothing new asks again. An OMA_DYNAMIC_TOOLS=1 left in an older entry does nothing; node install.mjs --check reports it as stale, and re-running the installer removes that one key. You can also batch approvals in Settings → Connectors → open-mcp-apps → Tool permissions.

Usage

Start in your host. Restart it after installing. New here? The engine ships one MCP prompt, get_started. A host that surfaces prompts lists it as Get started with open-mcp-apps; hosts that render prompts as slash commands spell it /mcp__open-mcp-apps__get_started. Picking it hands the AI the whole opening move. Not every host surfaces prompts — where yours doesn't, nothing is lost, because the prompt is just a sentence you can say yourself: "I just installed open-mcp-apps — show me how to use it with a couple of examples, and suggest a few apps that fit how I work." Either way it looks at what you already have and what the App Store already offers, asks you a couple of questions, and sets up a first app tailored to you. This step is separate from install and lives in the host. Or just ask directly:

• *"make me a board for what I'm juggling right now"* → the AI writes it, seeds it, and opens it (persistent)
• *"make me a habit tracker"* → watch it read the guide, write t