feat(runtime): configurable MCP server on BuiltInAgent (Bearer + per-call user header)

[lukasmoschitz]

Summary

Closes CPK-7526.

@copilotkit/runtime/v2's BuiltInAgent already supported MCP servers, but only with static headers set at client construction. CopilotKit Intelligence's /mcp endpoint requires a two-axis auth contract that breaks under static headers:

1. Static project Bearer — Authorization: Bearer cpk-{projectId}_{shortToken}_{longToken}. Same on every call.
2. Per-call end-user header — X-Cpki-User-Id. Fresh per outbound MCP HTTP request — never cached. Determines which user's persistent bash sandbox + /threads view a call sees.

Without per-call user-id, every demo session for a given project would share one bash sandbox, breaking the user-isolation contract that cpki.shell_contexts and ThreadsFs enforce on the platform side.

This PR adds the missing per-call resolver hook and is the precondition for CPK-7527 (Phase 4b SL integration), which wires it into Intelligence/demos/simple-agent.

What's in here

Public API surface

import {
  BuiltInAgent,
  INTELLIGENCE_USER_ID_HEADER,
  // re-exported from @ai-sdk/mcp:
  type MCPClient,
  type MCPTransport,
  type OAuthClientProvider,
} from "@copilotkit/runtime/v2";

new BuiltInAgent({
  model: "openai/gpt-4o",
  mcpServers: [{
    type: "http",
    url: `${process.env.INTELLIGENCE_API_URL}/mcp`,
    authToken: process.env.INTELLIGENCE_API_KEY!,
    getHeaders: ({ requestHeaders }) => {
      const userId = requestHeaders[INTELLIGENCE_USER_ID_HEADER]?.trim();
      if (!userId) throw new Error("missing user-id");
      return { [INTELLIGENCE_USER_ID_HEADER]: userId };
    },
  }],
});

