Backport: feat(packages/mcp): add support for MCP server prompts exposed (#9994)

This is an automated backport of #9957 to the release-v5.0 branch.

Co-authored-by: Aayush Kapoor <[email protected]>

Author: vercel-ai-sdk[bot]

.changeset/fast-bobcats-relate.md

@@ -0,0 +1,5 @@
+---
+'@ai-sdk/mcp': patch
+---
+
+feat(packages/mcp): add support for MCP server prompts exposed

content/docs/03-ai-sdk-core/16-mcp-tools.mdx

@@ -9,8 +9,8 @@ description: Learn how to connect to Model Context Protocol (MCP) servers and us
   The MCP tools feature is experimental and may change in the future.
 </Note>
 
-The AI SDK supports connecting to [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers to access their tools.
-This enables your AI applications to discover and use tools across various services through a standardized interface.
+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.
 
 ## Initializing an MCP Client
 
@@ -226,6 +226,27 @@ Resource templates are dynamic URI patterns that allow flexible queries. List al
 const templates = await mcpClient.listResourceTemplates();
 ```
 
+## 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; }' },
+});
+```
+
 ## Examples
 
 You can see MCP tools in action in the following example:

content/docs/07-reference/01-ai-sdk-core/23-create-mcp-client.mdx

@@ -9,6 +9,7 @@ Creates a lightweight Model Context Protocol (MCP) client that connects to an MC
 
 - **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
 
 It currently does not support accepting notifications from an MCP server, and custom configuration of the client.
 
@@ -235,6 +236,68 @@ Returns a Promise that resolves to an `MCPClient` with the following methods:
         },
       ],
     },
+    {
+      name: 'listPrompts',
+      type: `async (options?: {
+        params?: PaginatedRequest['params'];
+        options?: RequestOptions;
+      }) => Promise<ListPromptsResult>`,
+      description: 'Lists available prompts 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: 'getPrompt',
+      type: `async (args: {
+        name: string;
+        arguments?: Record<string, unknown>;
+        options?: RequestOptions;
+      }) => Promise<GetPromptResult>`,
+      description: 'Retrieves a prompt by name, optionally passing arguments.',
+      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: 'close',
       type: 'async () => void',

examples/mcp/README.md

@@ -18,44 +18,38 @@ pnpm install
 pnpm build
 ```
 
-## Streamable HTTP Transport (Stateful)
+## Running Examples
 
-Start server
+Start the server for a specific example
 
 ```sh
-pnpm http:server
+pnpm server:<folder-name>
 ```
 
-Run example:
+Run the client for a specific example
 
 ```sh
-pnpm http:client
+pnpm client:<folder-name>
 ```
 
-## Stdio Transport
+Available examples/folders:
 
-Build
+- `sse` - SSE Transport (Legacy)
+- `http` - Streamable HTTP Transport (Stateful)
+- `mcp-with-auth` - MCP with authentication
+- `mcp-prompts` - MCP prompts example
+- `mcp-resources` - MCP resources example
+- `stdio` - Stdio Transport (requires `pnpm stdio:build` first)
 
-```sh
-pnpm stdio:build
-```
-
-Run example:
-
-```sh
-pnpm stdio:client
-```
-
-## SSE Transport (Legacy)
-
-Start server
+Example usage:
 
 ```sh
-pnpm sse:server
+# Start the HTTP server
+pnpm server:http
 ```
 
-Run example:
+In another terminal, run the HTTP client:
 
 ```sh
-pnpm sse:client
+pnpm client:http
 ```

examples/mcp/package.json

@@ -3,14 +3,18 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "sse:server": "tsx src/sse/server.ts",
-    "sse:client": "tsx src/sse/client.ts",
-    "sse-auth:server": "tsx src/mcp-with-auth/server.ts",
-    "sse-auth:client": "tsx src/mcp-with-auth/client.ts",
+    "server:sse": "tsx src/sse/server.ts",
+    "client:sse": "tsx src/sse/client.ts",
+    "server:http": "tsx src/http/server.ts",
+    "client:http": "tsx src/http/client.ts",
+    "server:mcp-with-auth": "tsx src/mcp-with-auth/server.ts",
+    "client:mcp-with-auth": "tsx src/mcp-with-auth/client.ts",
+    "server:mcp-prompts": "tsx src/mcp-prompts/server.ts",
+    "client:mcp-prompts": "tsx src/mcp-prompts/client.ts",
+    "server:mcp-resources": "tsx src/mcp-resources/server.ts",
+    "client:mcp-resources": "tsx src/mcp-resources/client.ts",
     "stdio:build": "tsc src/stdio/server.ts --outDir src/stdio/dist --target es2023 --module nodenext",
-    "stdio:client": "tsx src/stdio/client.ts",
-    "http:server": "tsx src/http/server.ts",
-    "http:client": "tsx src/http/client.ts",
+    "client:stdio": "tsx src/stdio/client.ts",
     "custom-transport:build": "tsc src/custom-transport/server.ts --outDir src/custom-transport/dist --target es2023 --module nodenext",
     "custom-transport:client": "tsx src/custom-transport/client.ts",
     "type-check": "tsc --build"

examples/mcp/src/mcp-prompts/client.ts

@@ -0,0 +1,30 @@
+import { experimental_createMCPClient } from '@ai-sdk/mcp';
+
+async function main() {
+  const mcpClient = await experimental_createMCPClient({
+    transport: {
+      type: 'sse',
+      url: 'http://localhost:8083/sse',
+    },
+  });
+
+  try {
+    const prompts = await mcpClient.listPrompts();
+    console.log('PROMPTS:', JSON.stringify(prompts, null, 2));
+
+    const prompt = await mcpClient.getPrompt({
+      name: 'code_review',
+      arguments: {
+        code: 'function add(a, b) { return a + b; }\n',
+      },
+    });
+    console.log('GET PROMPT:', JSON.stringify(prompt, null, 2));
+  } finally {
+    await mcpClient.close();
+  }
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

examples/mcp/src/mcp-prompts/server.ts

@@ -0,0 +1,46 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import express from 'express';
+import { z } from 'zod';
+
+const app = express();
+
+const server = new McpServer({
+  name: 'mcp-prompts-example',
+  version: '1.0.0',
+});
+
+server.prompt(
+  'code_review',
+  'Asks the LLM to analyze code quality and suggest improvements',
+  { code: z.string() },
+  async ({ code }) => {
+    return {
+      description: 'Code review prompt',
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Please review this code and suggest improvements:\n${code}`,
+          },
+        },
+      ],
+    };
+  },
+);
+
+let transport: SSEServerTransport;
+
+app.get('/sse', async (_req, res) => {
+  transport = new SSEServerTransport('/messages', res);
+  await server.connect(transport);
+});
+
+app.post('/messages', async (req, res) => {
+  await transport.handlePostMessage(req, res);
+});
+
+app.listen(8083, () => {
+  console.log('MCP prompts example server listening on http://localhost:8083');
+});

