---
title: createMCPClient
description: Create a client for connecting to MCP servers
---

# `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

<Snippet
  text={`import { createMCPClient } from "@ai-sdk/mcp"`}
  prompt={false}
/>

## API Signature

### Parameters

<PropertiesTable
  content={[
    {
      name: 'config',
      type: 'MCPClientConfig',
      description: 'Configuration for the MCP client.',
      properties: [
        {
          type: 'MCPClientConfig',
          parameters: [
            {
              name: 'transport',
              type: 'MCPTransportConfig | MCPTransport',
              description: 'Configuration for the message transport layer.',
              properties: [
                {
                  type: 'MCPTransport',
                  description:
                    'A client transport instance, used explicitly for stdio or custom transports',
                  parameters: [
                    {
                      name: 'start',
                      type: '() => Promise<void>',
                      description: 'A method that starts the transport',
                    },
                    {
                      name: 'send',
                      type: '(message: JSONRPCMessage) => Promise<void>',
                      description:
                        'A method that sends a message through the transport',
                    },
                    {
                      name: 'close',
                      type: '() => Promise<void>',
                      description: 'A method that closes the transport',
                    },
                    {
                      name: 'onclose',
                      type: '() => void',
                      description:
                        'A method that is called when the transport is closed',
                    },
                    {
                      name: 'onerror',
                      type: '(error: Error) => void',
                      description:
                        'A method that is called when the transport encounters an error',
                    },
                    {
                      name: 'onmessage',
                      type: '(message: JSONRPCMessage) => void',
                      description:
                        'A method that is called when the transport receives a message',
                    },
                  ],
                },
                {
                  type: 'MCPTransportConfig',
                  parameters: [
                    {
                      name: 'type',
                      type: "'sse' | 'http'",
                      description: 'Use Server-Sent Events for communication',
                    },
                    {
                      name: 'url',
                      type: 'string',
                      description: 'URL of the MCP server',
                    },
                    {
                      name: 'headers',
                      type: 'Record<string, string>',
                      isOptional: true,
                      description:
                        'Additional HTTP headers to be sent with requests.',
                    },
                    {
                      name: 'authProvider',
                      type: 'OAuthClientProvider',
                      isOptional: true,
                      description:
                        'Optional OAuth provider for authorization to access protected remote MCP servers. Implement `validateAuthorizationServerURL` on the provider to allowlist discovered OAuth authorization server URLs before metadata is fetched.',
                    },
                    {
                      name: 'redirect',
                      type: "'follow' | 'error'",
                      isOptional: true,
                      description:
                        "Controls how HTTP redirects are handled for transport requests. Set to 'follow' to allow redirect responses. Defaults to 'error' to reject any redirect response, preventing servers from redirecting requests to unintended hosts.",
                    },
                    {
                      name: 'initialSessionId',
                      type: 'string',
                      isOptional: true,
                      description:
                        'Initial MCP session id to send with resumed Streamable HTTP requests after initialization. Pair with initialInitializeResult when using createMCPClient. Only used by the HTTP transport.',
                    },
                    {
                      name: 'initialProtocolVersion',
                      type: 'string',
                      isOptional: true,
                      description:
                        'Initial MCP protocol version to send before initialize negotiates one. Only used by the HTTP transport.',
                    },
                    {
                      name: 'onSessionIdChange',
                      type: '(sessionId: string | undefined) => void',
                      isOptional: true,
                      description:
                        'Callback invoked when the Streamable HTTP server creates, changes, or clears the MCP session id. Only used by the HTTP transport.',
                    },
                    {
                      name: 'onSessionExpired',
                      type: '(sessionId: string) => void',
                      isOptional: true,
                      description:
                        'Callback invoked when a Streamable HTTP request returns 404 for an existing MCP session id. The transport clears the session id before reporting the underlying HTTP error. Only used by the HTTP transport.',
                    },
                    {
                      name: 'terminateSessionOnClose',
                      type: 'boolean',
                      isOptional: true,
                      description:
                        'Whether close() should send DELETE for the current MCP session id. Set to false when the application intends to reattach to the session later. Defaults to true. Only used by the HTTP transport.',
                    },
                    {
                      name: 'fetch',
                      type: 'FetchFunction',
                      isOptional: true,
                      description:
                        'Optional custom fetch implementation to use for HTTP requests. Useful for runtimes that need a request-local fetch.',
                    },
                  ],
                },
              ],
            },
            {
              name: 'clientName',
              type: 'string',
              isOptional: true,
              description: 'Client name. Defaults to "ai-sdk-mcp-client".',
            },
            {
              name: 'name',
              type: 'string',
              isOptional: true,
              description:
                'Deprecated. Use `clientName` instead. Defaults to "ai-sdk-mcp-client".',
            },
            {
              name: 'version',
              type: 'string',
              isOptional: true,
              description: 'Client version. Defaults to "1.0.0"',
            },
            {
              name: 'onUncaughtError',
              type: '(error: unknown) => void',
              isOptional: true,
              description: 'Handler for uncaught errors',
            },
            {
              name: 'maxRetries',
              type: 'number',
              isOptional: true,
              description:
                'Maximum number of retries for transient MCP tool call failures. Set to 0 to disable retries. Defaults to 0. Retries are opt-in and apply to tools/call requests.',
            },
            {
              name: 'initialInitializeResult',
              type: 'InitializeResult',
              isOptional: true,
              description:
                'Initialize result from a previous MCP session. When provided, the client starts the transport and reuses this metadata without sending a new initialize request.',
            },
            {
              name: 'capabilities',
              type: 'ClientCapabilities',
              isOptional: true,
              description:
                'Optional client capabilities to advertise during initialization. For example, set { elicitation: {} } to enable handling elicitation requests from the server.',
            },
          ],
        },
      ],
    },
  ]}
