OpenWikivercel/ai

MCP Tools and Apps

Purpose and Scope

Model Context Protocol support lets an AI SDK application discover capabilities from an external MCP server and pass those capabilities into normal AI SDK Core model calls. In this repository, the reader-facing docs describe MCP as a standardized way to access tools, resources, and prompts, while the package README frames @ai-sdk/mcp as the client package that converts MCP tool definitions into AI SDK tools usable by generateText and streamText. MCP Apps build on that same tool flow by letting a tool point to an interactive HTML resource rendered by the host application. Sources: content/docs/03-ai-sdk-core/16-mcp-tools.mdx, packages/mcp/README.md, content/docs/03-ai-sdk-core/17-mcp-apps.mdx

Use this page when you need to decide whether you are only exposing MCP server tools to a model, or whether you are also hosting app-backed tool UI. Plain MCP tool use is server-side: create a client, list or convert tools, run a generation call, and close the client. MCP Apps add a browser-facing host responsibility: advertise app support, separate model-visible tools from app-visible tools, fetch a ui:// HTML resource, render it in a sandboxed iframe, and proxy allowed JSON-RPC requests back to the MCP server. Sources: content/docs/03-ai-sdk-core/16-mcp-tools.mdx, content/docs/03-ai-sdk-core/17-mcp-apps.mdx

Relevant Source Files

  • content/docs/03-ai-sdk-core/16-mcp-tools.mdx — First-party Core documentation for connecting to MCP servers, choosing transports, session reattachment, and converting MCP capabilities into AI SDK tools.
  • content/docs/03-ai-sdk-core/17-mcp-apps.mdx — First-party Core documentation for MCP Apps host flow, client capabilities, tool visibility, app resources, and iframe rendering responsibilities.
  • packages/mcp/README.md — Package-level usage guide for installing @ai-sdk/mcp, calling createMCPClient, using mcpClient.tools(), and closing clients after generation or streaming.
  • packages/react/src/mcp-apps/index.ts — React package export surface for the experimental MCP App renderer and related renderer, metadata, resource, bridge handler, and sandbox configuration types.

Core Primitives

The smallest useful MCP integration has three primitives: a client, a transport, and converted tools. The client is created with createMCPClient, the transport determines how the client reaches the MCP server, and the converted tools are passed through the standard AI SDK Core tools option. The MCP README shows installation with npm i @ai-sdk/mcp ai zod, then demonstrates fetching tools with mcpClient.tools() before calling a model. That keeps MCP tool use aligned with ordinary AI SDK tool calling rather than creating a separate execution path. Sources: packages/mcp/README.md, content/docs/03-ai-sdk-core/16-mcp-tools.mdx

Transport choice is a deployment decision, not just a syntax preference. The Core docs recommend HTTP transport for production deployments, including direct configuration with a URL, optional headers, an OAuth client provider, and redirect behavior. SSE is documented as another HTTP-based option, while stdio is specifically scoped to local development because it relies on standard input and output streams for a local server process. The README mirrors this split by showing HTTP, SSE, and Experimental_StdioMCPTransport examples, with stdio imported from the @ai-sdk/mcp/mcp-stdio subpath. Sources: content/docs/03-ai-sdk-core/16-mcp-tools.mdx, packages/mcp/README.md

MCP Tool Execution Flow

A typical server route or script starts by creating an MCP client with the appropriate transport and credentials. After connection, call mcpClient.tools() when you want the package to fetch definitions and convert them into AI SDK tool objects, or use lower-level definition APIs when an MCP Apps host needs to inspect visibility metadata first. Pass the resulting tools into generateText for a complete response or streamText for incremental output. The model then sees the converted tools through the same option shape used for local AI SDK tools. Sources: packages/mcp/README.md, content/docs/03-ai-sdk-core/16-mcp-tools.mdx

Client lifetime matters because the MCP client owns a connection to another server. The README wraps generateText in a try and finally so mcpClient.close() runs after the call, and it uses the onEnd callback to close the client when a streamText stream finishes. For multi-step tool use, the README example combines MCP tools with stopWhen: isStepCount(10), showing that MCP tools participate in the same loop-control mechanics as ordinary AI SDK tools. That pattern is useful when the model may need several tool calls before producing an answer. Sources: packages/mcp/README.md