packages/mcp/src/tool/mcp-client.test.ts

@@ -7,6 +7,8 @@ import {
   ListResourceTemplatesResult,
   ListResourcesResult,
   ReadResourceResult,
+  ListPromptsResult,
+  GetPromptResult,
 } from './types';
 import {
   beforeEach,
@@ -148,6 +150,80 @@ describe('MCPClient', () => {
     `);
   });
 
+  it('should list prompts from the server', async () => {
+    client = await createMCPClient({
+      transport: { type: 'sse', url: 'https://example.com/sse' },
+    });
+
+    const prompts = await client.listPrompts();
+
+    expectTypeOf(prompts).toEqualTypeOf<ListPromptsResult>();
+
+    expect(prompts.prompts).toMatchInlineSnapshot(`
+      [
+        {
+          "arguments": [
+            {
+              "description": "The code to review",
+              "name": "code",
+              "required": true,
+            },
+          ],
+          "description": "Asks the LLM to analyze code quality and suggest improvements",
+          "name": "code_review",
+          "title": "Request Code Review",
+        },
+      ]
+    `);
+  });
+
+  it('should get a prompt by name', async () => {
+    client = await createMCPClient({
+      transport: { type: 'sse', url: 'https://example.com/sse' },
+    });
+
+    const prompt = await client.getPrompt({
+      name: 'code_review',
+      arguments: { code: 'print(42)' },
+    });
+
+    expectTypeOf(prompt).toEqualTypeOf<GetPromptResult>();
+
+    expect(prompt).toMatchInlineSnapshot(`
+      {
+        "description": "Code review prompt",
+        "messages": [
+          {
+            "content": {
+              "text": "Please review this code:\nfunction add(a, b) { return a + b; }",
+              "type": "text",
+            },
+            "role": "user",
+          },
+        ],
+      }
+    `);
+  });
+
+  it('should throw if the server does not support prompts', async () => {
+    createMockTransport.mockImplementation(
+      () =>
+        new MockMCPTransport({
+          resources: [],
+          prompts: [],
+        }),
+    );
+
+    client = await createMCPClient({
+      transport: { type: 'sse', url: 'https://example.com/sse' },
+    });
+
+    await expect(client.listPrompts()).rejects.toThrow(MCPClientError);
+    await expect(client.getPrompt({ name: 'code_review' })).rejects.toThrow(
+      MCPClientError,
+    );
+  });
+
   it('should return typed AI SDK compatible tool set when schemas are provided', async () => {
     const mockTransport = new MockMCPTransport({
       overrideTools: [