Model Context Protocol (MCP)

The AI SDK supports connecting to Model Context Protocol (MCP) servers to access their tools, resources, and prompts. This enables your AI applications to discover and use capabilities across various services through a standardized interface.

Initializing an MCP Client

We recommend using HTTP transport (like StreamableHTTPClientTransport) for production deployments. The stdio transport should only be used for connecting to local servers as it cannot be deployed to production environments.

Create an MCP client using one of the following transport options:

• HTTP transport (Recommended): Either configure HTTP directly via the client using transport: { type: 'http', ... }, or use MCP's official TypeScript SDK StreamableHTTPClientTransport
• SSE (Server-Sent Events): An alternative HTTP-based transport
• stdio: For local development only. Uses standard input/output streams for local MCP servers

The AI SDK MCP client supports both legacy initialization-based protocol versions and stateless MCP 2026-07-28. The built-in stdio transport probes with server/discover and automatically falls back to the legacy initialize handshake for older servers. Custom transports can opt into this negotiation with supportsProtocolVersionDiscovery: true.

HTTP Transport (Recommended)

For production deployments, we recommend using the HTTP transport. You can configure it directly on the client:

import { createMCPClient } from '@ai-sdk/mcp';

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://your-server.com/mcp',

    // optional: configure HTTP headers
    headers: { Authorization: 'Bearer my-api-key' },

    // optional: provide an OAuth client provider for automatic authorization
    authProvider: myOAuthClientProvider,

    // optional: allow redirect responses (default is 'error' to prevent SSRF)
    redirect: 'follow',
  },
});

If a legacy MCP server uses Streamable HTTP sessions, you can reattach to a saved session by restoring both the previous session id and initialize result. MCP 2026-07-28 is stateless and does not use these options:

import { createMCPClient } from '@ai-sdk/mcp';

const savedSession = await loadMcpSession();
let currentSessionId = savedSession?.sessionId;

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://your-server.com/mcp',
    initialSessionId: savedSession?.sessionId,
    initialProtocolVersion: savedSession?.initializeResult.protocolVersion,
    terminateSessionOnClose: false,

    onSessionIdChange: sessionId => {
      currentSessionId = sessionId;
    },

    onSessionExpired: sessionId => {
      if (currentSessionId === sessionId) {
        currentSessionId = undefined;
        void clearMcpSession();
      }
    },
  },
  initialInitializeResult: savedSession?.initializeResult,
});

if (currentSessionId) {
  await saveMcpSession({
    sessionId: currentSessionId,
    initializeResult: mcpClient.initializeResult,
  });
}

When initialInitializeResult is provided, createMCPClient reuses the cached initialize metadata and does not send another initialize request. When onSessionExpired is called, the transport has already cleared the session id and the request still fails with the underlying HTTP error. Retry by creating a fresh client without initialSessionId or initialInitializeResult. Set terminateSessionOnClose to false when closing only the local client but keeping the MCP session available for a later reattach.

Alternatively, you can use StreamableHTTPClientTransport from MCP's official TypeScript SDK:

import { createMCPClient } from '@ai-sdk/mcp';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const url = new URL('https://your-server.com/mcp');
const mcpClient = await createMCPClient({
  transport: new StreamableHTTPClientTransport(url, {
    sessionId: 'session_123',
  }),
});

SSE Transport

SSE provides an alternative HTTP-based transport option. Configure it with a type and url property. You can also provide an authProvider for OAuth:

import { createMCPClient } from '@ai-sdk/mcp';

const mcpClient = await createMCPClient({
  transport: {
    type: 'sse',
    url: 'https://my-server.com/sse',

    // optional: configure HTTP headers
    headers: { Authorization: 'Bearer my-api-key' },

    // optional: provide an OAuth client provider for automatic authorization
    authProvider: myOAuthClientProvider,

    // optional: allow redirect responses (default is 'error' to prevent SSRF)
    redirect: 'follow',
  },
});

