---
title: "MCP Apps Next.js Starter"
description: "MCP Apps are similar to ChatGPT apps, but are a provider-agnostic open standard for embedded UIs. "
url: "https://vercel.com/templates/next.js/mcp-apps-next-js-starter"
links:
  repository: "https://github.com/vercel-labs/mcp-apps-nextjs-starter"
  demo: "https://mcp-apps-nextjs-starter.vercel.app/"
  deploy: "https://vercel.com/new/clone?demo-title=MCP+Apps+Next.js+Starter&demo-description=MCP+Apps+are+similar+to+ChatGPT+apps%2C+but+are+a+provider-agnostic+open+standard+for+embedded+UIs.+&demo-url=https%3A%2F%2Fmcp-apps-nextjs-starter.vercel.app%2F&demo-image=%2F%2Fimages.ctfassets.net%2Fe5382hct74si%2F5Gux1oZKPoVW7iwevPSflj%2Fb0c7c6a3f23d6409302175cdf3905612%2FCleanShot_2026-03-05_at_08.21.53_2x.png&project-name=MCP+Apps+Next.js+Starter&repository-name=mcp-apps-next-js-starter&repository-url=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fmcp-apps-nextjs-starter&from=templates&skippable-integrations=1&root-directories=List+of+directory+paths+for+the+directories+to+clone+into+projects&project-names=Comma+separated+list+of+project+names%2Cto+match+the+root-directories"
---

# MCP Apps Next.js Starter

MCP Apps are similar to ChatGPT apps, but are a provider-agnostic open standard for embedded UIs.

# MCP Apps — Minimal Next.js Starter

A minimal [Next.js](https://nextjs.org) starter for building [MCP Apps](https://modelcontextprotocol.io) — interactive UIs that MCP hosts render alongside tool calls.

## How it works

The Next.js app serves two roles:

1. **MCP server** (`app/mcp/route.ts`) — registers tools and resources via [`mcp-handler`](https://github.com/vercel/mcp-handler) and [`@modelcontextprotocol/ext-apps`](https://github.com/anthropics/ext-apps).
2. **Widget UI** (`app/page.tsx`) — a React page that MCP hosts render inside a sandboxed iframe. The MCP route self-fetches the rendered page HTML and serves it as an MCP resource.

The `useMcpApp` hook (`app/hooks/use-mcp-app.ts`) connects to the host via the `App` class from `@modelcontextprotocol/ext-apps` and provides tool input/result data as React state.

## Getting started

```bash
pnpm install
```

### Local development with a tunnel

MCP Apps need a public HTTPS URL. Use [ngrok](https://ngrok.com) (or any tunnel):

```bash
ngrok http 3000
```

Copy the HTTPS URL and set it in `.env`:

```
BASE_URL=https://xxxx-xxx-xxx.ngrok-free.app
```

Then start the dev server:

```bash
pnpm dev
```

### Connect to a host

Add your MCP server URL to any MCP host that supports Apps:

```
https://xxxx-xxx-xxx.ngrok-free.app/mcp
```

For example, in ChatGPT, Cursor, or Claude.ai: Settings > Apps > add the URL above.

## Project structure

```
app/
  page.tsx              — Homepage (widget UI)
  about/page.tsx        — Example sub-page (navigation demo)
  counter/page.tsx      — Example sub-page (interactivity demo)
  mcp/route.ts          — MCP server endpoint
  hooks/use-mcp-app.ts  — React hook for the MCP Apps bridge
  layout.tsx            — Root layout with iframe bootstrap patches
baseUrl.ts              — Public URL resolver (tunnel / Vercel)
middleware.ts           — CORS headers for cross-origin iframe access
next.config.ts          — assetPrefix for iframe asset loading
```

## Key files

- **`app/mcp/route.ts`** — Define your tools and resources here. The `greet` tool is a minimal example.
- **`app/page.tsx`** — Your widget UI. Edit this like any Next.js page. It receives tool data via `useMcpApp()`.
- **`app/hooks/use-mcp-app.ts`** — Singleton `App` bridge with `sessionStorage` persistence. Provides `toolInput`, `toolResult`, and `connected` state.

## Deploy

Deploy to [Vercel](https://vercel.com/new) — no additional configuration needed. The `BASE_URL` is automatically derived from Vercel's environment variables in production.

Once deployed, connect it to any MCP host using:

```
https://your-app.vercel.app/mcp
```

For example, in ChatGPT, Cursor, or Claude.ai: Settings > Apps > add the URL above as a connector.

## Learn more

- [MCP Apps specification](https://modelcontextprotocol.io)
- [@modelcontextprotocol/ext-apps](https://github.com/anthropics/ext-apps)
- [mcp-handler](https://github.com/vercel/mcp-handler)

---

## Additional documentation

The [Vercel Knowledge Base](https://vercel.com/kb) contains guides and answers to common questions about Vercel, including deployment, framework configuration, domains, caching, and troubleshooting.