@mastra/mcp 1.0.0-beta.6 → 1.0.0-beta.8

package/dist/docs/tools/01-reference.md

@@ -0,0 +1,2005 @@
+# Tools API Reference
+
+> API reference for tools - 3 entries
+
+
+---
+
+## Reference: MCPClient
+
+> API Reference for MCPClient - A class for managing multiple Model Context Protocol servers and their tools.
+
+The `MCPClient` class provides a way to manage multiple MCP server connections and their tools in a Mastra application. It handles connection lifecycle, tool namespacing, and provides access to tools across all configured servers.
+
+This class replaces the deprecated [`MastraMCPClient`](https://mastra.ai/reference/v1/tools/client).
+
+## Constructor
+
+Creates a new instance of the MCPClient class.
+
+```typescript
+constructor({
+  id?: string;
+  servers: Record<string, MastraMCPServerDefinition>;
+  timeout?: number;
+}: MCPClientOptions)
+```
+
+### MCPClientOptions
+
+<br />
+
+### MastraMCPServerDefinition
+
+Each server in the `servers` map is configured using the `MastraMCPServerDefinition` type. The transport type is detected based on the provided parameters:
+
+- If `command` is provided, it uses the Stdio transport.
+- If `url` is provided, it first attempts to use the Streamable HTTP transport and falls back to the legacy SSE transport if the initial connection fails.
+
+<br />
+
+## Methods
+
+### listTools()
+
+Retrieves all tools from all configured servers, with tool names namespaced by their server name (in the format `serverName_toolName`) to prevent conflicts.
+Intended to be passed onto an Agent definition.
+
+```ts
+new Agent({ tools: await mcp.listTools() });
+```
+
+### listToolsets()
+
+Returns an object mapping namespaced tool names (in the format `serverName.toolName`) to their tool implementations.
+Intended to be passed dynamically into the generate or stream method.
+
+```typescript
+const res = await agent.stream(prompt, {
+  toolsets: await mcp.listToolsets(),
+});
+```
+
+### disconnect()
+
+Disconnects from all MCP servers and cleans up resources.
+
+```typescript
+async disconnect(): Promise<void>
+```
+
+### `resources` Property
+
+The `MCPClient` instance has a `resources` property that provides access to resource-related operations.
+
+```typescript
+const mcpClient = new MCPClient({
+  /* ...servers configuration... */
+});
+
+// Access resource methods via mcpClient.resources
+const allResourcesByServer = await mcpClient.resources.list();
+const templatesByServer = await mcpClient.resources.templates();
+// ... and so on for other resource methods.
+```
+
+#### `resources.list()`
+
+Retrieves all available resources from all connected MCP servers, grouped by server name.
+
+```typescript
+async list(): Promise<Record<string, Resource[]>>
+```
+
+Example:
+
+```typescript
+const resourcesByServer = await mcpClient.resources.list();
+for (const serverName in resourcesByServer) {
+  console.log(`Resources from ${serverName}:`, resourcesByServer[serverName]);
+}
+```
+
+#### `resources.templates()`
+
+Retrieves all available resource templates from all connected MCP servers, grouped by server name.
+
+```typescript
+async templates(): Promise<Record<string, ResourceTemplate[]>>
+```
+
+Example:
+
+```typescript
+const templatesByServer = await mcpClient.resources.templates();
+for (const serverName in templatesByServer) {
+  console.log(`Templates from ${serverName}:`, templatesByServer[serverName]);
+}
+```
+
+#### `resources.read(serverName: string, uri: string)`
+
+Reads the content of a specific resource from a named server.
+
+```typescript
+async read(serverName: string, uri: string): Promise<ReadResourceResult>
+```
+
+- `serverName`: The identifier of the server (key used in the `servers` constructor option).
+- `uri`: The URI of the resource to read.
+
+Example:
+
+```typescript
+const content = await mcpClient.resources.read(
+  "myWeatherServer",
+  "weather://current",
+);
+console.log("Current weather:", content.contents[0].text);
+```
+
+#### `resources.subscribe(serverName: string, uri: string)`
+
+Subscribes to updates for a specific resource on a named server.
+
+```typescript
+async subscribe(serverName: string, uri: string): Promise<object>
+```
+
+Example:
+
+```typescript
+await mcpClient.resources.subscribe("myWeatherServer", "weather://current");
+```
+
+#### `resources.unsubscribe(serverName: string, uri: string)`
+
+Unsubscribes from updates for a specific resource on a named server.
+
+```typescript
+async unsubscribe(serverName: string, uri: string): Promise<object>
+```
+
+Example:
+
+```typescript
+await mcpClient.resources.unsubscribe("myWeatherServer", "weather://current");
+```
+
+#### `resources.onUpdated(serverName: string, handler: (params: { uri: string }) => void)`
+
+Sets a notification handler that will be called when a subscribed resource on a specific server is updated.
+
+```typescript
+async onUpdated(serverName: string, handler: (params: { uri: string }) => void): Promise<void>
+```
+
+Example:
+
+```typescript
+mcpClient.resources.onUpdated("myWeatherServer", (params) => {
+  console.log(`Resource updated on myWeatherServer: ${params.uri}`);
+  // You might want to re-fetch the resource content here
+  // await mcpClient.resources.read("myWeatherServer", params.uri);
+});
+```
+
+#### `resources.onListChanged(serverName: string, handler: () => void)`
+
+Sets a notification handler that will be called when the overall list of available resources changes on a specific server.
+
+```typescript
+async onListChanged(serverName: string, handler: () => void): Promise<void>
+```
+
+Example:
+
+```typescript
+mcpClient.resources.onListChanged("myWeatherServer", () => {
+  console.log("Resource list changed on myWeatherServer.");
+  // You should re-fetch the list of resources
+  // await mcpClient.resources.list();
+});
+```
+
+### `elicitation` Property
+
+The `MCPClient` instance has an `elicitation` property that provides access to elicitation-related operations. Elicitation allows MCP servers to request structured information from users.
+
+```typescript
+const mcpClient = new MCPClient({
+  /* ...servers configuration... */
+});
+
+// Set up elicitation handler
+mcpClient.elicitation.onRequest("serverName", async (request) => {
+  // Handle elicitation request from server
+  console.log("Server requests:", request.message);
+  console.log("Schema:", request.requestedSchema);
+
+  // Return user response
+  return {
+    action: "accept",
+    content: { name: "John Doe", email: "john@example.com" },
+  };
+});
+```
+
+#### `elicitation.onRequest(serverName: string, handler: ElicitationHandler)`
+
+Sets up a handler function that will be called when any connected MCP server sends an elicitation request. The handler receives the request and must return a response.
+
+**ElicitationHandler Function:**
+
+The handler function receives a request object with:
+
+- `message`: A human-readable message describing what information is needed
+- `requestedSchema`: A JSON schema defining the structure of the expected response
+
+The handler must return an `ElicitResult` with:
+
+- `action`: One of `'accept'`, `'decline'`, or `'cancel'`
+- `content`: The user's data (only when action is `'accept'`)
+
+**Example:**
+
+```typescript
+mcpClient.elicitation.onRequest("serverName", async (request) => {
+  console.log(`Server requests: ${request.message}`);
+
+  // Example: Simple user input collection
+  if (request.requestedSchema.properties.name) {
+    // Simulate user accepting and providing data
+    return {
+      action: "accept",
+      content: {
+        name: "Alice Smith",
+        email: "alice@example.com",
+      },
+    };
+  }
+
+  // Simulate user declining the request
+  return { action: "decline" };
+});
+```
+
+**Complete Interactive Example:**
+
+```typescript
+import { MCPClient } from "@mastra/mcp";
+import { createInterface } from "readline";
+
+const readline = createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+function askQuestion(question: string): Promise<string> {
+  return new Promise((resolve) => {
+    readline.question(question, (answer) => resolve(answer.trim()));
+  });
+}
+
+const mcpClient = new MCPClient({
+  servers: {
+    interactiveServer: {
+      url: new URL("http://localhost:3000/mcp"),
+    },
+  },
+});
+
+// Set up interactive elicitation handler
+await mcpClient.elicitation.onRequest("interactiveServer", async (request) => {
+  console.log(`\n📋 Server Request: ${request.message}`);
+  console.log("Required information:");
+
+  const schema = request.requestedSchema;
+  const properties = schema.properties || {};
+  const required = schema.required || [];
+  const content: Record<string, any> = {};
+
+  // Collect input for each field
+  for (const [fieldName, fieldSchema] of Object.entries(properties)) {
+    const field = fieldSchema as any;
+    const isRequired = required.includes(fieldName);
+
+    let prompt = `${field.title || fieldName}`;
+    if (field.description) prompt += ` (${field.description})`;
+    if (isRequired) prompt += " *required*";
+    prompt += ": ";
+
+    const answer = await askQuestion(prompt);
+
+    // Handle cancellation
+    if (answer.toLowerCase() === "cancel") {
+      return { action: "cancel" };
+    }
+
+    // Validate required fields
+    if (answer === "" && isRequired) {
+      console.log(`❌ ${fieldName} is required`);
+      return { action: "decline" };
+    }
+
+    if (answer !== "") {
+      content[fieldName] = answer;
+    }
+  }
+
+  // Confirm submission
+  console.log("\n📝 You provided:");
+  console.log(JSON.stringify(content, null, 2));
+
+  const confirm = await askQuestion(
+    "\nSubmit this information? (yes/no/cancel): ",
+  );
+
+  if (confirm.toLowerCase() === "yes" || confirm.toLowerCase() === "y") {
+    return { action: "accept", content };
+  } else if (confirm.toLowerCase() === "cancel") {
+    return { action: "cancel" };
+  } else {
+    return { action: "decline" };
+  }
+});
+```
+
+### `prompts` Property
+
+The `MCPClient` instance has a `prompts` property that provides access to prompt-related operations.
+
+```typescript
+const mcpClient = new MCPClient({
+  /* ...servers configuration... */
+});
+
+// Access prompt methods via mcpClient.prompts
+const allPromptsByServer = await mcpClient.prompts.list();
+const { prompt, messages } = await mcpClient.prompts.get({
+  serverName: "myWeatherServer",
+  name: "current",
+});
+```
+
+#### `prompts.list()`
+
+Retrieves all available prompts from all connected MCP servers, grouped by server name.
+
+```typescript
+async list(): Promise<Record<string, Prompt[]>>
+```
+
+Example:
+
+```typescript
+const promptsByServer = await mcpClient.prompts.list();
+for (const serverName in promptsByServer) {
+  console.log(`Prompts from ${serverName}:`, promptsByServer[serverName]);
+}
+```
+
+#### `prompts.get({ serverName, name, args?, version? })`
+
+Retrieves a specific prompt and its messages from a server.
+
+```typescript
+async get({
+  serverName,
+  name,
+  args?,
+  version?,
+}: {
+  serverName: string;
+  name: string;
+  args?: Record<string, any>;
+  version?: string;
+}): Promise<{ prompt: Prompt; messages: PromptMessage[] }>
+```
+
+Example:
+
+```typescript
+const { prompt, messages } = await mcpClient.prompts.get({
+  serverName: "myWeatherServer",
+  name: "current",
+  args: { location: "London" },
+});
+console.log(prompt);
+console.log(messages);
+```
+
+#### `prompts.onListChanged(serverName: string, handler: () => void)`
+
+Sets a notification handler that will be called when the list of available prompts changes on a specific server.
+
+```typescript
+async onListChanged(serverName: string, handler: () => void): Promise<void>
+```
+
+Example:
+
+```typescript
+mcpClient.prompts.onListChanged("myWeatherServer", () => {
+  console.log("Prompt list changed on myWeatherServer.");
+  // You should re-fetch the list of prompts
+  // await mcpClient.prompts.list();
+});
+```
+
+### `progress` Property
+
+The `MCPClient` instance has a `progress` property for subscribing to progress notifications emitted by MCP servers while tools execute.
+
+```typescript
+const mcpClient = new MCPClient({
+  servers: {
+    myServer: {
+      url: new URL('http://localhost:4111/api/mcp/myServer/mcp'),
+      // Enabled by default; set to false to disable
+      enableProgressTracking: true,
+    },
+  },
+});
+
+// Subscribe to progress updates for a specific server
+await mcpClient.progress.onUpdate('myServer', (params) => {
+  console.log('📊 Progress:', params.progress, '/', params.total);
+  if (params.message) console.log('Message:', params.message);
+  if (params.progressToken) console.log('Token:', params.progressToken);
+});
+```
+
+#### `progress.onUpdate(serverName: string, handler)`
+
+Registers a handler function to receive progress updates from the specified server.
+
+```typescript
+async onUpdate(
+  serverName: string,
+  handler: (params: {
+    progressToken: string;
+    progress: number;
+    total?: number;
+    message?: string;
+  }) => void,
+): Promise<void>
+```
+
+Notes:
+
+- When `enableProgressTracking` is true (default), tool calls include a `progressToken` so you can correlate updates to a specific run.
+- If you pass a `runId` when executing a tool, it will be used as the `progressToken`.
+
+To disable progress tracking for a server:
+
+```typescript
+const mcpClient = new MCPClient({
+  servers: {
+    myServer: {
+      url: new URL('http://localhost:4111/api/mcp/myServer/mcp'),
+      enableProgressTracking: false,
+    },
+  },
+});
+```
+
+## Elicitation
+
+Elicitation is a feature that allows MCP servers to request structured information from users. When a server needs additional data, it can send an elicitation request that the client handles by prompting the user. A common example is during a tool call.
+
+### How Elicitation Works
+
+1. **Server Request**: An MCP server tool calls `server.elicitation.sendRequest()` with a message and schema
+2. **Client Handler**: Your elicitation handler function is called with the request
+3. **User Interaction**: Your handler collects user input (via UI, CLI, etc.)
+4. **Response**: Your handler returns the user's response (accept/decline/cancel)
+5. **Tool Continuation**: The server tool receives the response and continues execution
+
+### Setting Up Elicitation
+
+You must set up an elicitation handler before tools that use elicitation are called:
+
+```typescript
+import { MCPClient } from "@mastra/mcp";
+
+const mcpClient = new MCPClient({
+  servers: {
+    interactiveServer: {
+      url: new URL("http://localhost:3000/mcp"),
+    },
+  },
+});
+
+// Set up elicitation handler
+mcpClient.elicitation.onRequest("interactiveServer", async (request) => {
+  // Handle the server's request for user input
+  console.log(`Server needs: ${request.message}`);
+
+  // Your logic to collect user input
+  const userData = await collectUserInput(request.requestedSchema);
+
+  return {
+    action: "accept",
+    content: userData,
+  };
+});
+```
+
+### Response Types
+
+Your elicitation handler must return one of three response types:
+
+- **Accept**: User provided data and confirmed submission
+
+  ```typescript
+  return {
+    action: "accept",
+    content: { name: "John Doe", email: "john@example.com" },
+  };
+  ```
+
+- **Decline**: User explicitly declined to provide the information
+
+  ```typescript
+  return { action: "decline" };
+  ```
+
+- **Cancel**: User dismissed or cancelled the request
+  ```typescript
+  return { action: "cancel" };
+  ```
+
+### Schema-Based Input Collection
+
+The `requestedSchema` provides structure for the data the server needs:
+
+```typescript
+await mcpClient.elicitation.onRequest("interactiveServer", async (request) => {
+  const { properties, required = [] } = request.requestedSchema;
+  const content: Record<string, any> = {};
+
+  for (const [fieldName, fieldSchema] of Object.entries(properties || {})) {
+    const field = fieldSchema as any;
+    const isRequired = required.includes(fieldName);
+
+    // Collect input based on field type and requirements
+    const value = await promptUser({
+      name: fieldName,
+      title: field.title,
+      description: field.description,
+      type: field.type,
+      required: isRequired,
+      format: field.format,
+      enum: field.enum,
+    });
+
+    if (value !== null) {
+      content[fieldName] = value;
+    }
+  }
+
+  return { action: "accept", content };
+});
+```
+
+### Best Practices
+
+- **Always handle elicitation**: Set up your handler before calling tools that might use elicitation
+- **Validate input**: Check that required fields are provided
+- **Respect user choice**: Handle decline and cancel responses gracefully
+- **Clear UI**: Make it obvious what information is being requested and why
+- **Security**: Never auto-accept requests for sensitive information
+
+## Examples
+
+### Static Tool Configuration
+
+For tools where you have a single connection to the MCP server for you entire app, use `listTools()` and pass the tools to your agent:
+
+```typescript
+import { MCPClient } from "@mastra/mcp";
+import { Agent } from "@mastra/core/agent";
+
+const mcp = new MCPClient({
+  servers: {
+    stockPrice: {
+      command: "npx",
+      args: ["tsx", "stock-price.ts"],
+      env: {
+        API_KEY: "your-api-key",
+      },
+      log: (logMessage) => {
+        console.log(`[${logMessage.level}] ${logMessage.message}`);
+      },
+    },
+    weather: {
+      url: new URL("http://localhost:8080/sse"),
+    },
+  },
+  timeout: 30000, // Global 30s timeout
+});
+
+// Create an agent with access to all tools
+const agent = new Agent({
+  name: "Multi-tool Agent",
+  instructions: "You have access to multiple tool servers.",
+  model: "openai/gpt-5.1",
+  tools: await mcp.listTools(),
+});
+
+// Example of using resource methods
+async function checkWeatherResource() {
+  try {
+    const weatherResources = await mcp.resources.list();
+    if (weatherResources.weather && weatherResources.weather.length > 0) {
+      const currentWeatherURI = weatherResources.weather[0].uri;
+      const weatherData = await mcp.resources.read(
+        "weather",
+        currentWeatherURI,
+      );
+      console.log("Weather data:", weatherData.contents[0].text);
+    }
+  } catch (error) {
+    console.error("Error fetching weather resource:", error);
+  }
+}
+checkWeatherResource();
+
+// Example of using prompt methods
+async function checkWeatherPrompt() {
+  try {
+    const weatherPrompts = await mcp.prompts.list();
+    if (weatherPrompts.weather && weatherPrompts.weather.length > 0) {
+      const currentWeatherPrompt = weatherPrompts.weather.find(
+        (p) => p.name === "current",
+      );
+      if (currentWeatherPrompt) {
+        console.log("Weather prompt:", currentWeatherPrompt);
+      } else {
+        console.log("Current weather prompt not found");
+      }
+    }
+  } catch (error) {
+    console.error("Error fetching weather prompt:", error);
+  }
+}
+checkWeatherPrompt();
+```
+
+### Dynamic toolsets
+
+When you need a new MCP connection for each user, use `listToolsets()` and add the tools when calling stream or generate:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { MCPClient } from "@mastra/mcp";
+
+// Create the agent first, without any tools
+const agent = new Agent({
+  name: "Multi-tool Agent",
+  instructions: "You help users check stocks and weather.",
+  model: "openai/gpt-5.1",
+});
+
+// Later, configure MCP with user-specific settings
+const mcp = new MCPClient({
+  servers: {
+    stockPrice: {
+      command: "npx",
+      args: ["tsx", "stock-price.ts"],
+      env: {
+        API_KEY: "user-123-api-key",
+      },
+      timeout: 20000, // Server-specific timeout
+    },
+    weather: {
+      url: new URL("http://localhost:8080/sse"),
+      requestInit: {
+        headers: {
+          Authorization: `Bearer user-123-token`,
+        },
+      },
+    },
+  },
+});
+
+// Pass all toolsets to stream() or generate()
+const response = await agent.stream(
+  "How is AAPL doing and what is the weather?",
+  {
+    toolsets: await mcp.listToolsets(),
+  },
+);
+```
+
+## Instance Management
+
+The `MCPClient` class includes built-in memory leak prevention for managing multiple instances:
+
+1. Creating multiple instances with identical configurations without an `id` will throw an error to prevent memory leaks
+2. If you need multiple instances with identical configurations, provide a unique `id` for each instance
+3. Call `await configuration.disconnect()` before recreating an instance with the same configuration
+4. If you only need one instance, consider moving the configuration to a higher scope to avoid recreation
+
+For example, if you try to create multiple instances with the same configuration without an `id`:
+
+```typescript
+// First instance - OK
+const mcp1 = new MCPClient({
+  servers: {
+    /* ... */
+  },
+});
+
+// Second instance with same config - Will throw an error
+const mcp2 = new MCPClient({
+  servers: {
+    /* ... */
+  },
+});
+
+// To fix, either:
+// 1. Add unique IDs
+const mcp3 = new MCPClient({
+  id: "instance-1",
+  servers: {
+    /* ... */
+  },
+});
+
+// 2. Or disconnect before recreating
+await mcp1.disconnect();
+const mcp4 = new MCPClient({
+  servers: {
+    /* ... */
+  },
+});
+```
+
+## Server Lifecycle
+
+MCPClient handles server connections gracefully:
+
+1. Automatic connection management for multiple servers
+2. Graceful server shutdown to prevent error messages during development
+3. Proper cleanup of resources when disconnecting
+
+## Using Custom Fetch for Dynamic Authentication
+
+For HTTP servers, you can provide a custom `fetch` function to handle dynamic authentication, request interception, or other custom behavior. This is particularly useful when you need to refresh tokens on each request or customize request behavior.
+
+When `fetch` is provided, `requestInit`, `eventSourceInit`, and `authProvider` become optional, as you can handle these concerns within your custom fetch function.
+
+```typescript
+const mcpClient = new MCPClient({
+  servers: {
+    apiServer: {
+      url: new URL("https://api.example.com/mcp"),
+      fetch: async (url, init) => {
+        // Refresh token on each request
+        const token = await getAuthToken(); // Your token refresh logic
+        
+        return fetch(url, {
+          ...init,
+          headers: {
+            ...init?.headers,
+            Authorization: `Bearer ${token}`,
+          },
+        });
+      },
+    },
+  },
+});
+```
+
+## Using SSE Request Headers
+
+When using the legacy SSE MCP transport, you must configure both `requestInit` and `eventSourceInit` due to a bug in the MCP SDK. Alternatively, you can use a custom `fetch` function which will be automatically used for both POST requests and SSE connections:
+
+```ts
+// Option 1: Using requestInit and eventSourceInit (required for SSE)
+const sseClient = new MCPClient({
+  servers: {
+    exampleServer: {
+      url: new URL("https://your-mcp-server.com/sse"),
+      // Note: requestInit alone isn't enough for SSE
+      requestInit: {
+        headers: {
+          Authorization: "Bearer your-token",
+        },
+      },
+      // This is also required for SSE connections with custom headers
+      eventSourceInit: {
+        fetch(input: Request | URL | string, init?: RequestInit) {
+          const headers = new Headers(init?.headers || {});
+          headers.set("Authorization", "Bearer your-token");
+          return fetch(input, {
+            ...init,
+            headers,
+          });
+        },
+      },
+    },
+  },
+});
+
+// Option 2: Using custom fetch (simpler, works for both Streamable HTTP and SSE)
+const sseClientWithFetch = new MCPClient({
+  servers: {
+    exampleServer: {
+      url: new URL("https://your-mcp-server.com/sse"),
+      fetch: async (url, init) => {
+        const headers = new Headers(init?.headers || {});
+        headers.set("Authorization", "Bearer your-token");
+        return fetch(url, {
+          ...init,
+          headers,
+        });
+      },
+    },
+  },
+});
+```
+
+## Related Information
+
+- For creating MCP servers, see the [MCPServer documentation](./mcp-server).
+- For more about the Model Context Protocol, see the [@modelcontextprotocol/sdk documentation](https://github.com/modelcontextprotocol/typescript-sdk).
+
+---
+
+## Reference: MCPServer
+
+> API Reference for MCPServer - A class for exposing Mastra tools and capabilities as a Model Context Protocol server.
+
+The `MCPServer` class provides the functionality to expose your existing Mastra tools and Agents as a Model Context Protocol (MCP) server. This allows any MCP client (like Cursor, Windsurf, or Claude Desktop) to connect to these capabilities and make them available to an agent.
+
+Note that if you only need to use your tools or agents directly within your Mastra application, you don't necessarily need to create an MCP server. This API is specifically for exposing your Mastra tools and agents to _external_ MCP clients.
+
+It supports both [stdio (subprocess) and SSE (HTTP) MCP transports](https://modelcontextprotocol.io/docs/concepts/transports).
+
+## Constructor
+
+To create a new `MCPServer`, you need to provide some basic information about your server, the tools it will offer, and optionally, any agents you want to expose as tools.
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { createTool } from "@mastra/core/tools";
+import { MCPServer } from "@mastra/mcp";
+import { z } from "zod";
+import { dataProcessingWorkflow } from "../workflows/dataProcessingWorkflow";
+
+const myAgent = new Agent({
+  id: "my-example-agent",
+  name: "MyExampleAgent",
+  description: "A generalist to help with basic questions."
+  instructions: "You are a helpful assistant.",
+  model: "openai/gpt-5.1",
+});
+
+const weatherTool = createTool({
+  id: "getWeather",
+  description: "Gets the current weather for a location.",
+  inputSchema: z.object({ location: z.string() }),
+  execute: async (inputData) => `Weather in ${inputData.location} is sunny.`,
+});
+
+const server = new MCPServer({
+  id: "my-custom-server",
+  name: "My Custom Server",
+  version: "1.0.0",
+  description: "A server that provides weather data and agent capabilities",
+  instructions: "Use the available tools to help users with weather information and data processing tasks.",
+  tools: { weatherTool },
+  agents: { myAgent }, // this agent will become tool "ask_myAgent"
+  workflows: {
+    dataProcessingWorkflow, // this workflow will become tool "run_dataProcessingWorkflow"
+  }
+});
+```
+
+### Configuration Properties
+
+The constructor accepts an `MCPServerConfig` object with the following properties:
+
+## Exposing Agents as Tools
+
+A powerful feature of `MCPServer` is its ability to automatically expose your Mastra Agents as callable tools. When you provide agents in the `agents` property of the configuration:
+
+- **Tool Naming**: Each agent is converted into a tool named `ask_<agentKey>`, where `<agentKey>` is the key you used for that agent in the `agents` object. For instance, if you configure `agents: { myAgentKey: myAgentInstance }`, a tool named `ask_myAgentKey` will be created.
+
+- **Tool Functionality**:
+  - **Description**: The generated tool's description will be in the format: "Ask agent `<AgentName>` a question. Original agent instructions: `<agent description>`".
+  - **Input**: The tool expects a single object argument with a `message` property (string): `{ message: "Your question for the agent" }`.
+  - **Execution**: When this tool is called, it invokes the `generate()` method of the corresponding agent, passing the provided `query`.
+  - **Output**: The direct result from the agent's `generate()` method is returned as the output of the tool.
+
+- **Name Collisions**: If an explicit tool defined in the `tools` configuration has the same name as an agent-derived tool (e.g., you have a tool named `ask_myAgentKey` and also an agent with the key `myAgentKey`), the _explicitly defined tool will take precedence_. The agent will not be converted into a tool in this conflicting case, and a warning will be logged.
+
+This makes it straightforward to allow MCP clients to interact with your agents using natural language queries, just like any other tool.
+
+### Agent-to-Tool Conversion
+
+When you provide agents in the `agents` configuration property, `MCPServer` will automatically create a corresponding tool for each agent. The tool will be named `ask_<agentIdentifier>`, where `<agentIdentifier>` is the key you used in the `agents` object.
+
+The description for this generated tool will be: "Ask agent `<agent.name>` a question. Agent description: `<agent.description>`".
+
+**Important**: For an agent to be converted into a tool, it **must** have a non-empty `description` string property set in its configuration when it was instantiated (e.g., `new Agent({ name: 'myAgent', description: 'This agent does X.', ... })`). If an agent is passed to `MCPServer` with a missing or empty `description`, an error will be thrown when the `MCPServer` is instantiated, and server setup will fail.
+
+This allows you to quickly expose the generative capabilities of your agents through the MCP, enabling clients to "ask" your agents questions directly.
+
+### Accessing MCP Context in Tools
+
+Tools exposed through `MCPServer` can access MCP request context (authentication, session IDs, etc.) via two different properties depending on how the tool is invoked:
+
+| Call Pattern | Access Method |
+|-------------|---------------|
+| Direct tool call | `context?.mcp?.extra` |
+| Agent tool call | `context?.requestContext?.get("mcp.extra")` |
+
+**Universal pattern** (works in both contexts):
+```typescript
+const mcpExtra = context?.mcp?.extra ?? context?.requestContext?.get("mcp.extra");
+const authInfo = mcpExtra?.authInfo;
+```
+
+#### Example: Tool that works in both contexts
+
+```typescript
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+const fetchUserData = createTool({
+  id: "fetchUserData",
+  description: "Fetches user data using authentication from MCP context",
+  inputSchema: z.object({
+    userId: z.string().describe("The ID of the user to fetch"),
+  }),
+  execute: async (inputData, context) => {
+    // Access MCP authentication context
+    // When called directly via MCP: context.mcp.extra
+    // When called via agent: context.requestContext.get('mcp.extra')
+    const mcpExtra = context?.mcp?.extra || context?.requestContext?.get("mcp.extra");
+    const authInfo = mcpExtra?.authInfo;
+
+    if (!authInfo?.token) {
+      throw new Error("Authentication required");
+    }
+
+    const response = await fetch(`https://api.example.com/users/${inputData.userId}`, {
+      headers: {
+        Authorization: `Bearer ${authInfo.token}`,
+      },
+    });
+
+    return response.json();
+  },
+});
+```
+
+## Methods
+
+These are the functions you can call on an `MCPServer` instance to control its behavior and get information.
+
+### startStdio()
+
+Use this method to start the server so it communicates using standard input and output (stdio). This is typical when running the server as a command-line program.
+
+```typescript
+async startStdio(): Promise<void>
+```
+
+Here's how you would start the server using stdio:
+
+```typescript
+const server = new MCPServer({
+  id: "my-server",
+  name: "My Server",
+  version: "1.0.0",
+  tools: { /* ... */ },
+});
+await server.startStdio();
+```
+
+### startSSE()
+
+This method helps you integrate the MCP server with an existing web server to use Server-Sent Events (SSE) for communication. You'll call this from your web server's code when it receives a request for the SSE or message paths.
+
+```typescript
+async startSSE({
+  url,
+  ssePath,
+  messagePath,
+  req,
+  res,
+}: {
+  url: URL;
+  ssePath: string;
+  messagePath: string;
+  req: any;
+  res: any;
+}): Promise<void>
+```
+
+Here's an example of how you might use `startSSE` within an HTTP server request handler. In this example an MCP client could connect to your MCP server at `http://localhost:1234/sse`:
+
+```typescript
+import http from "http";
+
+const httpServer = http.createServer(async (req, res) => {
+  await server.startSSE({
+    url: new URL(req.url || "", `http://localhost:1234`),
+    ssePath: "/sse",
+    messagePath: "/message",
+    req,
+    res,
+  });
+});
+
+httpServer.listen(PORT, () => {
+  console.log(`HTTP server listening on port ${PORT}`);
+});
+```
+
+Here are the details for the values needed by the `startSSE` method:
+
+### startHonoSSE()
+
+This method helps you integrate the MCP server with an existing web server to use Server-Sent Events (SSE) for communication. You'll call this from your web server's code when it receives a request for the SSE or message paths.
+
+```typescript
+async startHonoSSE({
+  url,
+  ssePath,
+  messagePath,
+  req,
+  res,
+}: {
+  url: URL;
+  ssePath: string;
+  messagePath: string;
+  req: any;
+  res: any;
+}): Promise<void>
+```
+
+Here's an example of how you might use `startHonoSSE` within an HTTP server request handler. In this example an MCP client could connect to your MCP server at `http://localhost:1234/hono-sse`:
+
+```typescript
+import http from "http";
+
+const httpServer = http.createServer(async (req, res) => {
+  await server.startHonoSSE({
+    url: new URL(req.url || "", `http://localhost:1234`),
+    ssePath: "/hono-sse",
+    messagePath: "/message",
+    req,
+    res,
+  });
+});
+
+httpServer.listen(PORT, () => {
+  console.log(`HTTP server listening on port ${PORT}`);
+});
+```
+
+Here are the details for the values needed by the `startHonoSSE` method:
+
+### startHTTP()
+
+This method helps you integrate the MCP server with an existing web server to use streamable HTTP for communication. You'll call this from your web server's code when it receives HTTP requests.
+
+```typescript
+async startHTTP({
+  url,
+  httpPath,
+  req,
+  res,
+  options = { sessionIdGenerator: () => randomUUID() },
+}: {
+  url: URL;
+  httpPath: string;
+  req: http.IncomingMessage;
+  res: http.ServerResponse<http.IncomingMessage>;
+  options?: StreamableHTTPServerTransportOptions;
+}): Promise<void>
+```
+
+Here's an example of how you might use `startHTTP` within an HTTP server request handler. In this example an MCP client could connect to your MCP server at `http://localhost:1234/http`:
+
+```typescript
+import http from "http";
+
+const httpServer = http.createServer(async (req, res) => {
+  await server.startHTTP({
+    url: new URL(req.url || "", "http://localhost:1234"),
+    httpPath: `/mcp`,
+    req,
+    res,
+    options: {
+      sessionIdGenerator: () => randomUUID(),
+    },
+  });
+});
+
+httpServer.listen(PORT, () => {
+  console.log(`HTTP server listening on port ${PORT}`);
+});
+```
+
+For **serverless environments** (Supabase Edge Functions, Cloudflare Workers, Vercel Edge, etc.), use `serverless: true` to enable stateless operation:
+
+```typescript
+// Supabase Edge Function example
+import { serve } from "https://deno.land/std@0.168.0/http/server.ts";
+import { MCPServer } from "@mastra/mcp";
+// Note: You will need to convert req/res format from Deno to Node
+import { toReqRes, toFetchResponse } from "fetch-to-node";
+
+const server = new MCPServer({
+  id: "my-serverless-mcp",
+  name: "My Serverless MCP",
+  version: "1.0.0",
+  tools: { /* your tools */ },
+});
+
+serve(async (req) => {
+  const url = new URL(req.url);
+
+  if (url.pathname === "/mcp") {
+    // Convert Deno Request to Node.js-compatible format
+    const { req: nodeReq, res: nodeRes } = toReqRes(req);
+
+    await server.startHTTP({
+      url,
+      httpPath: "/mcp",
+      req: nodeReq,
+      res: nodeRes,
+      options: {
+        serverless: true, // ← Enable stateless mode for serverless
+      },
+    });
+
+    return toFetchResponse(nodeRes);
+  }
+
+  return new Response("Not found", { status: 404 });
+});
+```
+
+> **Note:**
+
+**When to use `serverless: true`**
+
+Use `serverless: true` when deploying to environments where each request runs in a fresh, stateless execution context:
+- Supabase Edge Functions
+- Cloudflare Workers
+- Vercel Edge Functions
+- Netlify Edge Functions
+- AWS Lambda
+- Deno Deploy
+
+Use the default session-based mode (without `serverless: true`) for:
+- Long-lived Node.js servers
+- Docker containers
+- Traditional hosting (VPS, dedicated servers)
+
+The serverless mode disables session management and creates fresh server instances per request, which is necessary for stateless environments where memory doesn't persist between invocations.
+
+**Note:** The following MCP features require session state or persistent connections and will **not work** in serverless mode:
+- **Elicitation** - Interactive user input requests during tool execution require session management to route responses back to the correct client
+- **Resource subscriptions** - `resources/subscribe` and `resources/unsubscribe` need persistent connections to maintain subscription state
+- **Resource update notifications** - `resources.notifyUpdated()` requires active subscriptions and persistent connections to notify clients
+- **Prompt list change notifications** - `prompts.notifyListChanged()` requires persistent connections to push updates to clients
+
+These features work normally in long-lived server environments (Node.js servers, Docker containers, etc.).
+
+Here are the details for the values needed by the `startHTTP` method:
+
+The `StreamableHTTPServerTransportOptions` object allows you to customize the behavior of the HTTP transport. Here are the available options:
+
+### close()
+
+This method closes the server and releases all resources.
+
+```typescript
+async close(): Promise<void>
+```
+
+### getServerInfo()
+
+This method gives you a look at the server's basic information.
+
+```typescript
+getServerInfo(): ServerInfo
+```
+
+### getServerDetail()
+
+This method gives you a detailed look at the server's information.
+
+```typescript
+getServerDetail(): ServerDetail
+```
+
+### getToolListInfo()
+
+This method gives you a look at the tools that were set up when you created the server. It's a read-only list, useful for debugging purposes.
+
+```typescript
+getToolListInfo(): ToolListInfo
+```
+
+### getToolInfo()
+
+This method gives you detailed information about a specific tool.
+
+```typescript
+getToolInfo(toolName: string): ToolInfo
+```
+
+### executeTool()
+
+This method executes a specific tool and returns the result.
+
+```typescript
+executeTool(toolName: string, input: any): Promise<any>
+```
+
+### getStdioTransport()
+
+If you started the server with `startStdio()`, you can use this to get the object that manages the stdio communication. This is mostly for checking things internally or for testing.
+
+```typescript
+getStdioTransport(): StdioServerTransport | undefined
+```
+
+### getSseTransport()
+
+If you started the server with `startSSE()`, you can use this to get the object that manages the SSE communication. Like `getStdioTransport`, this is mainly for internal checks or testing.
+
+```typescript
+getSseTransport(): SSEServerTransport | undefined
+```
+
+### getSseHonoTransport()
+
+If you started the server with `startHonoSSE()`, you can use this to get the object that manages the SSE communication. Like `getSseTransport`, this is mainly for internal checks or testing.
+
+```typescript
+getSseHonoTransport(): SSETransport | undefined
+```
+
+### getStreamableHTTPTransport()
+
+If you started the server with `startHTTP()`, you can use this to get the object that manages the HTTP communication. Like `getSseTransport`, this is mainly for internal checks or testing.
+
+```typescript
+getStreamableHTTPTransport(): StreamableHTTPServerTransport | undefined
+```
+
+### tools()
+
+Executes a specific tool provided by this MCP server.
+
+```typescript
+async executeTool(
+  toolId: string,
+  args: any,
+  executionContext?: { messages?: any[]; toolCallId?: string },
+): Promise<any>
+```
+
+## Resource Handling
+
+### What are MCP Resources?
+
+Resources are a core primitive in the Model Context Protocol (MCP) that allow servers to expose data and content that can be read by clients and used as context for LLM interactions. They represent any kind of data that an MCP server wants to make available, such as:
+
+- File contents
+- Database records
+- API responses
+- Live system data
+- Screenshots and images
+- Log files
+
+Resources are identified by unique URIs (e.g., `file:///home/user/documents/report.pdf`, `postgres://database/customers/schema`) and can contain either text (UTF-8 encoded) or binary data (base64 encoded).
+
+Clients can discover resources through:
+
+1.  **Direct resources**: Servers expose a list of concrete resources via a `resources/list` endpoint.
+2.  **Resource templates**: For dynamic resources, servers can expose URI templates (RFC 6570) that clients use to construct resource URIs.
+
+To read a resource, clients make a `resources/read` request with the URI. Servers can also notify clients about changes to the resource list (`notifications/resources/list_changed`) or updates to specific resource content (`notifications/resources/updated`) if a client has subscribed to that resource.
+
+For more detailed information, refer to the [official MCP documentation on Resources](https://modelcontextprotocol.io/docs/concepts/resources).
+
+### `MCPServerResources` Type
+
+The `resources` option takes an object of type `MCPServerResources`. This type defines the callbacks your server will use to handle resource requests:
+
+```typescript
+export type MCPServerResources = {
+  // Callback to list available resources
+  listResources: () => Promise<Resource[]>;
+
+  // Callback to get the content of a specific resource
+  getResourceContent: ({
+    uri,
+  }: {
+    uri: string;
+  }) => Promise<MCPServerResourceContent | MCPServerResourceContent[]>;
+
+  // Optional callback to list available resource templates
+  resourceTemplates?: () => Promise<ResourceTemplate[]>;
+};
+
+export type MCPServerResourceContent = { text?: string } | { blob?: string };
+```
+
+Example:
+
+```typescript
+import { MCPServer } from "@mastra/mcp";
+import type {
+  MCPServerResourceContent,
+  Resource,
+  ResourceTemplate,
+} from "@mastra/mcp";
+
+// Resources/resource templates will generally be dynamically fetched.
+const myResources: Resource[] = [
+  { uri: "file://data/123.txt", name: "Data File", mimeType: "text/plain" },
+];
+
+const myResourceContents: Record<string, MCPServerResourceContent> = {
+  "file://data.txt/123": { text: "This is the content of the data file." },
+};
+
+const myResourceTemplates: ResourceTemplate[] = [
+  {
+    uriTemplate: "file://data/{id}",
+    name: "Data File",
+    description: "A file containing data.",
+    mimeType: "text/plain",
+  },
+];
+
+const myResourceHandlers: MCPServerResources = {
+  listResources: async () => myResources,
+  getResourceContent: async ({ uri }) => {
+    if (myResourceContents[uri]) {
+      return myResourceContents[uri];
+    }
+    throw new Error(`Resource content not found for ${uri}`);
+  },
+  resourceTemplates: async () => myResourceTemplates,
+};
+
+const serverWithResources = new MCPServer({
+  id: "resourceful-server",
+  name: "Resourceful Server",
+  version: "1.0.0",
+  tools: {
+    /* ... your tools ... */
+  },
+  resources: myResourceHandlers,
+});
+```
+
+### Notifying Clients of Resource Changes
+
+If the available resources or their content change, your server can notify connected clients that are subscribed to the specific resource.
+
+#### `server.resources.notifyUpdated({ uri: string })`
+
+Call this method when the content of a specific resource (identified by its `uri`) has been updated. If any clients are subscribed to this URI, they will receive a `notifications/resources/updated` message.
+
+```typescript
+async server.resources.notifyUpdated({ uri: string }): Promise<void>
+```
+
+Example:
+
+```typescript
+// After updating the content of 'file://data.txt'
+await serverWithResources.resources.notifyUpdated({ uri: "file://data.txt" });
+```
+
+#### `server.resources.notifyListChanged()`
+
+Call this method when the overall list of available resources has changed (e.g., a resource was added or removed). This will send a `notifications/resources/list_changed` message to clients, prompting them to re-fetch the list of resources.
+
+```typescript
+async server.resources.notifyListChanged(): Promise<void>
+```
+
+Example:
+
+```typescript
+// After adding a new resource to the list managed by 'myResourceHandlers.listResources'
+await serverWithResources.resources.notifyListChanged();
+```
+
+## Prompt Handling
+
+### What are MCP Prompts?
+
+Prompts are reusable templates or workflows that MCP servers expose to clients. They can accept arguments, include resource context, support versioning, and be used to standardize LLM interactions.
+
+Prompts are identified by a unique name (and optional version) and can be dynamic or static.
+
+### `MCPServerPrompts` Type
+
+The `prompts` option takes an object of type `MCPServerPrompts`. This type defines the callbacks your server will use to handle prompt requests:
+
+```typescript
+export type MCPServerPrompts = {
+  // Callback to list available prompts
+  listPrompts: () => Promise<Prompt[]>;
+
+  // Callback to get the messages/content for a specific prompt
+  getPromptMessages?: ({
+    name,
+    version,
+    args,
+  }: {
+    name: string;
+    version?: string;
+    args?: any;
+  }) => Promise<{ prompt: Prompt; messages: PromptMessage[] }>;
+};
+```
+
+Example:
+
+```typescript
+import { MCPServer } from "@mastra/mcp";
+import type { Prompt, PromptMessage, MCPServerPrompts } from "@mastra/mcp";
+
+const prompts: Prompt[] = [
+  {
+    name: "analyze-code",
+    description: "Analyze code for improvements",
+    version: "v1",
+  },
+  {
+    name: "analyze-code",
+    description: "Analyze code for improvements (new logic)",
+    version: "v2",
+  },
+];
+
+const myPromptHandlers: MCPServerPrompts = {
+  listPrompts: async () => prompts,
+  getPromptMessages: async ({ name, version, args }) => {
+    if (name === "analyze-code") {
+      if (version === "v2") {
+        const prompt = prompts.find(
+          (p) => p.name === name && p.version === "v2",
+        );
+        if (!prompt) throw new Error("Prompt version not found");
+        return {
+          prompt,
+          messages: [
+            {
+              role: "user",
+              content: {
+                type: "text",
+                text: `Analyze this code with the new logic: ${args.code}`,
+              },
+            },
+          ],
+        };
+      }
+      // Default or v1
+      const prompt = prompts.find((p) => p.name === name && p.version === "v1");
+      if (!prompt) throw new Error("Prompt version not found");
+      return {
+        prompt,
+        messages: [
+          {
+            role: "user",
+            content: { type: "text", text: `Analyze this code: ${args.code}` },
+          },
+        ],
+      };
+    }
+    throw new Error("Prompt not found");
+  },
+};
+
+const serverWithPrompts = new MCPServer({
+  id: "promptful-server",
+  name: "Promptful Server",
+  version: "1.0.0",
+  tools: {
+    /* ... */
+  },
+  prompts: myPromptHandlers,
+});
+```
+
+### Notifying Clients of Prompt Changes
+
+If the available prompts change, your server can notify connected clients:
+
+#### `server.prompts.notifyListChanged()`
+
+Call this method when the overall list of available prompts has changed (e.g., a prompt was added or removed). This will send a `notifications/prompts/list_changed` message to clients, prompting them to re-fetch the list of prompts.
+
+```typescript
+await serverWithPrompts.prompts.notifyListChanged();
+```
+
+### Best Practices for Prompt Handling
+
+- Use clear, descriptive prompt names and descriptions.
+- Validate all required arguments in `getPromptMessages`.
+- Include a `version` field if you expect to make breaking changes.
+- Use the `version` parameter to select the correct prompt logic.
+- Notify clients when prompt lists change.
+- Handle errors with informative messages.
+- Document argument expectations and available versions.
+
+---
+
+## Examples
+
+For practical examples of setting up and deploying an MCPServer, see the [Publishing an MCP Server guide](https://mastra.ai/docs/v1/mcp/publishing-mcp-server).
+
+The example at the beginning of this page also demonstrates how to instantiate `MCPServer` with both tools and agents.
+
+## Elicitation
+
+### What is Elicitation?
+
+Elicitation is a feature in the Model Context Protocol (MCP) that allows servers to request structured information from users. This enables interactive workflows where servers can collect additional data dynamically.
+
+The `MCPServer` class automatically includes elicitation capabilities. Tools receive a `context.mcp` object in their `execute` function that includes an `elicitation.sendRequest()` method for requesting user input.
+
+### Tool Execution Signature
+
+When tools are executed within an MCP server context, they receive MCP-specific capabilities via the `context.mcp` object:
+
+```typescript
+execute: async (inputData, context) => {
+  // input contains the tool's inputData parameters
+  // context.mcp contains server capabilities like elicitation and authentication info
+
+  // Access authentication information (when available)
+  if (context.mcp?.extra?.authInfo) {
+    console.log("Authenticated request from:", context.mcp.extra.authInfo.clientId);
+  }
+
+  // Use elicitation capabilities
+  const result = await context.mcp.elicitation.sendRequest({
+    message: "Please provide information",
+    requestedSchema: {
+      /* schema */
+    },
+  });
+
+  return result;
+};
+```
+
+### How Elicitation Works
+
+A common use case is during tool execution. When a tool needs user input, it can use the elicitation functionality provided through the context parameter:
+
+1. The tool calls `context.mcp.elicitation.sendRequest()` with a message and schema
+2. The request is sent to the connected MCP client
+3. The client presents the request to the user (via UI, command line, etc.)
+4. The user provides input, declines, or cancels the request
+5. The client sends the response back to the server
+6. The tool receives the response and continues execution
+
+### Using Elicitation in Tools
+
+Here's an example of a tool that uses elicitation to collect user contact information:
+
+```typescript
+import { MCPServer } from "@mastra/mcp";
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+const server = new MCPServer({
+  id: "interactive-server",
+  name: "Interactive Server",
+  version: "1.0.0",
+  tools: {
+    collectContactInfo: createTool({
+      id: "collectContactInfo",
+      description: "Collects user contact information through elicitation",
+      inputSchema: z.object({
+        reason: z
+          .string()
+          .optional()
+          .describe("Reason for collecting contact info"),
+      }),
+      execute: async (inputData, context) => {
+        const { reason } = inputData;
+
+        // Log session info if available
+        console.log("Request from session:", context.mcp?.extra?.sessionId);
+
+        try {
+          // Request user input via elicitation
+          const result = await context.mcp.elicitation.sendRequest({
+            message: reason
+              ? `Please provide your contact information. ${reason}`
+              : "Please provide your contact information",
+            requestedSchema: {
+              type: "object",
+              properties: {
+                name: {
+                  type: "string",
+                  title: "Full Name",
+                  description: "Your full name",
+                },
+                email: {
+                  type: "string",
+                  title: "Email Address",
+                  description: "Your email address",
+                  format: "email",
+                },
+                phone: {
+                  type: "string",
+                  title: "Phone Number",
+                  description: "Your phone number (optional)",
+                },
+              },
+              required: ["name", "email"],
+            },
+          });
+
+          // Handle the user's response
+          if (result.action === "accept") {
+            return `Contact information collected: ${JSON.stringify(result.content, null, 2)}`;
+          } else if (result.action === "decline") {
+            return "Contact information collection was declined by the user.";
+          } else {
+            return "Contact information collection was cancelled by the user.";
+          }
+        } catch (error) {
+          return `Error collecting contact information: ${error}`;
+        }
+      },
+    }),
+  },
+});
+```
+
+### Elicitation Request Schema
+
+The `requestedSchema` must be a flat object with primitive properties only. Supported types include:
+
+- **String**: `{ type: 'string', title: 'Display Name', description: 'Help text' }`
+- **Number**: `{ type: 'number', minimum: 0, maximum: 100 }`
+- **Boolean**: `{ type: 'boolean', default: false }`
+- **Enum**: `{ type: 'string', enum: ['option1', 'option2'] }`
+
+Example schema:
+
+```typescript
+{
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      title: 'Full Name',
+      description: 'Your complete name',
+    },
+    age: {
+      type: 'number',
+      title: 'Age',
+      minimum: 18,
+      maximum: 120,
+    },
+    newsletter: {
+      type: 'boolean',
+      title: 'Subscribe to Newsletter',
+      default: false,
+    },
+  },
+  required: ['name'],
+}
+```
+
+### Response Actions
+
+Users can respond to elicitation requests in three ways:
+
+1. **Accept** (`action: 'accept'`): User provided data and confirmed submission
+   - Contains `content` field with the submitted data
+2. **Decline** (`action: 'decline'`): User explicitly declined to provide information
+   - No content field
+3. **Cancel** (`action: 'cancel'`): User dismissed the request without deciding
+   - No content field
+
+Tools should handle all three response types appropriately.
+
+### Security Considerations
+
+- **Never request sensitive information** like passwords, SSNs, or credit card numbers
+- Validate all user input against the provided schema
+- Handle declining and cancellation gracefully
+- Provide clear reasons for data collection
+- Respect user privacy and preferences
+
+### Tool Execution API
+
+The elicitation functionality is available through the `options` parameter in tool execution:
+
+```typescript
+// Within a tool's execute function
+execute: async (inputData, context) => {
+  // Use elicitation for user input
+  const result = await context.mcp.elicitation.sendRequest({
+    message: string,           // Message to display to user
+    requestedSchema: object    // JSON schema defining expected response structure
+  }): Promise<ElicitResult>
+
+  // Access authentication info if needed
+  if (context.mcp?.extra?.authInfo) {
+    // Use context.mcp.extra.authInfo.token, etc.
+  }
+}
+```
+
+Note that elicitation is **session-aware** when using HTTP-based transports (SSE or HTTP). This means that when multiple clients are connected to the same server, elicitation requests are routed to the correct client session that initiated the tool execution.
+
+The `ElicitResult` type:
+
+```typescript
+type ElicitResult = {
+  action: "accept" | "decline" | "cancel";
+  content?: any; // Only present when action is 'accept'
+};
+```
+
+## Authentication Context
+
+Tools can access request metadata via `context.mcp.extra` when using HTTP-based transports:
+
+```typescript
+execute: async (inputData, context) => {
+  if (!context.mcp?.extra?.authInfo?.token) {
+    return "Authentication required";
+  }
+
+  // Use the auth token
+  const response = await fetch("/api/data", {
+    headers: { Authorization: `Bearer ${context.mcp.extra.authInfo.token}` },
+    signal: context.mcp.extra.signal,
+  });
+
+  return response.json();
+};
+```
+
+The `extra` object contains:
+
+- `authInfo`: Authentication info (when provided by server middleware)
+- `sessionId`: Session identifier
+- `signal`: AbortSignal for cancellation
+- `sendNotification`/`sendRequest`: MCP protocol functions
+
+> Note: To enable authentication, your HTTP server needs middleware that populates `req.auth` before calling `server.startHTTP()`. For example:
+>
+> ```typescript
+> httpServer.createServer((req, res) => {
+>   // Add auth middleware
+>   req.auth = validateAuthToken(req.headers.authorization);
+>
+>   // Then pass to MCP server
+>   await server.startHTTP({ url, httpPath, req, res });
+> });
+> ```
+
+## Related Information
+
+- For connecting to MCP servers in Mastra, see the [MCPClient documentation](./mcp-client).
+- For more about the Model Context Protocol, see the [@modelcontextprotocol/sdk documentation](https://github.com/modelcontextprotocol/typescript-sdk).
+
+---
+
+## Reference: MastraMCPClient (Deprecated)
+
+> API Reference for MastraMCPClient - A client implementation for the Model Context Protocol.
+
+The `MastraMCPClient` class provides a client implementation for interacting with Model Context Protocol (MCP) servers. It handles connection management, resource discovery, and tool execution through the MCP protocol.
+
+## Deprecation notice
+
+`MastraMCPClient` is being deprecated in favour of [`MCPClient`](./mcp-client). Rather than having two different interfaces for managing a single MCP server vs multiple MCP servers, we opted to recommend using the interface to manage multiple even when using a single MCP server.
+
+## Constructor
+
+Creates a new instance of the MastraMCPClient.
+
+```typescript
+constructor({
+    name,
+    version = '1.0.0',
+    server,
+    capabilities = {},
+    timeout = 60000,
+}: {
+    name: string;
+    server: MastraMCPServerDefinition;
+    capabilities?: ClientCapabilities;
+    version?: string;
+    timeout?: number;
+})
+```
+
+### Parameters
+
+<br />
+
+### MastraMCPServerDefinition
+
+MCP servers can be configured using this definition. The client automatically detects the transport type based on the provided parameters:
+
+- If `command` is provided, it uses the Stdio transport.
+- If `url` is provided, it first attempts to use the Streamable HTTP transport and falls back to the legacy SSE transport if the initial connection fails.
+
+<br />
+
+### LogHandler
+
+The `LogHandler` function takes a `LogMessage` object as its parameter and returns void. The `LogMessage` object has the following properties. The `LoggingLevel` type is a string enum with values: `debug`, `info`, `warn`, and `error`.
+
+<br />
+
+## Methods
+
+### connect()
+
+Establishes a connection with the MCP server.
+
+```typescript
+async connect(): Promise<void>
+```
+
+### disconnect()
+
+Closes the connection with the MCP server.
+
+```typescript
+async disconnect(): Promise<void>
+```
+
+### resources()
+
+Retrieves the list of available resources from the server.
+
+```typescript
+async resources(): Promise<ListResourcesResult>
+```
+
+### tools()
+
+Fetches and initializes available tools from the server, converting them into Mastra-compatible tool formats.
+
+```typescript
+async tools(): Promise<Record<string, Tool>>
+```
+
+Returns an object mapping tool names to their corresponding Mastra tool implementations.
+
+## Examples
+
+### Using with Mastra Agent
+
+#### Example with Stdio Server
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { MastraMCPClient } from "@mastra/mcp";
+
+// Initialize the MCP client using mcp/fetch as an example https://hub.docker.com/r/mcp/fetch
+// Visit https://github.com/docker/mcp-servers for other reference docker mcp servers
+const fetchClient = new MastraMCPClient({
+  name: "fetch",
+  server: {
+    command: "docker",
+    args: ["run", "-i", "--rm", "mcp/fetch"],
+    logger: (logMessage) => {
+      console.log(`[${logMessage.level}] ${logMessage.message}`);
+    },
+  },
+});
+
+// Create a Mastra Agent
+const agent = new Agent({
+  name: "Fetch agent",
+  instructions:
+    "You are able to fetch data from URLs on demand and discuss the response data with the user.",
+  model: "openai/gpt-5.1",
+});
+
+try {
+  // Connect to the MCP server
+  await fetchClient.connect();
+
+  // Gracefully handle process exits so the docker subprocess is cleaned up
+  process.on("exit", () => {
+    fetchClient.disconnect();
+  });
+
+  // Get available tools
+  const tools = await fetchClient.tools();
+
+  // Use the agent with the MCP tools
+  const response = await agent.generate(
+    "Tell me about mastra.ai/docs. Tell me generally what this page is and the content it includes.",
+    {
+      toolsets: {
+        fetch: tools,
+      },
+    },
+  );
+
+  console.log("\n\n" + response.text);
+} catch (error) {
+  console.error("Error:", error);
+} finally {
+  // Always disconnect when done
+  await fetchClient.disconnect();
+}
+```
+
+### Example with SSE Server
+
+```typescript
+// Initialize the MCP client using an SSE server
+const sseClient = new MastraMCPClient({
+  name: "sse-client",
+  server: {
+    url: new URL("https://your-mcp-server.com/sse"),
+    // Optional fetch request configuration - Note: requestInit alone isn't enough for SSE
+    requestInit: {
+      headers: {
+        Authorization: "Bearer your-token",
+      },
+    },
+    // Required for SSE connections with custom headers
+    eventSourceInit: {
+      fetch(input: Request | URL | string, init?: RequestInit) {
+        const headers = new Headers(init?.headers || {});
+        headers.set("Authorization", "Bearer your-token");
+        return fetch(input, {
+          ...init,
+          headers,
+        });
+      },
+    },
+    // Optional additional logging configuration
+    logger: (logMessage) => {
+      console.log(
+        `[${logMessage.level}] ${logMessage.serverName}: ${logMessage.message}`,
+      );
+    },
+    // Disable server logs
+    enableServerLogs: false,
+  },
+});
+
+// The rest of the usage is identical to the stdio example
+```
+
+### Important Note About SSE Authentication
+
+When using SSE connections with authentication or custom headers, you need to configure both `requestInit` and `eventSourceInit`. This is because SSE connections use the browser's EventSource API, which doesn't support custom headers directly.
+
+The `eventSourceInit` configuration allows you to customize the underlying fetch request used for the SSE connection, ensuring your authentication headers are properly included.
+Without `eventSourceInit`, authentication headers specified in `requestInit` won't be included in the connection request, leading to 401 Unauthorized errors.
+
+## Related Information
+
+- For managing multiple MCP servers in your application, see the [MCPClient documentation](./mcp-client)
+- For more details about the Model Context Protocol, see the [@modelcontextprotocol/sdk documentation](https://github.com/modelcontextprotocol/typescript-sdk).