MCP Servers
Connect MCP servers to your Built-in Agent, with support for persistent clients, tool caching, and dynamic auth.
What are MCP Servers?
MCP (Model Context Protocol) servers provide additional tools and capabilities to your agent. The Built-in Agent supports connecting to MCP servers via HTTP or SSE transports.
When should I use this?
- You want to connect your agent to existing MCP-compatible tool servers
- You need to add capabilities from third-party MCP providers
- You want to share tools across multiple agents or applications
SSE transport
Connect a server that serves the SSE (Server-Sent Events) transport:
import { BuiltInAgent } from "@copilotkit/runtime/v2";
const builtInAgent = new BuiltInAgent({
model: "openai:gpt-6-luna",
mcpServers: [
{
type: "sse",
url: "https://my-mcp-server.example.com/sse",
},
],
});Authentication headers
Pass custom headers for authentication:
const builtInAgent = new BuiltInAgent({
model: "openai:gpt-6-luna",
mcpServers: [
{
type: "sse",
url: "https://my-mcp-server.example.com/sse",
headers: {
Authorization: `Bearer ${process.env.MCP_API_KEY}`,
},
},
],
});HTTP transport
The HTTP (Streamable HTTP) transport uses standard HTTP requests:
const builtInAgent = new BuiltInAgent({
model: "openai:gpt-6-luna",
mcpServers: [
{
type: "http",
url: "https://my-mcp-server.example.com/mcp",
},
],
});The HTTP transport also accepts optional options for advanced configuration of the underlying StreamableHTTPClientTransport.
Multiple servers
Connect multiple MCP servers. Tools from all servers are available to the agent:
const builtInAgent = new BuiltInAgent({
model: "openai:gpt-6-luna",
mcpServers: [
{
type: "sse",
url: "https://search-mcp.example.com/sse",
},
{
type: "sse",
url: "https://db-mcp.example.com/sse",
headers: { Authorization: `Bearer ${process.env.DB_MCP_KEY}` },
},
{
type: "http",
url: "https://analytics-mcp.example.com/mcp",
},
],
});If a server cannot connect, or its tool list fails, the agent skips that server for the run. The server log shows a [CopilotKit] MCP server ... failed to connect error. The run continues with the other tools.
Tool name collisions
Two servers can expose tools with the same name. For example, a staging server and a production server expose the same tools. The agent keeps every copy. When a name collides, each MCP copy gets a prefix, and the agent logs a warning:
const builtInAgent = new BuiltInAgent({
model: "openai:gpt-6-luna",
mcpServers: [
{ type: "http", url: "https://staging.example.com/mcp", name: "staging" },
{ type: "http", url: "https://prod.example.com/mcp", name: "production" },
],
});
// Both servers expose `search`, so the model sees `staging_search` and `production_search`.- Only names that collide get a prefix. Other tools keep their names.
- If an MCP tool has the same name as one of your own tools, your tool keeps the name, and the MCP tool gets the prefix.
- If a server has no
name, the prefix ismcp<N>, where N is the server's position inmcpClientsand thenmcpServers, from 1. Entries inmcpClientshave noname, so they always usemcp<N>. - Characters other than letters, digits,
_and-innamebecome_. - If a prefixed name is already in use, a number is added, for example
production_search_2. This happens when two servers have the samename, so give each server a differentname. - A tool renderer that you register in the frontend matches only the exposed name. If
searchbecomesproduction_search, register the renderer forproduction_search.
Combining with server tools
MCP servers work alongside defineTool server tools. The agent sees all tools from both sources:
import { BuiltInAgent, defineTool } from "@copilotkit/runtime/v2";
import { z } from "zod";
const customTool = defineTool({
name: "getUser",
description: "Get the current user",
parameters: z.object({}),
execute: async () => {
return { name: "Jane", role: "Admin" };
},
});
const builtInAgent = new BuiltInAgent({
model: "openai:gpt-6-luna",
tools: [customTool], // Your custom tools
mcpServers: [ // Plus tools from MCP servers
{ type: "sse", url: "https://search-mcp.example.com/sse" },
],
});User-managed MCP clients
The mcpServers approach creates a fresh MCP connection on every agent run. For latency-sensitive setups (or when you need persistent connections, dynamic auth, or tool caching), use mcpClients instead. You create and manage the MCP client yourself; the agent just calls .tools() to get tool definitions.
import { BuiltInAgent } from "@copilotkit/runtime/v2";
import { createMCPClient } from "@ai-sdk/mcp";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
// Create a persistent client at startup
const transport = new StreamableHTTPClientTransport(
new URL("https://my-mcp-server.example.com/mcp"),
);
const client = await createMCPClient({ transport });
const builtInAgent = new BuiltInAgent({
model: "openai:gpt-6-luna",
mcpClients: [client],
});Unlike mcpServers, the agent never creates or closes these clients. You control the full lifecycle.
Tool caching
By default, .tools() fetches from the MCP server on every agent run. To cache tools at startup:
const client = await createMCPClient({ transport });
let cachedTools: Awaited<ReturnType<typeof client.tools>> | null = null;
const warmupPromise = client.tools().then(tools => { cachedTools = tools; });
const provider = {
async tools() {
if (cachedTools) return cachedTools;
await warmupPromise;
return cachedTools!;
},
};
const builtInAgent = new BuiltInAgent({
model: "openai:gpt-6-luna",
mcpClients: [provider],
});Tool discovery runs once in the background. The first request waits only if warmup hasn't finished yet; subsequent requests return instantly from cache.
Dynamic authentication
When using a persistent client, auth tokens may expire between requests. Handle this inside your provider:
const provider = {
async tools() {
if (isTokenExpired()) {
await currentClient.close();
currentClient = await createMCPClient({
transport: makeTransport(getFreshToken()),
});
}
return currentClient.tools();
},
};
const builtInAgent = new BuiltInAgent({
model: "openai:gpt-6-luna",
mcpClients: [provider],
});You only pay the reconnection cost when the token actually expires, not on every request.
Combining with mcpServers
mcpClients and mcpServers can be used together. The agent merges the tools from both. On a name collision, both tools stay and each gets a prefix, as Tool name collisions describes:
const builtInAgent = new BuiltInAgent({
model: "openai:gpt-6-luna",
mcpClients: [persistentClient], // User-managed, persistent
mcpServers: [ // Agent-managed, per-request
{ type: "sse", url: "https://other-mcp.example.com/sse" },
],
});Transport reference
| Property | SSE | HTTP | Description |
|---|---|---|---|
type | "sse" | "http" | Transport type |
url | string | string | MCP server URL |
headers | Record<string, string> | not supported | Custom HTTP headers (SSE only) |
options | not supported | StreamableHTTPClientTransportOptions | Transport options (HTTP only) |
How is this guide?