Build an MCP App ↗

    npm install && npm run build && npm run serve
    ```

```powershell
    npm install; npm run build; npm run serve
    ```


<span class="callout-start" data-callout-type="tip"></span>
You might need to make sure that you are first in the **app folder** before running the commands above.
<span class="callout-end"></span>
<span class="step-end"></span>

<span class="step-marker" data-step-title="Test your app"></span>
Follow the instructions in [Testing your app](#testing-your-app) below. For the color picker example, start a new chat and ask Claude to provide you a color picker.

<Frame caption="Testing the color picker in Claude">
<img src="https://mintcdn.com/mcp/GU_E-622SLWFdCrP/images/quickstart-apps/test-color-picker.gif?s=09413b99bc31d7edc7f9aa22df4faa6a" alt="Testing the color picker in Claude" data-og-width="800" width="800" data-og-height="544" height="544" data-path="images/quickstart-apps/test-color-picker.gif" data-optimize="true" data-opv="3" />

<span class="step-end"></span>
<span class="steps-end"></span>

### Manual setup

If you're not using an AI coding agent, or prefer to understand the setup
process, follow these steps.

<span class="steps-start"></span>
<span class="step-marker" data-step-title="Create the project structure"></span>
A typical MCP App project separates the server code from the UI code:

<Tree>
<Tree.Folder name="my-mcp-app" defaultOpen>
  <Tree.File name="package.json" />

  <Tree.File name="tsconfig.json" />

  <Tree.File name="vite.config.ts" />

  <Tree.File name="server.ts" comment="MCP server with tool + resource" />

  <Tree.File name="mcp-app.html" comment="UI entry point" />

  <Tree.Folder name="src" defaultOpen>
    <Tree.File name="mcp-app.ts" comment="UI logic" />
  </Tree.Folder>
</Tree.Folder>
</Tree>

The server registers the tool and serves the UI resource. The UI resource will eventually be rendered in a secure iframe with deny-by-default CSP configuration. If your app has CSS and JS assets, you will need to [configure CSP](https://apps.extensions.modelcontextprotocol.io/api/documents/Patterns.html#configuring-csp-and-cors), or you can bundle your assets into the HTML with a tool like `vite-plugin-singlefile`, which is what we will do in this tutorial.
<span class="step-end"></span>

<span class="step-marker" data-step-title="Install dependencies"></span>
```bash
  npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk
  npm install -D typescript vite vite-plugin-singlefile express cors @types/express @types/cors tsx
  ```

The `ext-apps` package provides helpers for both the server side (registering tools and resources) and the client side (the `App` class for UI-to-host communication). Vite with the `vite-plugin-singlefile` plugin is used here to bundle your UI and assets into a single HTML file for convenience, but this is optional — you can use any bundler or serve unbundled files if you [configure CSP](https://apps.extensions.modelcontextprotocol.io/api/documents/Patterns.html#configuring-csp-and-cors).
<span class="step-end"></span>

<span class="step-marker" data-step-title="Configure the project"></span>
<span class="tab-group-start"></span>
<span class="tab-start" data-tab-title="package.json"></span>
  The `"type": "module"` setting enables ES module syntax. The `build` script uses the `INPUT` environment variable to tell Vite which HTML file to bundle. The `serve` script runs your server using `tsx` for TypeScript execution.

  ```json
      {
        "type": "module",
        "scripts": {
          "build": "INPUT=mcp-app.html vite build",
          "serve": "npx tsx server.ts"
        }
      }
      ```
<span class="tab-end"></span>

<span class="tab-start" data-tab-title="tsconfig.json"></span>
  The TypeScript configuration targets modern JavaScript (`ES2022`) and uses ESNext modules with bundler resolution, which works well with Vite. The `include` array covers both the server code in the root and UI code in `src/`.

  ```json
      {
        "compilerOptions": {
          "target": "ES2022",
          "module": "ESNext",
          "moduleResolution": "bundler",
          "strict": true,
          "esModuleInterop": true,
          "skipLibCheck": true,
          "outDir": "dist"
        },
        "include": ["*.ts", "src/**/*.ts"]
      }
      ```
<span class="tab-end"></span>

<span class="tab-start" data-tab-title="vite.config.ts"></span>
  ```typescript
      import { defineConfig } from "vite";
      import { viteSingleFile } from "vite-plugin-singlefile";

      export default defineConfig({
        plugins: [viteSingleFile()],
        build: {
          outDir: "dist",
          rollupOptions: {
            input: process.env.INPUT,
          },
        },
      });
      ```
<span class="tab-end"></span>
<span class="tab-group-end"></span>
<span class="step-end"></span>

<span class="step-marker" data-step-title="Build the project"></span>
With the project structure and configuration in place, continue to [Building an MCP App](#building-an-mcp-app) below to implement the server and UI.
<span class="step-end"></span>
<span class="steps-end"></span>

## Building an MCP App

Let's build a simple app that displays the current server time. This example
demonstrates the full pattern: registering a tool with UI metadata, serving the
bundled HTML as a resource, and building a UI that communicates with the server.

### Server implementation

The server needs to do two things: register a tool that includes the
`_meta.ui.resourceUri` field, and register a resource handler that serves the
bundled HTML. Here's the complete server file:

```typescript
// server.ts
console.log("Starting MCP App server...");