Stdio Transport (Local Servers)

The Stdio transport can be imported from either the MCP SDK or the AI SDK:

import { createMCPClient } from '@ai-sdk/mcp';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
// Or use the AI SDK's stdio transport:
// import { Experimental_StdioMCPTransport as StdioClientTransport } from '@ai-sdk/mcp/mcp-stdio';

const mcpClient = await createMCPClient({
  transport: new StdioClientTransport({
    command: 'node',
    args: ['src/stdio/dist/server.js'],
  }),
});

Custom Transport

You can also bring your own transport by implementing the MCPTransport interface for specific requirements not covered by the standard transports.

Shared OAuth Credential Storage

When multiple MCP clients or replicas share OAuth credentials, a rotating refresh token can be used concurrently. One refresh may save new tokens while another receives invalid_grant for the old refresh token.

The optional OAuthClientProvider.invalidateCredentials method receives a second argument identifying the tokens used by a failed refresh:

invalidateCredentials(
  scope: 'all' | 'client' | 'tokens' | 'verifier',
  context?: { tokens: OAuthTokens },
): void | Promise<void>;

For scope === 'tokens' with a context, delete the credential only if the stored access and refresh tokens still match context.tokens. The comparison and deletion must be atomic, using a conditional database operation or a transaction. If they no longer match, leave the newer tokens in storage. The SDK retries authorization and reads the stored tokens again.

The SDK also provides this context when invalidating stored tokens that lack an authorization server pin. Other invalidations can omit the context.

If an authorization-code exchange returns invalid_grant, the SDK propagates the error without invalidating stored credentials or retrying the rejected code. A rejected authorization code does not indicate that existing access or refresh tokens are invalid.

OAuth Authorization Server Validation

When using MCP OAuth in server-side applications, the MCP server can advertise the OAuth authorization server to use. If you connect to MCP servers outside your control, implement validateAuthorizationServerURL on your authProvider to allow only the authorization server origins you trust:

const allowedAuthorizationServerOrigins = new Set([
  'https://accounts.example.com',
  'https://tenant.auth0.com',
]);

const myOAuthClientProvider = {
  // ...other OAuthClientProvider methods

  validateAuthorizationServerURL(serverUrl, authorizationServerUrl) {
    const origin = new URL(authorizationServerUrl).origin;

    if (!allowedAuthorizationServerOrigins.has(origin)) {
      throw new Error(
        `Unexpected OAuth authorization server for ${serverUrl}: ${origin}`,
      );
    }
  },
};

This hook is called before the SDK fetches authorization server metadata, so a rejected URL is not requested. It is optional and does not change existing OAuth flows unless you implement it.

OAuth Callback Issuer Validation

When completing an OAuth authorization callback, pass the callback's iss parameter to auth as callbackIssuer:

import { auth } from '@ai-sdk/mcp';

const callbackUrl = new URL(request.url);

await auth(myOAuthClientProvider, {
  serverUrl: 'https://mcp.example.com',
  authorizationCode: callbackUrl.searchParams.get('code')!,
  callbackState: callbackUrl.searchParams.get('state') ?? undefined,
  callbackIssuer: callbackUrl.searchParams.get('iss') ?? undefined,
});

When iss is present, it must exactly match the discovered authorization server issuer. The authorization code is not exchanged when it does not match.

Dynamic client registration requests include an OAuth application_type. The client infers native for loopback, localhost, and custom-scheme redirects, and web for remote HTTP(S) redirects. You can override this by setting application_type in the provider's clientMetadata.

Dynamic Client Credential Recovery

To let the SDK replace invalid credentials created through dynamic client registration, implement isClientInformationDynamicallyRegistered on the OAuth client provider. Return true only when the current client information came from a dynamic registration response. Persist this provenance alongside the credentials when the provider is recreated between requests.

