MCP Apps

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

Install the middleware

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

Add MCP Apps middleware to your agent

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

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

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.

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.

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

Example MCP Servers

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

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

2087950ee