@modelcontextprotocol/ext-apps

This repo contains the SDK and specification for MCP Apps Extension (SEP-1865).

MCP Apps are proposed standard inspired by MCP-UI and OpenAI's Apps SDK to allow MCP Servers to display interactive UI elements in conversational MCP clients / chatbots.

This repo provides:

• specification/draft/apps.mdx: The Draft Extension Specification. It's still... in flux! Feedback welcome! (also see discussions in SEP-1865).

• types.ts: Types of JSON-RPC messages used to communicate between Apps & their host

  • Note that MCP Apps also use some standard MCP messages (e.g. tools/call for the App to trigger actions on its originating Server - these calls are proxied through the Host), but these types are the additional messages defined by the extension

• examples/simple-example: Example Server + Apps

  • server.ts: MCP server with three tools that declare UI resources of Apps to be show in the chat when called
  • ui-react.tsx: React App returned by the create-ui-react tool shows how to use the useApp hook to register MCP callbacks
  • ui-vanilla.tsx: vanilla App returned by the create-ui-vanilla
  • ui-raw.tsx: same as vanilla App but doesn't use the SDK runtime (just its types)

• examples/simple-host: bare-bone examples on how to host MCP Apps (both use the AppBridge class to talk to a hosted App)

  • example-host-react.tsx uses React (esp. AppRenderer.tsx)
  • example-host-vanilla.tsx doesn't use React

• message-transport: PostMessageTransport class that uses postMessage to exchange JSON-RPC messages between windows / iframes

• app.ts: App class used by an App to talk to its host

• app-bridge.ts: AppBridge class used by the host to talk to a single App

• Soon: more examples!

What this repo does NOT provide:

• There's no supported host implementation in this repo (beyond the examples/simple-host example)
  • We have contributed a tentative implementation of hosting / iframing / sandboxing logic to the MCP-UI repository, and expect OSS clients may use it, while other clients might roll their own hosting logic.

Using the SDK

Run examples

Run the examples in this repo end-to-end:

npm i
npm start

open http://localhost:8080/

Note

Please bear with us while we add more examples!

Using the SDK in your project

This repo is in flux and isn't published to npm yet: when it is, it will use the @modelcontextprotocol/ext-apps package.

In the meantime you can depend on the SDK library in a Node.js project by installing it w/ its git URL:

npm install -S git+https://github.com/modelcontextprotocol/ext-apps.git

Your package.json will then look like:

{
  ...
  "dependencies": {
    ...
    "@modelcontextprotocol/ext-apps": "git+https://github.com/modelcontextprotocol/ext-apps.git"
  }
}

Note

The build tools (esbuild, tsx, typescript) are in dependencies rather than devDependencies. This is intentional: it allows the prepare script to run when the package is installed from git, since npm doesn't install devDependencies for git dependencies.

Once the package is published to npm with pre-built dist/, these can be moved back to devDependencies.