const myOAuthClientProvider = {
  // ...other OAuthClientProvider methods

  async saveClientInformation(clientInformation) {
    await saveClientRecord({
      clientInformation,
      dynamicallyRegistered: true,
    });
  },

  async isClientInformationDynamicallyRegistered() {
    return (await loadClientRecord())?.dynamicallyRegistered === true;
  },
};

When this method is omitted or returns false, client information is treated as pre-registered and is preserved after invalid_client and unauthorized_client errors. The SDK does not infer provenance from fields such as redirect_uris, because pre-registered clients can contain the same metadata as dynamically registered clients.

Retrying Transient Tool Failures

MCP tool calls can fail for transient transport reasons, such as rate limits, temporary overload, or gateway timeouts. You can opt into automatic retries for tools/call requests by passing maxRetries when creating the client:

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://your-server.com/mcp',
  },
  maxRetries: 2,
});

Retries are disabled by default. Built-in retry matching is intended for transient HTTP and network failures only. JSON-RPC application errors, such as invalid tool arguments, are surfaced immediately without retrying. Successful MCP tool responses with isError: true are also returned to the model without retrying.

maxRetries applies to tools/call requests, not to client initialization. The following example identifies potentially transient HTTP initialization failures using the exported MCPClientError type guard:

import { createMCPClient, MCPClientError } from '@ai-sdk/mcp';

try {
  await createMCPClient({
    transport: {
      type: 'http',
      url: 'https://your-server.com/mcp',
    },
  });
} catch (error) {
  if (
    !MCPClientError.isInstance(error) ||
    error.code != null ||
    error.statusCode == null ||
    !(
      error.statusCode === 408 ||
      error.statusCode === 409 ||
      error.statusCode === 429 ||
      error.statusCode >= 500
    )
  ) {
    throw error;
  }

  // Retry according to your application's backoff policy.
}

This example only considers HTTP statuses. A missing statusCode does not establish that a failure is transient: configuration errors, protocol errors, and cancelled requests can also lack an HTTP status. Network and timeout retries require a separate application policy. OAuth errors such as UnauthorizedError and MCPClientOAuthError are rethrown by this example.

Closing the MCP Client

After initialization, you should close the MCP client based on your usage pattern:

• For short-lived usage (e.g., single requests), close the client when the response is finished
• For long-running clients (e.g., command line apps), keep the client open but ensure it's closed when the application terminates

When streaming responses, you can close the client when the LLM response has finished. For example, when using streamText, you should use the onEnd callback:

GatewayProviderCustom

Claude Sonnet 5.5

const mcpClient = await createMCPClient({
  // ...
});

const tools = await mcpClient.tools();

const result = await streamText({
  model: "anthropic/claude-sonnet-5.5",
  tools,
  prompt: 'What is the weather in Brooklyn, New York?',
  onEnd: async () => {
    await mcpClient.close();
  },
});

When generating responses without streaming, you can use try/finally or cleanup functions in your framework:

import { createMCPClient, type MCPClient } from '@ai-sdk/mcp';

let mcpClient: MCPClient | undefined;

try {
  mcpClient = await createMCPClient({
    // ...
  });
} finally {
  await mcpClient?.close();
}

Using MCP Tools

The client's tools method acts as an adapter between MCP tools and AI SDK tools. It supports two approaches for working with tool schemas:

Schema Discovery

With schema discovery, all tools offered by the server are automatically listed, and input parameter types are inferred based on the schemas provided by the server:

const tools = await mcpClient.tools();

This approach is simpler to implement and automatically stays in sync with server changes. However, you won't have TypeScript type safety during development, and all tools from the server will be loaded

Tool Annotations and Approval

MCP servers can describe tool behavior with annotations such as readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The MCP client exposes these annotations on each tool's metadata.annotations and on the resulting tool call's toolMetadata.annotations.

Annotations are untrusted, server-provided hints. The MCP client does not turn them into an approval policy automatically. Applications should combine them with deterministic controls such as tool allowlists, scoped credentials, and their own toolApproval policy.

