📄 ai-sdk/docs/reference/ai-sdk-core/create-mcp-client

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

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

Configuration for the MCP client.

MCPClientConfig

transport:

TransportConfig = MCPTransport | McpSSEServerConfig

Configuration for the message transport layer.

MCPTransport

start:

() => Promise<void>

A method that starts the transport

send:

(message: JSONRPCMessage) => Promise<void>

A method that sends a message through the transport

close:

() => Promise<void>

A method that closes the transport

onclose:

() => void

A method that is called when the transport is closed

onerror:

(error: Error) => void

A method that is called when the transport encounters an error

onmessage:

(message: JSONRPCMessage) => void

A method that is called when the transport receives a message

MCPTransportConfig

type:

'sse' | 'http

Use Server-Sent Events for communication

url:

string

URL of the MCP server

headers?:

Record<string, string>

Additional HTTP headers to be sent with requests.

authProvider?:

OAuthClientProvider

Optional OAuth provider for authorization to access protected remote MCP servers.

name?:

string

Client name. Defaults to "ai-sdk-mcp-client"

onUncaughtError?:

(error: unknown) => void

Handler for uncaught errors

Returns

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

tools:

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

Gets the tools available from the MCP server.

options

schemas?:

TOOL_SCHEMAS

Schema definitions for compile-time type checking. When not provided, schemas are inferred from the server.

listResources:

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

Lists all available resources from the MCP server.

options

params?:

PaginatedRequest['params']

Optional pagination parameters including cursor.

options?:

RequestOptions

Optional request options including signal and timeout.

readResource:

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

Reads the contents of a specific resource by URI.

args

uri:

string

The URI of the resource to read.

options?:

RequestOptions

Optional request options including signal and timeout.

listResourceTemplates:

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

Lists all available resource templates from the MCP server.

options

options?:

RequestOptions

Optional request options including signal and timeout.

listPrompts:

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

Lists available prompts from the MCP server.

options

params?:

PaginatedRequest['params']

Optional pagination parameters including cursor.

options?:

RequestOptions

Optional request options including signal and timeout.

getPrompt:

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

Retrieves a prompt by name, optionally passing arguments.

args

name:

string

Prompt name to retrieve.

arguments?:

Record<string, unknown>

Optional arguments to fill into the prompt.

options?:

RequestOptions

Optional request options including signal and timeout.

close:

async () => void

Closes the connection to the MCP server and cleans up resources.

Example

import { experimental_createMCPClient, generateText } from '@ai-sdk/mcp';import { Experimental_StdioMCPTransport } from '@ai-sdk/mcp/mcp-stdio';import { openai } from '@ai-sdk/openai';
let client;
try {  client = await experimental_createMCPClient({    transport: new Experimental_StdioMCPTransport({      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);} 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.

On this page

experimental_createMCPClient()

Deploy and Scale AI Apps with Vercel.

Vercel delivers the infrastructure and developer experience you need to ship reliable AI-powered applications at scale.

Trusted by industry leaders:

OpenAI
Photoroom

Talk to an expert