const server = new McpServer({
name: "My MCP App Server",
version: "1.0.0",
});

// The ui:// scheme tells hosts this is an MCP App resource.
// The path structure is arbitrary; organize it however makes sense for your app.
const resourceUri = "ui://get-time/mcp-app.html";

// Register the tool that returns the current time
registerAppTool(
server,
"get-time",
{
  title: "Get Time",
  description: "Returns the current server time.",
  inputSchema: {},
  _meta: { ui: { resourceUri } },
},
async () => {
  const time = new Date().toISOString();
  return {
    content: [{ type: "text", text: time }],
  };
},
);

// Register the resource that serves the bundled HTML
registerAppResource(
server,
resourceUri,
resourceUri,
{ mimeType: RESOURCE_MIME_TYPE },
async () => {
  const html = await fs.readFile(
    path.join(import.meta.dirname, "dist", "mcp-app.html"),
    "utf-8",
  );
  return {
    contents: [
      { uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html },
    ],
  };
},
);

// Expose the MCP server over HTTP
const expressApp = express();
expressApp.use(cors());
expressApp.use(express.json());

expressApp.post("/mcp", async (req, res) => {
const transport = new StreamableHTTPServerTransport({
  sessionIdGenerator: undefined,
  enableJsonResponse: true,
});
res.on("close", () => transport.close());
await server.connect(transport);
await transport.handleRequest(req, res, req.body);
});

expressApp.listen(3001, (err) => {
if (err) {
  console.error("Error starting server:", err);
  process.exit(1);
}
console.log("Server listening on http://localhost:3001/mcp");
});

<!-- mcp-app.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Get Time App</title>
  </head>
  <body>
    <p>
      <strong>Server Time:</strong>
      <code id="server-time">Loading...</code>
    </p>
    <button id="get-time-btn">Get Server Time</button>
    
  </body>
</html>

// src/mcp-app.ts

const serverTimeEl = document.getElementById("server-time")!;
const getTimeBtn = document.getElementById("get-time-btn")!;

const app = new App({ name: "Get Time App", version: "1.0.0" });

// Establish communication with the host
app.connect();

// Handle the initial tool result pushed by the host
app.ontoolresult = (result) => {
  const time = result.content?.find((c) => c.type === "text")?.text;
  serverTimeEl.textContent = time ?? "[ERROR]";
};

// Proactively call tools when users interact with the UI
getTimeBtn.addEventListener("click", async () => {
  const result = await app.callServerTool({
    name: "get-time",
    arguments: {},
  });
  const time = result.content?.find((c) => c.type === "text")?.text;
  serverTimeEl.textContent = time ?? "[ERROR]";
});

npm run build && npm run serve

npm run build; npm run serve

npx cloudflared tunnel --url http://localhost:3001

git clone https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps/examples/basic-host
npm install

git clone https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps\examples\basic-host
npm install

SERVERS='["http://localhost:3001/mcp"]' npm start

$env:SERVERS='["http://localhost:3001/mcp"]'; npm start