The following conservative policy allows tools to run automatically only when the server explicitly marks them as read-only. Tools with readOnlyHint: false or no readOnlyHint require user approval:

GatewayProviderCustom

Claude Sonnet 5.5

import { type McpProviderMetadata } from '@ai-sdk/mcp';

const result = streamText({
  model: "anthropic/claude-sonnet-5.5",
  tools,
  toolApproval: ({ toolCall }) => {
    const annotations = (
      toolCall.toolMetadata as McpProviderMetadata | undefined
    )?.annotations;

    return annotations?.readOnlyHint === true
      ? 'not-applicable'
      : {
          type: 'user-approval',
          reason:
            annotations?.destructiveHint === true
              ? 'The MCP server marks this tool as destructive.'
              : 'The MCP server does not mark this tool as read-only.',
        };
  },
  prompt,
});

See the local tool annotations example for a complete annotated MCP server and application-layer approval configuration. Start the server and client in separate terminals:

cd examples/mcp
pnpm server:tool-annotations

cd examples/mcp
pnpm client:tool-annotations

Ask the client to read, delete, or create a note. The read-only tool executes immediately. The destructive and unannotated tools prompt for approval; after you enter y or n, the client sends the decision back and prints the model's response.

Schema Definition

For better type safety and control, you can define the tools and their input schemas explicitly in your client code:

import { z } from 'zod';

const tools = await mcpClient.tools({
  schemas: {
    'get-data': {
      inputSchema: z.object({
        query: z.string().describe('The data query'),
        format: z.enum(['json', 'text']).optional(),
      }),
    },
    // For tools with zero inputs, you should use an empty object:
    'tool-with-no-args': {
      inputSchema: z.object({}),
    },
  },
});

This approach provides full TypeScript type safety and IDE autocompletion, letting you catch parameter mismatches during development. When you define schemas, the client only pulls the explicitly defined tools, keeping your application focused on the tools it needs

Typed Tool Outputs

When MCP servers return structuredContent (per the MCP specification), you can define an outputSchema to get typed tool results:

import { z } from 'zod';

const tools = await mcpClient.tools({
  schemas: {
    'get-weather': {
      inputSchema: z.object({
        location: z.string(),
      }),
      // Define outputSchema for typed results
      outputSchema: z.object({
        temperature: z.number(),
        conditions: z.string(),
        humidity: z.number(),
      }),
    },
  },
});

const result = await tools['get-weather'].execute(
  { location: 'New York' },
  { messages: [], toolCallId: 'weather-1' },
);

console.log(`Temperature: ${result.temperature}°C`);

When outputSchema is provided:

• The client extracts structuredContent from the tool result
• The output is validated against your schema at runtime
• You get full TypeScript type safety for the result

If the server doesn't return structuredContent, the client falls back to parsing JSON from the text content. If neither is available or validation fails, an error is thrown.

If a server returns structuredContent without the backwards-compatible content field, the client adds a text content block containing the serialized JSON before returning the result. This compatibility behavior handles servers that omit the text mirror recommended by the MCP specification.

Using MCP Resources

According to the MCP specification, resources are application-driven data sources that provide context to the model. Unlike tools (which are model-controlled), your application decides when to fetch and pass resources as context.

The MCP client provides three methods for working with resources:

Listing Resources

List all available resources from the MCP server:

const resources = await mcpClient.listResources();

Reading Resource Contents

Read the contents of a specific resource by its URI:

const resourceData = await mcpClient.readResource({
  uri: 'file:///example/document.txt',
});

Listing Resource Templates

Resource templates are dynamic URI patterns that allow flexible queries. List all available templates:

const templates = await mcpClient.listResourceTemplates();

Using MCP Completions

MCP servers can provide autocompletion suggestions for prompt arguments and resource template variables when they advertise the completions capability. Use complete to ask the server for suggestions based on the current partial argument value:

