experimental_createMCPClient()

Creates a lightweight Model Context Protocol (MCP) client that connects to an MCP server. The client's primary purpose is tool conversion between MCP tools and AI SDK tools.

It currently does not support accepting notifications from an MCP server, and custom configuration of the client.

This feature is experimental and may change or be removed in the future.

Import 

import { experimental_createMCPClient } from "ai"

API Signature

Parameters

config:

MCPClientConfig
MCPClientConfig

transport:

TransportConfig = MCPTransport | McpSSEServerConfig
MCPTransport

start:

() => Promise<void>

send:

(message: JSONRPCMessage) => Promise<void>

close:

() => Promise<void>

onclose:

() => void

onerror:

(error: Error) => void

onmessage:

(message: JSONRPCMessage) => void
McpSSEServerConfig

type:

'sse'

url:

string

headers?:

Record<string, string>

name?:

string

onUncaughtError?:

(error: unknown) => void

Returns

Returns a Promise that resolves to an MCPClient with the following methods:

tools:

async (options?: { schemas?: TOOL_SCHEMAS }) => Promise<McpToolSet<TOOL_SCHEMAS>>
options

schemas?:

TOOL_SCHEMAS

close:

async () => void

Example 

import { experimental_createMCPClient, generateText } from 'ai';
import { openai } from '@ai-sdk/openai';


try {
  const client = await experimental_createMCPClient({
    transport: {
      type: 'stdio',
      command: 'node server.js',
    },
  });


  const tools = await client.tools();


  const response = await generateText({
    model: openai('gpt-4o-mini'),
    tools,
    messages: [{ role: 'user', content: 'Query the data' }],
  });


  console.log(response);
} finally {
  await client.close();
}

Error Handling

The client throws MCPClientError for:

  • Client initialization failures
  • Protocol version mismatches
  • Missing server capabilities
  • Connection failures

For tool execution, errors are propagated as CallToolError errors.

For unknown errors, the client exposes an onUncaughtError callback that can be used to manually log or handle errors that are not covered by known error types.