copilotkit__copilotkit/docs/snippets/shared/generative-ui/mcp-apps.mdx

import { Tabs, Tab } from "fumadocs-ui/components/tabs";

## 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](#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.

```bash
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.

<Steps>
  <Step>
    ### (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.

    ```bash
    npx create-next-app@latest
    ```
  </Step>
  <Step>
    ### Add the dependencies

    ```npm
    npm install @copilotkit/react-ui @copilotkit/react-core @copilotkit/runtime @ag-ui/mcp-apps-middleware
    ```
  </Step>
  <Step>
    ### Configure your agent

    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",
          },
        ],
      }),
    );
    ```
  </Step>
  <Step>
    ### Configure environment

    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>
  </Step>
  <Step>
    ### Configure CopilotKit Provider

    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>
                    {/* [!code highlight:3] */}
                    <CopilotKit runtimeUrl="/api/copilotkit">
                        {children}
                    </CopilotKit>
                </body>
            </html>
        );
    }
    ```
  </Step>
  <Step>
    ### Add the chat interface

    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>
        );
    }
    ```
  </Step>
  <Step>
    ### Start your UI

    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`.
  </Step>
</Steps>

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:

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

### SSE Transport

For MCP servers using Server-Sent Events:

```typescript
{
  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.