const completion = await mcpClient.complete({
  ref: {
    type: 'ref/resource',
    uri: 'file:///{path}',
  },
  argument: {
    name: 'path',
    value: 'doc',
  },
});

console.log(completion.completion.values);

For resource templates or prompts with multiple arguments, pass already resolved values through context.arguments:

const completion = await mcpClient.complete({
  ref: {
    type: 'ref/resource',
    uri: 'kubernetes://namespaced/{plural}/{namespace}',
  },
  argument: {
    name: 'namespace',
    value: 'auth',
  },
  context: {
    arguments: {
      plural: 'deployments',
    },
  },
});

If the connected server does not advertise capabilities.completions, the client throws an MCPClientError.

Using MCP Prompts

According to the MCP specification, prompts are user-controlled templates that servers expose for clients to list and retrieve with optional arguments.

Listing Prompts

const prompts = await mcpClient.experimental_listPrompts();

Getting a Prompt

Retrieve prompt messages, optionally passing arguments defined by the server:

const prompt = await mcpClient.experimental_getPrompt({
  name: 'code_review',
  arguments: { code: 'function add(a, b) { return a + b; }' },
});

Handling Elicitation Requests

Elicitation is a mechanism where MCP servers can request additional information from the client during tool execution. For example, a server might need user input to complete a registration form or confirmation for a sensitive operation.

Enabling Elicitation Support

To enable elicitation, you need to advertise the capability when creating the MCP client:

const mcpClient = await createMCPClient({
  transport: {
    type: 'sse',
    url: 'https://your-server.com/sse',
  },
  capabilities: {
    elicitation: {},
  },
});

Registering an Elicitation Handler

Use the onElicitationRequest method to register a handler that will be called when the server requests input:

import { ElicitationRequestSchema } from '@ai-sdk/mcp';

mcpClient.onElicitationRequest(ElicitationRequestSchema, async request => {
  // request.params.message: A message describing what input is needed
  // request.params.requestedSchema: JSON schema defining the expected input structure

  // Get input from the user (implement according to your application's needs)
  const userInput = await getInputFromUser(
    request.params.message,
    request.params.requestedSchema,
  );

  // Return the result with one of three actions:
  return {
    action: 'accept', // or 'decline' or 'cancel'
    content: userInput, // only required when action is 'accept'
  };
});

Elicitation Response Actions

Your handler must return an object with an action field that can be one of:

• 'accept': User provided the requested information. Must include content with the data.
• 'decline': User chose not to provide the information.
• 'cancel': User cancelled the operation entirely.

Detecting tool-definition drift ("rug pull")

An MCP server sends tool definitions (name, description, input schema) when your app first connects, and you typically review and approve them at that point. Nothing in the protocol prevents the server from later serving a different definition for the same tool name — for example a description carrying injected instructions, or an input schema widened with an extra field. Because the SDK uses whatever tools you pass on each call, a mutated definition returned by a later mcpClient.tools() fetch would be used without any comparison to what was approved. This is the MCP "rug pull" class of attack.

The AI SDK provides two functions to pin the approved definitions and detect changes. fingerprintTools digests the server-controlled, security-relevant fields of each tool (string description, resolved input schema, and title) into a stable map of tool name to digest. detectToolDrift diffs two such maps. Your app owns baseline storage and the response to drift (block, force re-approval, or alert):

import { fingerprintTools, detectToolDrift } from 'ai';

// Trust time (first connect, human-reviewed): capture and persist the baseline.
const baseline = await fingerprintTools(await mcpClient.tools());

// Every later fetch, before handing tools to generateText:
const tools = await mcpClient.tools();
const drift = detectToolDrift(await fingerprintTools(tools), baseline);

if (drift.changed.length || drift.added.length) {
  // A pinned definition changed, or a new tool appeared. Block, re-approve,
  // or alert per your policy — do not silently pass `tools` to the model.
}

Examples

You can see MCP in action in the following examples: