docs/snippets/shared/generative-ui/mcp-apps.mdx
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
Before you begin, you'll need the following:
MCP Apps are MCP servers that expose tools with associated UI resources. When the agent calls one of these tools, CopilotKit automatically fetches and renders the UI component in the chat - no additional frontend code required.
Key benefits:
Want to try MCP Apps out with a new application? We have a pre-built example app you can use via our CLI.
npx copilotkit create -f mcp-apps
If you're looking to add an MCP App into an existing application, let's walk through the process.
<Steps> <Step> ### (Optional) Create a new applicationWe'll be starting from scratch for this example, but feel free to skip this step if you already have an application.
For the sake of this example, we'll be using Next.js but the process will slot into any frontend React framework.
```bash
npx create-next-app@latest
```
```npm
npm install @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime @ag-ui/mcp-apps-middleware
```
Add your agent configuration to CopilotRuntime with your MCP server configurations:
<Callout>
This same process will work with any agent configuration.
</Callout>
```bash
touch app/api/copilotkit/route.ts
```
```typescript title="app/api/copilotkit/route.ts"
import {
CopilotRuntime,
ExperimentalEmptyAdapter,
copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/runtime/v2";
import { NextRequest } from "next/server";
// 1. Create your agent
const agent = new BuiltInAgent({
model: "openai/gpt-5.4",
prompt: "You are a helpful assistant.",
});
// 2. Create a service adapter, empty if not relevant
const serviceAdapter = new ExperimentalEmptyAdapter();
// 3. Create the runtime with mcpApps configured
const runtime = new CopilotRuntime({
agents: {
default: agent,
},
mcpApps: {
servers: [
{
type: "http",
url: "http://localhost:3108/mcp",
serverId: "my-server", // Recommended: stable identifier
},
],
},
});
// 4. Create the API route
export const POST = async (req: NextRequest) => {
const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
runtime,
serviceAdapter,
endpoint: "/api/copilotkit",
});
return handleRequest(req);
};
```
<Callout type="info" title="Server ID">
Always provide a `serverId` for production deployments. Without it, CopilotKit generates a hash from the server URL. If your URL changes (e.g., different environments), previously stored MCP Apps in conversation history won't load correctly.
</Callout>
Alternatively, if you want to scope MCP Apps to specific agents, you can use `MCPAppsMiddleware` directly on the agent via `.use()`:
```typescript title="app/api/copilotkit/route.ts"
import { MCPAppsMiddleware } from "@ag-ui/mcp-apps-middleware";
const agent = new BuiltInAgent({
model: "openai/gpt-5.4",
prompt: "You are a helpful assistant.",
}).use(
new MCPAppsMiddleware({
mcpServers: [
{
type: "http",
url: "http://localhost:3108/mcp",
serverId: "my-server",
},
],
}),
);
```
Create a `.env.local` file in your frontend directory and add your API key:
```plaintext title=".env.local"
OPENAI_API_KEY=your_openai_api_key
```
<Callout type="info" title="What about other models?">
The example is configured to use OpenAI's GPT-4o by default, but you can modify the BuiltInAgent to use any language model supported by CopilotKit.
</Callout>
Wrap your application with the CopilotKit provider:
```tsx title="app/layout.tsx"
// [!code highlight:2]
import { CopilotKit } from "@copilotkit/react-core/v2";
import "@copilotkit/react-ui/v2/styles.css";
// ...
export default function RootLayout({ children }: {children: React.ReactNode}) {
return (
<html lang="en">
<body>
<CopilotKit runtimeUrl="/api/copilotkit">
{children}
</CopilotKit>
</body>
</html>
);
}
```
Add the CopilotSidebar component to your page:
```tsx title="app/page.tsx"
"use client";
import { CopilotSidebar } from "@copilotkit/react-core/v2";
export default function Page() {
return (
<main>
<h1>Your App</h1>
<CopilotSidebar />
</main>
);
}
```
Start the development server:
<Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
<Tab value="npm">
```bash
npm run dev
```
</Tab>
<Tab value="pnpm">
```bash
pnpm dev
```
</Tab>
<Tab value="yarn">
```bash
yarn dev
```
</Tab>
<Tab value="bun">
```bash
bun dev
```
</Tab>
</Tabs>
Your application will be available at `http://localhost:3000`.
That's it! MCP Apps will now render automatically when the agent uses tools that have associated UI resources.
The middleware supports two transport types:
For MCP servers using HTTP-based communication:
{
type: "http",
url: "http://localhost:3101/mcp",
serverId: "my-http-server"
}
For MCP servers using Server-Sent Events:
{
type: "sse",
url: "https://mcp.example.com/sse",
headers: {
"Authorization": "Bearer token"
},
serverId: "my-sse-server"
}
MCP Apps integrate fully with CopilotKit's threading system:
serverId values ensures MCP Apps load correctly across sessionsTry these open-source MCP Apps servers to get started:
https://github.com/modelcontextprotocol/ext-apps
This repo contains multiple demo servers with tools like budget allocators, data visualizations, and interactive dashboards.