• Unified MCPClientConfig shape mirrors @ai-sdk/mcp's MCPTransportConfig (single discriminated type: "http" | "sse", url, headers, authProvider) plus two CopilotKit extensions: authToken (static Bearer shorthand) and getHeaders (per-call resolver invoked on every outbound HTTP request — initialize, tools/list, tools/call, reconnects).
• MCPRequestContext carries requestHeaders (snapshot of the agent's per-run forwarded headers), input, and mcpServerUrl.
• MCPHeaderResolverError wraps resolver throws so RUN_ERROR attributes the failure to the resolver via ES2022 Error.cause.
• BuiltInAgent.headers: Record<string, string> = {} is now declared on the class. The runtime's existing extractForwardableHeaders feature-detect (if (agent.headers) in configureAgentForRequest) only forwards headers to agents that already declare a truthy field — initializing to {} activates that path so the BFF's per-request headers reach the resolver via context.
• INTELLIGENCE_USER_ID_HEADER constant exported as the canonical header name ("x-cpki-user-id") — re-exported through both intelligence-platform and v2/runtime barrels.

Architecture

The agent's MCP layer now sits directly on @ai-sdk/mcp's stable surface (createMCPClient, MCPClient, MCPTransport) instead of bypassing it to @modelcontextprotocol/sdk. The agent module no longer imports @modelcontextprotocol/sdk at all — that's confined to a small CopilotKitMCPTransport class that implements Vercel's MCPTransport interface and is only instantiated when a getHeaders resolver is present.

For static-only configs (no per-call hooks), the config is handed straight to createMCPClient and Vercel's built-in HttpMCPTransport / SseMCPTransport handle the wire.

MCPClient, MCPTransport, OAuthClientProvider, OAuthTokens, and UnauthorizedError are re-exported from @copilotkit/runtime/v2 so consumers don't need a direct @ai-sdk/mcp dependency.

Side-effect bug fix: SSE static headers

The pre-existing direct-SDK construction passed serverConfig.headers as the wrong-shape options arg to SSEClientTransport, and the SDK silently ignored it — auth on SSE simply didn't work. Vercel's SseMCPTransport correctly applies headers via its commonHeaders() pipeline. The new architecture inherits the fix; a regression test in mcp-servers-integration.test.ts proves static headers now reach the wire on the SSE path.

What's intentionally NOT in here

• Demo wiring in Intelligence/demos/simple-agent (CPK-7527).
• MCP support for LangGraph / Mastra runtimes — different integration points; not this ticket.
• Server-side /mcp route changes in Intelligence (already shipped on mme/integrate-sl).

Notes for reviewers

• Public-API addition: BuiltInAgent.headers is a real public field, not just an ad-hoc property. It's load-bearing for the runtime's existing header-forwarding feature-detect.
• Test header inspection: aimock redacts Authorization to [REDACTED] in its journal, so tests that need to verify the actual outgoing Bearer use a vi.spyOn(globalThis, "fetch") recorder instead of the journal. The x-cpki-user-id header isn't redacted, so per-call user-id assertions read from the journal directly.
• No toMCPServer() helper. Earlier iterations of this PR shipped a CopilotKitIntelligence.toMCPServer() shortcut. It conflated thread management (the class's actual job) with MCP transport configuration and baked in opinionated behavior that not every deployment will want; dropped in favor of the inline pattern shown above using the exported INTELLIGENCE_USER_ID_HEADER constant. Same line count as the helper-call form, more flexible.
• Pre-existing tsc --noEmit OOM: pnpm nx run @copilotkit/runtime:check-types runs out of heap on main at 8GB. Reproduces on a clean checkout without any changes from this PR. Worth tracking as a separate issue. Build (tsdown) is unaffected; the full vitest suite (1419 tests, 101 files) passes.

Test plan

• pnpm nx run @copilotkit/runtime:test -- mcp-servers-integration — 15 cases pass (8 existing + 6 per-call/static-header + 1 new SSE regression test)
• pnpm nx run @copilotkit/runtime:test -- mcp-clients — 8 cases pass (existing user-managed-clients suite, including MCPClient ↔ MCPClientProvider type-compat check)
• pnpm nx run @copilotkit/runtime:test --skip-nx-cache — full suite 1419/1419
• pnpm nx run @copilotkit/runtime:build — tsdown clean
• oxlint on changed files — 0 errors
• Manual end-to-end against a local Intel server + simple-agent BFF — deferred to CPK-7527 since the demo wiring lives there

[linear]

CPK-7526 @copilotkit/runtime/v2: configurable MCP server on BuiltInAgent (Bearer + per-call user header)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
chat-with-your-data	Ready	Preview, Comment	May 7, 2026 0:46am
docs	Ready	Preview, Comment	May 7, 2026 0:46am
form-filling	Ready	Preview, Comment	May 7, 2026 0:46am
research-canvas	Ready	Preview, Comment	May 7, 2026 0:46am
travel	Ready	Preview, Comment	May 7, 2026 0:46am

[github-actions]

📣 Social Copy Generator

Generate social media copies (Twitter/X, LinkedIn, Blog Post) for this PR using Claude.

• Generate social media copies

[pkg-pr-new]

Open in StackBlitz

@copilotkit/a2ui-renderer

pnpm add https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/a2ui-renderer@4420

@copilotkit/agentcore-runner

pnpm add https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/agentcore-runner@4420

@copilotkitnext/angular

pnpm add https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkitnext/angular@4420

@copilotkit/core

pnpm add https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/core@4420

@copilotkit/react-core

pnpm add https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/react-core@4420

@copilotkit/react-native

pnpm add https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/react-native@4420

@copilotkit/react-textarea

pnpm add https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/react-textarea@4420

@copilotkit/react-ui

pnpm add https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/react-ui@4420

@copilotkit/runtime

pnpm add https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/runtime@4420

@copilotkit/runtime-client-gql

pnpm add https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/runtime-client-gql@4420

@copilotkit/sdk-js

pnpm add https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/sdk-js@4420

@copilotkit/shared

pnpm add https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/shared@4420

@copilotkit/sqlite-runner

pnpm add https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/sqlite-runner@4420

@copilotkit/voice

pnpm add https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/voice@4420

@copilotkit/web-inspector

pnpm add https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/web-inspector@4420

commit: 5dad3de

[BenTaylorDev]

Things Claude wanted me to tell you:

• The cast in handlers/intelligence/run.ts:87 — (agent as unknown as { user?: { id, name } }).user = ....
  MiddlewareCapableAgent already extends AbstractAgent with user? in agent-utils.ts:16. The handler should
  accept that type (or a narrow shared type) instead of double-casting. Loses type safety for no real reason.
• INTELLIGENCE_USER_ID_HEADER is hard-coded inside client.ts:9 — fine for encapsulation, but the helper is
  closed over a single header name. If/when a self-hosted Intelligence variant wants a different name, this
  becomes a fork point. Probably worth a comment that it's deliberately not configurable.
• Concurrency assumption is implicit: setting agent.user before agent.run() only works because
  cloneAgentForRequest returns a fresh instance per request. Worth a one-liner on BuiltInAgent.user saying
  "set per request on a cloned agent; do not set on a shared singleton."
• Doc-table footnote: the SSE row says "if you need it, use HTTP" but the SSE bug-fix commit means SSE now
  applies static headers correctly. A tiny note that SSE supports static headers and only getHeaders is
  HTTP-only would prevent confusion.