MCP Apps

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

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#

Run and connect your agent#

You'll need to run your agent and connect it to CopilotKit before proceeding. If you haven't done so already, you can follow the instructions in the Getting Started guide.

If you don't already have an agent, you can use the coagent starter as a starting point as this guide uses it as a starting point.

Add MCP Apps middleware to your agent#

Install the middleware package and add it to your LangGraphAgent with .use():

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

app/api/copilotkit/route.ts

import {
  CopilotRuntime,
  ExperimentalEmptyAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";
import { LangGraphAgent } from "@copilotkit/runtime";
import { MCPAppsMiddleware } from "@ag-ui/mcp-apps-middleware";
import { NextRequest } from "next/server";

const agent = new LangGraphAgent({
deploymentUrl: process.env.LANGGRAPH_DEPLOYMENT_URL || "http://localhost:8123",
  graphId: "sample_agent",
langsmithApiKey: process.env.LANGSMITH_API_KEY || "",
});

agent.use(
  new MCPAppsMiddleware({
    mcpServers: [
      {
        type: "http",
        url: "https://mcp.excalidraw.com",
        serverId: "excalidraw",
      },
    ],
  }),
);

export const POST = async (req: NextRequest) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    endpoint: "/api/copilotkit",
    serviceAdapter: new ExperimentalEmptyAdapter(),
    runtime: new CopilotRuntime({
      agents: {
        default: agent,
      },
    }),
  });

  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.

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 agent code or 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