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
  • Completions: Methods to request autocompletion suggestions for prompt arguments and resource template variables
  • 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.

Import 

import { createMCPClient } from "@ai-sdk/mcp"

API Signature

Parameters

config:

MCPClientConfig
MCPClientConfig

transport:

MCPTransportConfig | MCPTransport
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

redirect?:

'follow' | 'error'

initialSessionId?:

string

initialProtocolVersion?:

string

onSessionIdChange?:

(sessionId: string | undefined) => void

onSessionExpired?:

(sessionId: string) => void

terminateSessionOnClose?:

boolean

fetch?:

FetchFunction

initializationOptions?:

RequestOptions

clientName?:

string

name?:

string

version?:

string

onUncaughtError?:

(error: unknown) => void

maxRetries?:

number

initialInitializeResult?:

InitializeResult

capabilities?:

ClientCapabilities

Returns

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

initializeResult:

InitializeResult

serverInfo:

Configuration

instructions?:

string

tools:

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

schemas?:

TOOL_SCHEMAS
TOOL_SCHEMAS

inputSchema:

FlexibleSchema

outputSchema?:

FlexibleSchema

listTools:

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

params?:

PaginatedRequest['params']

options?:

RequestOptions

callTool:

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

name:

string

arguments?:

Record<string, unknown>

options?:

RequestOptions

toolsFromDefinitions:

(definitions: ListToolsResult, options?: { schemas?: TOOL_SCHEMAS }) => McpToolSet<TOOL_SCHEMAS>
parameters

definitions:

ListToolsResult

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

complete:

async (args: CompleteRequestParams & { options?: RequestOptions; }) => Promise<CompleteResult>
args

ref:

{ type: 'ref/prompt'; name: string } | { type: 'ref/resource'; uri: string }

argument:

{ name: string; value: string }

context?:

{ arguments: Record<string, string> }

options?:

RequestOptions

experimental_listPrompts:

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

params?:

PaginatedRequest['params']

options?:

RequestOptions

experimental_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:

() => Promise<void>

Example 

import { createMCPClient } from '@ai-sdk/mcp';
import { generateText } from 'ai';
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: "xai/grok-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.