ai
Version:
AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.
900 lines (706 loc) • 32.6 kB
text/mdx
---
title: Model Context Protocol (MCP)
description: Learn how to connect to Model Context Protocol (MCP) servers and use their tools with AI SDK Core.
keywords:
- mcp
- model context protocol
---
# Model Context Protocol (MCP)
The AI SDK supports connecting to [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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.
<Note>
If you're using OpenAI's Responses API, you can also use the built-in
`openai.tools.mcp` tool, which provides direct MCP server integration without
needing to convert tools. See the [OpenAI provider
documentation](/providers/ai-sdk-providers/openai#mcp-tool) for details.
</Note>
## 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`.
Recognized modern protocol errors, including `-32022` (unsupported protocol
version), do not trigger automatic fallback to `initialize`. If you know an
endpoint requires legacy initialization, set `protocolVersionDiscovery: false`
on `createMCPClient` to skip discovery and start with the legacy handshake.
The server can then negotiate an older supported version in its `initialize`
response.
### Securing remote server URLs
When an application accepts MCP server URLs from users or external configuration,
use `guarded-fetch` on Node.js unless the destinations are controlled by
your application or your fetch implementation or network egress policy already
provides equivalent SSRF protection. Authentication alone does not make a
user-supplied URL trusted. Rejecting redirects does not prevent a hostname from
resolving to a private address.
Pass the guarded transport through `transport.fetch` on the built-in HTTP or SSE
transport. The built-in transports also use that fetch implementation for OAuth
metadata and token requests. On server runtimes, OAuth with an authorization
server on a different origin than the MCP server
[requires such a transport](#oauth-authorization-server-validation):
```ts
import { createGuardedFetch } from 'guarded-fetch';
import { createMCPClient } from '@ai-sdk/mcp';
const fetch = createGuardedFetch();
const mcpClient = await createMCPClient({
transport: {
type: 'http',
url: 'https://mcp.example.com/mcp',
fetch,
redirect: 'error',
},
});
// Reuse the client and transport. At application shutdown, close the MCP
// client first, then await fetch.close() after all requests have finished.
```
Only send credentials to approved server destinations. When using OAuth,
continue to [validate discovered authorization server URLs](#oauth-authorization-server-validation);
a guarded transport checks network destinations, not which services may receive
your credentials. Official SDK and custom transports need equivalent protection
in their own fetch configuration. See [Secure URL
Fetching](/docs/advanced/secure-url-fetching) for runtime requirements, private
endpoint configuration, and network egress controls.
### HTTP Transport (Recommended)
For production deployments, we recommend using the HTTP transport. You can configure it directly on the client:
```typescript
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,
// Reject redirects; DNS protection requires a guarded fetch or egress policy.
redirect: 'error',
},
});
```
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:
```typescript
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:
```typescript
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:
```typescript
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,
// Reject redirects; DNS protection requires a guarded fetch or egress policy.
redirect: 'error',
},
});
```
### Stdio Transport (Local Servers)
<Note type="warning">
The stdio transport should only be used for local servers.
</Note>
The Stdio transport can be imported from either the MCP SDK or the AI SDK:
```typescript
import { createMCPClient } from '@ai-sdk/mcp';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
// Or use the AI SDK's stdio transport:
// import { 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.
<Note>
The client returned by the `createMCPClient` function is a
lightweight client intended for use in tool conversion. It currently does not
support all features of the full MCP client, such as automatic session
persistence, resumable streams, and receiving notifications.
Authorization via OAuth is supported when using the AI SDK MCP HTTP or SSE
transports by providing an `authProvider`. On server runtimes, including
Node.js, also pass a `fetch` with connect-time DNS validation, such as
`guarded-fetch`, when the authorization server is on a different origin than
the MCP server. See [Securing remote server URLs](#securing-remote-server-urls).
</Note>
### OAuth Resource Binding
The MCP client includes the OAuth `resource` parameter in authorization,
authorization-code exchange, and token refresh requests. It uses the validated
resource from protected resource metadata when available. If metadata is
unavailable, it uses the configured MCP server URL with its fragment removed.
To customize resource validation and selection, implement
`OAuthClientProvider.validateResourceURL`. Return a `URL` to select a resource,
or throw to reject it. Returning `undefined` uses the canonical MCP server URL;
it does not omit the `resource` parameter.
### 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:
```typescript
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. These tokens must be cleared before the SDK saves a new
client registration or authorization server pin. If the invalidation hook is
missing or refresh tokens remain in storage, authorization stops with an error;
clear the stored tokens and start authorization again. 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
Pre-registered confidential clients must be bound to their authorization server
before starting OAuth. Set `issuer` on the credentials returned by
`clientInformation()` to the issuer of the server that registered the client:
```typescript
clientInformation() {
return {
client_id: process.env.OAUTH_CLIENT_ID!,
client_secret: process.env.OAUTH_CLIENT_SECRET!,
issuer: 'https://accounts.example.com',
};
}
```
The issuer must exactly match the discovered issuer. The SDK rejects a mismatch
before redirecting or sending credentials, even if a stored authorization flow
pin names the discovered server. Dynamic client registration attaches this
binding automatically.
Existing complete authorization server bindings on credentials, stored tokens,
or `authorizationServerInformation()` are also supported. Without a binding,
a pre-registered client secret or custom `addClientAuthentication` handler is
rejected, even when `validateAuthorizationServerURL` accepts the selected server.
Approving a server does not establish that the credentials belong to it.
Do not derive the credential issuer from the MCP server's metadata; configure it
from the client's registration.
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:
```typescript
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. The hook is an optional additional restriction;
it does not replace the credential binding required for confidential clients.
On server runtimes, including Node.js, OAuth discovery blocks untrusted
authorization-server URLs, redirects, token endpoints, and registration
endpoints unless you supply a custom `fetch` with connect-time address
validation and DNS pinning. Without one, the request fails with a
`DownloadError`. On Node.js, pass `createGuardedFetch()` through
`transport.fetch` as shown in
[Securing remote server URLs](#securing-remote-server-urls). When calling
`auth` directly, pass the same transport as `fetchFn`.
Passing global `fetch` explicitly does not opt out of this requirement. The
configured MCP server origin remains supported, including local endpoints;
response-supplied authorization-server hosts are not automatically trusted.
Browser window discovery remains supported. Browser Web Workers and Service
Workers without a DOM follow the strict custom-fetch requirement as well;
worker globals alone cannot establish that the runtime is a browser rather
than a server worker.
### OAuth Callback Issuer Validation
When completing an OAuth authorization callback, pass the callback's `iss`
parameter to `auth` as `callbackIssuer`:
```typescript
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.
```typescript
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:
```typescript
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:
```typescript
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.
<Note type="warning">
Only enable retries for MCP tools where retrying is safe. Retrying
non-idempotent tools, such as tools that send emails or create records, can
duplicate side effects.
</Note>
### 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:
```typescript
const mcpClient = await createMCPClient({
// ...
});
const tools = await mcpClient.tools();
const result = await streamText({
model: __MODEL__,
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:
```typescript
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:
```typescript
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`](/docs/agents/tool-approvals) 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:
```typescript
import { type McpProviderMetadata } from '@ai-sdk/mcp';
const result = streamText({
model: __MODEL__,
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](https://github.com/vercel/ai/tree/main/examples/mcp/src/tool-annotations)
for a complete annotated MCP server and application-layer approval
configuration. Start the server and client in separate terminals:
```bash
cd examples/mcp
pnpm server:tool-annotations
```
```bash
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:
```typescript
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](https://modelcontextprotocol.io/specification/2026-07-28/server/tools#structured-content)), you can define an `outputSchema` to get typed tool results:
```typescript
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.
<Note>
Without `outputSchema`, the tool returns the raw `CallToolResult` object
containing `content` and optional `isError` fields.
</Note>
## Using MCP Resources
According to the [MCP specification](https://modelcontextprotocol.io/docs/learn/server-concepts#resources), 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:
```typescript
const resources = await mcpClient.listResources();
```
### Reading Resource Contents
Read the contents of a specific resource by its URI:
```typescript
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:
```typescript
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:
```typescript
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`:
```typescript
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
```typescript
const prompts = await mcpClient.listPrompts();
```
### Getting a Prompt
Retrieve prompt messages, optionally passing arguments defined by the server:
```typescript
const prompt = await mcpClient.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.
<Note type="warning">
It is up to the client application to handle elicitation requests properly.
The MCP client simply surfaces these requests from the server to your
application code.
</Note>
### Enabling Elicitation Support
To enable elicitation, you need to advertise the capability when creating the MCP client:
```typescript
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:
```typescript
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
On MCP `2026-07-28` connections, the same handler processes form elicitation
requests embedded in `input_required` results from tools, prompts, and resource
reads. The client retries the original request with the handler's answers and
the server's unchanged `requestState` until it receives a final result, with a
limit of 10 retries. State-only retries are delayed by 250 ms. Each round respects
`timeout`, including time spent awaiting the handler, while `maxTotalTimeout`
bounds the entire exchange. Missing handlers and unsupported input requests
reject the operation. Older connections continue to use `elicitation/create`
server requests.
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"](https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks)
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):
```typescript
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.
}
```
<Note>
This detects mutation of a tool's description, input schema, or title — the
prompt-injection and schema-widening vectors. It cannot detect a
behavior/endpoint swap where the name, description, and schema are all
unchanged, because the tool runs remotely on the MCP server and that change is
invisible to the client. Core stays unopinionated: it does not persist
baselines or block calls — those are your app's responsibility.
</Note>
## Examples
You can see MCP in action in the following examples:
<ExampleLinks
examples={[
{
title: 'Learn to use MCP tools in Node.js',
link: '/cookbook/node/mcp-tools',
},
{
title: 'Learn to handle MCP elicitation requests in Node.js',
link: '/cookbook/node/mcp-elicitation',
},
{
title: 'Learn to render MCP Apps',
link: '/docs/ai-sdk-core/mcp-apps',
},
]}
/>