MCP Apps

Render interactive UI components from MCP servers directly in your chat interface.

Prerequisites#

Before you begin, you'll need the following:

An OpenAI API key (or API key for your preferred LLM provider)
Node.js 20+
Your favorite package manager
An MCP server running (see Example MCP Servers below)

What are MCP Apps?#

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:

Zero frontend code - UI components are served by the MCP server
Full interactivity - Components can use HTML, CSS, and JavaScript
Secure sandboxing - Content runs in isolated iframes
Direct server communication - The middleware securely proxies communication between the rendered UI and the MCP server, enabling real-time interactions
Thread persistence - MCP Apps are stored in conversation history and restored on reconnect

Quickstart#

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

Getting started#

If you're looking to add an MCP App into an existing application, let's walk through the process.

(Optional) Create a new application#

We'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.

npx create-next-app@latest

Add the dependencies#

npm install @copilotkit/react-core @copilotkit/runtime @ag-ui/mcp-apps-middleware

Configure your agent#

Add your agent configuration to CopilotRuntime with your MCP server configurations:

This same process will work with any agent configuration.

touch app/api/copilotkit/route.ts

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);
};

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.

Alternatively, if you want to scope MCP Apps to specific agents, you can use MCPAppsMiddleware directly on the agent via .use():

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",
      },
    ],
  }),
);

Configure environment#

Create a .env.local file in your frontend directory and add your API key:

.env.local

OPENAI_API_KEY=your_openai_api_key

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.

Configure CopilotKit Provider#

Wrap your application with the CopilotKit provider:

app/layout.tsx

import { CopilotKit } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/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 chat interface#

Add the CopilotSidebar component to your page:

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 your UI#

Start the development server:

npm run dev

pnpm dev

yarn dev

bun dev

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.

Transport Types#

The middleware supports two transport types:

HTTP Transport#

For MCP servers using HTTP-based communication:

{
  type: "http",
  url: "http://localhost:3101/mcp",
  serverId: "my-http-server"
}

SSE Transport#

For MCP servers using Server-Sent Events:

{
  type: "sse",
  url: "https://mcp.example.com/sse",
  headers: {
    "Authorization": "Bearer token"
  },
  serverId: "my-sse-server"
}

Threading Support#

MCP Apps integrate fully with CopilotKit's threading system:

Persistence - When you save a thread, MCP Apps are stored as part of the conversation history
Restoration - Loading a thread restores all MCP Apps with their original state
Server ID stability - Using consistent serverId values ensures MCP Apps load correctly across sessions

Example MCP Servers#

Try 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.