这是构建MCP应用的最低限度Next.js起始——MCP托管的交互式UI，与工具调用一同渲染。

它是如何运作的

Next.js应用承担两个角色：

1. MCP 服务器（app/mcp/route.ts）——通过 mcp-handler 和 @modelcontextprotocol/ext-apps 注册工具和资源。
2. Widget UI（app/page.tsx）——一个MCP托管渲染的React页面，在沙盒iframe中进行渲染。MCP路由自取渲染后的页面HTML，并将其作为MCP资源提供。

useMcpApp 钩子（app/hooks/use-mcp-app.ts）通过来自@modelcontextprotocol/ext-apps的App类连接到主机，并以React状态提供工具输入/结果数据。

开始

带隧道的本地开发

MCP 应用需要一个公开的 HTTPS URL。使用 ngrok（或任何隧道）：

复制HTTPS的URL，并在.env中设置：

然后启动开发服务器：

连接主机

将您的MCP服务器URL添加到支持应用的任何MCP主机：

例如，在ChatGPT、光标或 Claude.ai：应用设置>>添加上述URL。

项目结构

关键文件

• app/mcp/route.ts — 请在此定义你的工具和资源。greet 工具是一个极简的例子。
• app/page.tsx — 你的小部件界面。

MCP Apps — Minimal Next.js Starter

A minimal Next.js starter for building MCP Apps — 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 and @modelcontextprotocol/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

pnpm install

Local development with a tunnel

MCP Apps need a public HTTPS URL. Use ngrok (or any tunnel):

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:

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 — 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
• @modelcontextprotocol/ext-apps
• mcp-handler