MCP Apps - Copilotkit

What is this?

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
Thread persistence — MCP Apps are stored in conversation history and restored on reconnect

Implementation

<Steps> <Step> ### Install the middleware

```bash
npm install @ag-ui/mcp-apps-middleware
```

</Step> <Step> ### Add MCP Apps middleware to your agent

Use `.use()` to attach the `MCPAppsMiddleware` to your `BuiltInAgent`:

```typescript title="app/api/copilotkit/route.ts"
import {
  CopilotRuntime,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { BuiltInAgent } from "@copilotkit/runtime/v2"; // [!code highlight]
import { MCPAppsMiddleware } from "@ag-ui/mcp-apps-middleware"; // [!code highlight]
import { NextRequest } from "next/server";

const agent = new BuiltInAgent({
  model: "openai:gpt-5.4-mini",
  prompt: "You are a helpful assistant.",
}).use( // [!code highlight:9]
  new MCPAppsMiddleware({
    mcpServers: [
      {
        type: "http",
        url: "http://localhost:3108/mcp",
        serverId: "my-server",
      },
    ],
  }),
);

const runtime = new CopilotRuntime({
  agents: { default: agent },
});

export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    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>

</Step> <Step> ### Give it a try!

That's it. MCP Apps will render automatically when the agent uses tools that have associated UI resources. No changes to your frontend are needed.

</Step> </Steps>

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"
}

Example MCP Servers

Try these open-source MCP Apps servers to get started:

https://github.com/modelcontextprotocol/ext-apps