/>

### Returns

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

<PropertiesTable
  content={[
    {
      name: 'initializeResult',
      type: 'InitializeResult',
      description:
        'The full initialize result used by this client, either from the server during initialization or from initialInitializeResult.',
    },
    {
      name: 'serverInfo',
      type: 'Configuration',
      description:
        'Information about the connected MCP server (name, version, optional title), as reported during the initialize handshake.',
    },
    {
      name: 'instructions',
      type: 'string',
      isOptional: true,
      description:
        'Optional instructions provided by the server during the initialize handshake. Describes how to use the server and its features. Useful for inclusion in the LLM system prompt.',
    },
    {
      name: 'tools',
      type: `async (options?: {
        schemas?: TOOL_SCHEMAS
      }) => Promise<McpToolSet<TOOL_SCHEMAS>>`,
      description: 'Gets the tools available from the MCP server.',
      properties: [
        {
          type: 'options',
          parameters: [
            {
              name: 'schemas',
              type: 'TOOL_SCHEMAS',
              isOptional: true,
              description:
                'Schema definitions for compile-time type checking. When not provided, schemas are inferred from the server. Each tool schema can include inputSchema for typed inputs, and optionally outputSchema for typed outputs when the server returns structuredContent.',
            },
          ],
        },
        {
          type: 'TOOL_SCHEMAS',
          parameters: [
            {
              name: 'inputSchema',
              type: 'FlexibleSchema',
              description:
                'Zod schema or JSON schema defining the expected input parameters for the tool.',
            },
            {
              name: 'outputSchema',
              type: 'FlexibleSchema',
              isOptional: true,
              description:
                'Zod schema or JSON schema defining the expected output structure. When provided, the client extracts and validates structuredContent from tool results, giving you typed outputs.',
            },
          ],
        },
      ],
    },
    {
      name: 'listTools',
      type: `async (options?: {
        params?: PaginatedRequest['params'];
        options?: RequestOptions;
      }) => Promise<ListToolsResult>`,
      description:
        'Lists available tool definitions from the MCP server without converting them to AI SDK tools.',
      properties: [
        {
          type: 'options',
          parameters: [
            {
              name: 'params',
              type: "PaginatedRequest['params']",
              isOptional: true,
              description: 'Optional pagination parameters including cursor.',
            },
            {
              name: 'options',
              type: 'RequestOptions',
              isOptional: true,
              description:
                'Optional request options including signal and timeout.',
            },
          ],
        },
      ],
    },
    {
      name: 'callTool',
      type: `async (args: {
        name: string;
        arguments?: Record<string, unknown>;
        options?: RequestOptions;
      }) => Promise<CallToolResult>`,
      description:
        'Calls a tool on the MCP server. This is useful for host-mediated calls, such as MCP Apps iframe requests.',
      properties: [
        {
          type: 'args',
          parameters: [
            {
              name: 'name',
              type: 'string',
              description: 'The name of the MCP tool to call.',
            },
            {
              name: 'arguments',
              type: 'Record<string, unknown>',
              isOptional: true,
              description: 'Arguments to pass to the MCP tool.',
            },
            {
              name: 'options',
              type: 'RequestOptions',
              isOptional: true,
              description:
                'Optional request options including signal and timeout.',
            },
          ],
        },
      ],
    },
    {
      name: 'toolsFromDefinitions',
      type: `(definitions: ListToolsResult, options?: {
        schemas?: TOOL_SCHEMAS
      }) => McpToolSet<TOOL_SCHEMAS>`,
      description:
        'Converts existing MCP tool definitions into AI SDK tools without listing tools again.',
      properties: [
        {
          type: 'parameters',
          parameters: [
            {
              name: 'definitions',
              type: 'ListToolsResult',
              description:
                'Tool definitions, typically returned by `listTools`.',
            },
            {
              name: 'schemas',
              type: 'TOOL_SCHEMAS',
              isOptional: true,
              description:
                'Optional schema definitions for compile-time type checking and typed outputs.',
            },
          ],
        },
      ],
    },
    {
      name: 'listResources',
      type: `async (options?: {
        params?: PaginatedRequest['params'];
        options?: RequestOptions;
      }) => Promise<ListResourcesResult>`,
      description: 'Lists all available resources from the MCP server.',
      properties: [
        {
          type: 'options',
          parameters: [
            {
              name: 'params',
              type: "PaginatedRequest['params']",
              isOptional: true,
              description: 'Optional pagination parameters including cursor.',
            },
            {
              name: 'options',
              type: 'RequestOptions',
              isOptional: true,
              description:
                'Optional request options including signal and timeout.',
            },
          ],
        },
      ],
    },
    {
      name: 'readResource',
      type: `async (args: {
        uri: string;
        options?: RequestOptions;
      }) => Promise<ReadResourceResult>`,
      description: 'Reads the contents of a specific resource by URI.',
      properties: [
        {
          type: 'args',
          parameters: [
            {
              name: 'uri',
              type: 'string',
              description: 'The URI of the resource to read.',
            },
            {
              name: 'options',
              type: 'RequestOptions',
              isOptional: true,
              description:
                'Optional request options including signal and timeout.',
            },
          ],
        },
      ],
    },
    {
      name: 'listResourceTemplates',
      type: `async (options?: {
        options?: RequestOptions;
      }) => Promise<ListResourceTemplatesResult>`,
      description:
        'Lists all available resource templates from the MCP server.',
      properties: [
        {
          type: 'options',
          parameters: [
            {
              name: 'options',
              type: 'RequestOptions',
              isOptional: true,
              description:
                'Optional request options including signal and timeout.',
            },
          ],
        },
      ],
    },
    {
      name: 'complete',
      type: `async (args: CompleteRequestParams & {
        options?: RequestOptions;
      }) => Promise<CompleteResult>`,
      description:
        'Requests autocompletion suggestions for a prompt argument or resource template variable. The server must advertise the completions capability.',
      properties: [
        {
          type: 'args',
          parameters: [
            {
              name: 'ref',
              type: "{ type: 'ref/prompt'; name: string } | { type: 'ref/resource'; uri: string }",
              description:
                'Reference to the prompt or resource template being completed.',
            },
            {
              name: 'argument',
              type: '{ name: string; value: string }',
              description:
                'Argument name and current partial value to complete.',
            },
            {
              name: 'context',
              type: '{ arguments: Record<string, string> }',
              isOptional: true,
              description:
                'Previously resolved argument values used to provide context for multi-argument prompts or resource templates.',
            },
            {
              name: 'options',
              type: 'RequestOptions',
              isOptional: true,
              description:
                'Optional request options including signal and timeout.',
            },
          ],
        },
      ],
    },
    {
      name: 'experimental_listPrompts',
      type: `async (options?: {
        params?: PaginatedRequest['params'];
        options?: RequestOptions;
      }) => Promise<ListPromptsResult>`,
      description:
        'Lists available prompts from the MCP server. This method is experimental and may change in the future.',
      properties: [
        {
          type: 'options',
          parameters: [
            {
              name: 'params',
              type: "PaginatedRequest['params']",
              isOptional: true,
              description: 'Optional pagination parameters including cursor.',
            },
            {
              name: 'options',
              type: 'RequestOptions',
              isOptional: true,
              description:
                'Optional request options including signal and timeout.',
            },
          ],
        },
      ],
    },
    {
      name: 'experimental_getPrompt',
      type: `async (args: {
        name: string;
        arguments?: Record<string, unknown>;
        options?: RequestOptions;
      }) => Promise<GetPromptResult>`,
      description:
        'Retrieves a prompt by name, optionally passing arguments. This method is experimental and may change in the future.',
      properties: [
        {
          type: 'args',
          parameters: [
            {
              name: 'name',
              type: 'string',
              description: 'Prompt name to retrieve.',
            },
            {
              name: 'arguments',
              type: 'Record<string, unknown>',
              isOptional: true,
              description: 'Optional arguments to fill into the prompt.',
            },
            {
              name: 'options',
              type: 'RequestOptions',
              isOptional: true,
              description:
                'Optional request options including signal and timeout.',
            },
          ],
        },
      ],
    },
    {
      name: 'onElicitationRequest',
      type: `(
        schema: typeof ElicitationRequestSchema,
        handler: (request: ElicitationRequest) => Promise<ElicitResult> | ElicitResult
      ) => void`,
      description:
        'Registers a handler for elicitation requests from the MCP server. The handler receives requests when the server needs additional input during tool execution.',
      properties: [
        {
          type: 'parameters',
          parameters: [
            {
              name: 'schema',
              type: 'typeof ElicitationRequestSchema',
              description:
                'The schema to validate requests against. Must be ElicitationRequestSchema.',
            },
            {
              name: 'handler',
              type: '(request: ElicitationRequest) => Promise<ElicitResult> | ElicitResult',
              description:
                'A function that handles the elicitation request. The request contains a message and requestedSchema. The handler must return an object with an action ("accept", "decline", or "cancel") and optionally content when accepting.',
            },
          ],
        },
      ],
    },
    {
      name: 'close',
      type: '() => Promise<void>',
      description:
        'Closes the connection to the MCP server and cleans up resources.',
    },
  ]}
/>

## Example

```typescript
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: __MODEL__,
    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.
