# MCP Servers

> Connect MCP servers to your Built-in Agent, with support for persistent clients, tool caching, and dynamic auth.

## What are MCP Servers? [#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? [#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 [#sse-transport]

Connect a server that serves the SSE (Server-Sent Events) transport:

```typescript title="src/copilotkit.ts"
import { BuiltInAgent } from "@copilotkit/runtime/v2";

const builtInAgent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
  mcpServers: [
    {
      type: "sse", // [!code highlight]
      url: "https://my-mcp-server.example.com/sse",
    },
  ],
});
```

### Authentication headers [#authentication-headers]

Pass custom headers for authentication:

```typescript
const builtInAgent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
  mcpServers: [
    {
      type: "sse",
      url: "https://my-mcp-server.example.com/sse",
      headers: { // [!code highlight:3]
        Authorization: `Bearer ${process.env.MCP_API_KEY}`,
      },
    },
  ],
});
```

## HTTP transport [#http-transport]

The HTTP (Streamable HTTP) transport uses standard HTTP requests:

```typescript
const builtInAgent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
  mcpServers: [
    {
      type: "http", // [!code highlight]
      url: "https://my-mcp-server.example.com/mcp",
    },
  ],
});
```

The HTTP transport also accepts optional `options` for advanced configuration of the underlying `StreamableHTTPClientTransport`.

## Multiple servers [#multiple-servers]

Connect multiple MCP servers. Tools from all servers are available to the agent:

```typescript
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 [#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:

```typescript
const builtInAgent = new BuiltInAgent({
  model: "openai:gpt-6-luna",
  mcpServers: [
    { type: "http", url: "https://staging.example.com/mcp", name: "staging" }, // [!code highlight]
    { type: "http", url: "https://prod.example.com/mcp", name: "production" }, // [!code highlight]
  ],
});
// 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 is `mcp<N>`, where N is the server's position in `mcpClients` and then `mcpServers`, from 1. Entries in `mcpClients` have no `name`, so they always use `mcp<N>`.
- Characters other than letters, digits, `_` and `-` in `name` become `_`.
- If a prefixed name is already in use, a number is added, for example `production_search_2`. This happens when two servers have the same `name`, so give each server a different `name`.
- A tool renderer that you register in the frontend matches only the exposed name. If `search` becomes `production_search`, register the renderer for `production_search`.

## Combining with server tools [#combining-with-server-tools]

MCP servers work alongside `defineTool` server tools. The agent sees all tools from both sources:

```typescript
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 [#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.

```typescript
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], // [!code highlight]
});
```

Unlike `mcpServers`, the agent **never** creates or closes these clients. You control the full lifecycle.

### Tool caching [#tool-caching]

By default, `.tools()` fetches from the MCP server on every agent run. To cache tools at startup:

```typescript
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], // [!code highlight]
});
```

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 [#dynamic-authentication]

When using a persistent client, auth tokens may expire between requests. Handle this inside your provider:

```typescript
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 [#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](#tool-name-collisions) describes:

```typescript
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 [#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) |