HTTP session reattachment is the main edge case to plan for in longer-lived deployments. The docs show restoring a saved session id together with the previous initialize result, passing initialSessionId, initialProtocolVersion, terminateSessionOnClose: false, and initialInitializeResult. When cached initialize metadata is provided, the client can reuse it without sending another initialize request. If onSessionExpired fires, the transport has already cleared the session id and the failed request should be retried by creating a fresh client without the stale session or initialize data. Sources: content/docs/03-ai-sdk-core/16-mcp-tools.mdx, packages/mcp/README.md

MCP Apps Host Flow

MCP Apps are still based on ordinary MCP tools, but the host must understand additional UI metadata. The docs describe tools that point to a ui:// resource containing HTML, which the app renders inside a sandboxed iframe. This is a deliberate split of responsibilities: the model calls a tool, the server-side MCP host reads and normalizes the app resource, and the browser-side host renders the interactive UI while bridging approved JSON-RPC messages. Because an iframe can request app-visible tool calls, the host should proxy only allowed requests back to the MCP server. Sources: content/docs/03-ai-sdk-core/17-mcp-apps.mdx

An MCP Apps host should advertise app support only when it can render app resources safely. The docs use mcpAppClientCapabilities when creating the client, indicating support for text/html;profile=mcp-app resources. After connecting, the host lists tool definitions and applies splitMCPAppTools so only model-visible tools are passed to streamText or generateText. Tools marked for app visibility are not model inputs; they are kept for iframe-originated requests. This distinction prevents app-only operations from being exposed as model-callable actions. Sources: content/docs/03-ai-sdk-core/17-mcp-apps.mdx

When a model calls an app-backed tool, the MCP client preserves app metadata on the tool UI part, and that metadata becomes the bridge between the Core stream and the React renderer. The React package exposes experimental_MCPAppRenderer as the public component name for rendering the iframe. It also exports types for bridge handlers, app metadata, renderer props, app resources, and sandbox configuration. Those exports show that MCP Apps span both server-side Core work and client-side UI hosting, rather than living entirely in one package. Sources: content/docs/03-ai-sdk-core/17-mcp-apps.mdx, packages/react/src/mcp-apps/index.ts

Compact API and Configuration Reference

  • Install MCP client support with npm i @ai-sdk/mcp ai zod. Sources: packages/mcp/README.md
  • Create a client with createMCPClient({ transport: { type: 'http', url, headers, authProvider, redirect } }) for production-oriented HTTP use. Sources: content/docs/03-ai-sdk-core/16-mcp-tools.mdx
  • Use transport: { type: 'sse', url } for MCP servers that expose Server-Sent Events. Sources: packages/mcp/README.md
  • Use Experimental_StdioMCPTransport from @ai-sdk/mcp/mcp-stdio only for local MCP servers. Sources: packages/mcp/README.md
  • Convert tools with mcpClient.tools() for direct Core calls, or list definitions first when an MCP Apps host must split visibility. Sources: packages/mcp/README.md, content/docs/03-ai-sdk-core/17-mcp-apps.mdx
  • Pass converted tools to generateText or streamText with the normal AI SDK Core tools option. Sources: packages/mcp/README.md
  • For MCP Apps, use mcpAppClientCapabilities, splitMCPAppTools, and readMCPAppResource in the host flow. Sources: content/docs/03-ai-sdk-core/17-mcp-apps.mdx
  • Render app resources with experimental_MCPAppRenderer from the React MCP Apps export surface. Sources: packages/react/src/mcp-apps/index.ts

Implementation Guidance

Choose the simplest integration that matches the user experience you are building. If your application only needs remote actions or data lookup, treat MCP as an external tool source and keep the UI exactly like any other AI SDK chat or agent flow. If the remote capability needs its own interactive surface, implement the MCP Apps host flow and make the visibility boundary explicit. In both cases, keep transport credentials on the server, close clients after work completes, and avoid advertising app capabilities until your host can sandbox HTML resources and control iframe bridge requests. Sources: content/docs/03-ai-sdk-core/16-mcp-tools.mdx, content/docs/03-ai-sdk-core/17-mcp-apps.mdx, packages/mcp/README.md

A good next step is to read the general tool-calling and streaming pages before building a complex MCP workflow. MCP tools enter the same model loop as local tools, so settings such as step limits, active tools, callbacks, and streaming response conversion still shape behavior. Then move to the UI stream and transport material if you are building MCP Apps, because the app renderer depends on tool UI parts reaching the browser. For provider-specific alternatives, note that the MCP tools docs call out OpenAI Responses API support through openai.tools.mcp, which can avoid conversion in that provider path. Sources: content/docs/03-ai-sdk-core/16-mcp-tools.mdx, content/docs/03-ai-sdk-core/17-mcp-apps.mdx

Ask a question...