experimental_createMCPClient()

Creates a lightweight Model Context Protocol (MCP) client that connects to an MCP server. The client provides:

  • Tools: Automatic conversion between MCP tools and AI SDK tools
  • Resources: Methods to list, read, and discover resource templates from MCP servers
  • Prompts: Methods to list available prompts and retrieve prompt messages
  • Elicitation: Support for handling server requests for additional input during tool execution

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-sdk/mcp"

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
MCPTransportConfig

type:

'sse' | 'http

url:

string

headers?:

Record<string, string>

authProvider?:

OAuthClientProvider

name?:

string

onUncaughtError?:

(error: unknown) => void

capabilities?:

ClientCapabilities

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

listResources:

async (options?: { params?: PaginatedRequest['params']; options?: RequestOptions; }) => Promise<ListResourcesResult>
options

params?:

PaginatedRequest['params']

options?:

RequestOptions

readResource:

async (args: { uri: string; options?: RequestOptions; }) => Promise<ReadResourceResult>
args

uri:

string

options?:

RequestOptions

listResourceTemplates:

async (options?: { options?: RequestOptions; }) => Promise<ListResourceTemplatesResult>
options

options?:

RequestOptions

listPrompts:

async (options?: { params?: PaginatedRequest['params']; options?: RequestOptions; }) => Promise<ListPromptsResult>
options

params?:

PaginatedRequest['params']

options?:

RequestOptions

getPrompt:

async (args: { name: string; arguments?: Record<string, unknown>; options?: RequestOptions; }) => Promise<GetPromptResult>
args

name:

string

arguments?:

Record<string, unknown>

options?:

RequestOptions

onElicitationRequest:

( schema: typeof ElicitationRequestSchema, handler: (request: ElicitationRequest) => Promise<ElicitResult> | ElicitResult ) => void
parameters

schema:

typeof ElicitationRequestSchema

handler:

(request: ElicitationRequest) => Promise<ElicitResult> | ElicitResult

close:

async () => void

Example 

import {
  experimental_createMCPClient as createMCPClient,
  generateText,
} from '@ai-sdk/mcp';
import { Experimental_StdioMCPTransport } from '@ai-sdk/mcp/mcp-stdio';


let client;


try {
  client = await createMCPClient({
    transport: new Experimental_StdioMCPTransport({
      command: 'node server.js',
    }),
  });


  const tools = await client.tools();


  const response = await generateText({
    model: "anthropic/claude-sonnet-4.5",
    tools,
    messages: [{ role: 'user', content: 'Query the data' }],
  });


  console.log(response);
} catch (error) {
  console.error('Error:', error);
} finally {
  // ensure the client is closed even if an error occurs
  if (client) {
    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.