@mastra/mcp 1.0.0 → 1.0.1

package/dist/docs/{tools/01-reference.md → references/reference-tools-mcp-server.md}

@@ -1,957 +1,4 @@
-# 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({ id: "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
-
-## OAuth Authentication
-
-For connecting to MCP servers that require OAuth authentication per the [MCP Auth Specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization), use the `MCPOAuthClientProvider`:
-
-```typescript
-import { MCPClient, MCPOAuthClientProvider } from "@mastra/mcp";
-
-// Create an OAuth provider
-const oauthProvider = new MCPOAuthClientProvider({
-  redirectUrl: "http://localhost:3000/oauth/callback",
-  clientMetadata: {
-    redirect_uris: ["http://localhost:3000/oauth/callback"],
-    client_name: "My MCP Client",
-    grant_types: ["authorization_code", "refresh_token"],
-    response_types: ["code"],
-  },
-  onRedirectToAuthorization: (url) => {
-    // Handle authorization redirect (open browser, redirect response, etc.)
-    console.log(`Please visit: ${url}`);
-  },
-});
-
-// Use the provider with MCPClient
-const client = new MCPClient({
-  servers: {
-    protectedServer: {
-      url: new URL("https://mcp.example.com/mcp"),
-      authProvider: oauthProvider,
-    },
-  },
-});
-```
-
-### Quick Token Provider
-
-For testing or when you already have a valid access token:
-
-```typescript
-import { MCPClient, createSimpleTokenProvider } from "@mastra/mcp";
-
-const provider = createSimpleTokenProvider("your-access-token", {
-  redirectUrl: "http://localhost:3000/callback",
-  clientMetadata: {
-    redirect_uris: ["http://localhost:3000/callback"],
-    client_name: "Test Client",
-  },
-});
-
-const client = new MCPClient({
-  servers: {
-    testServer: {
-      url: new URL("https://mcp.example.com/mcp"),
-      authProvider: provider,
-    },
-  },
-});
-```
-
-### Custom Token Storage
-
-For persistent token storage across sessions, implement the `OAuthStorage` interface:
-
-```typescript
-import { MCPOAuthClientProvider, OAuthStorage } from "@mastra/mcp";
-
-class DatabaseOAuthStorage implements OAuthStorage {
-  constructor(private db: Database, private userId: string) {}
-
-  async set(key: string, value: string): Promise<void> {
-    await this.db.query(
-      "INSERT INTO oauth_tokens (user_id, key, value) VALUES (?, ?, ?) ON CONFLICT DO UPDATE SET value = ?",
-      [this.userId, key, value, value]
-    );
-  }
-
-  async get(key: string): Promise<string | undefined> {
-    const result = await this.db.query(
-      "SELECT value FROM oauth_tokens WHERE user_id = ? AND key = ?",
-      [this.userId, key]
-    );
-    return result?.[0]?.value;
-  }
-
-  async delete(key: string): Promise<void> {
-    await this.db.query(
-      "DELETE FROM oauth_tokens WHERE user_id = ? AND key = ?",
-      [this.userId, key]
-    );
-  }
-}
-
-const provider = new MCPOAuthClientProvider({
-  redirectUrl: "http://localhost:3000/callback",
-  clientMetadata: { /* ... */ },
-  storage: new DatabaseOAuthStorage(db, "user-123"),
-});
-```
-
-## 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({
-  id: "multi-tool-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({
-  id: "multi-tool-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.
+# MCPServer
 
 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.
 
@@ -1003,6 +50,38 @@ const server = new MCPServer({
 
 The constructor accepts an `MCPServerConfig` object with the following properties:
 
+**id:** (`string`): Unique identifier for the server. This ID is preserved when the server is registered with Mastra and can be used to retrieve the server via getMCPServerById().
+
+**name:** (`string`): A descriptive name for your server (e.g., 'My Weather and Agent Server').
+
+**version:** (`string`): The semantic version of your server (e.g., '1.0.0').
+
+**tools:** (`ToolsInput`): An object where keys are tool names and values are Mastra tool definitions (created with \`createTool\` or Vercel AI SDK). These tools will be directly exposed.
+
+**agents?:** (`Record<string, Agent>`): An object where keys are agent identifiers and values are Mastra Agent instances. Each agent will be automatically converted into a tool named \`ask\_\<agentIdentifier>\`. The agent \*\*must\*\* have a non-empty \`description\` string property defined in its constructor configuration. This description will be used in the tool's description. If an agent's description is missing or empty, an error will be thrown during MCPServer initialization.
+
+**workflows?:** (`Record<string, Workflow>`): An object where keys are workflow identifiers and values are Mastra Workflow instances. Each workflow is converted into a tool named \`run\_\<workflowKey>\`. The workflow's \`inputSchema\` becomes the tool's input schema. The workflow \*\*must\*\* have a non-empty \`description\` string property, which is used for the tool's description. If a workflow's description is missing or empty, an error will be thrown. The tool executes the workflow by calling \`workflow\.createRun()\` followed by \`run.start({ inputData: \<tool\_input> })\`. If a tool name derived from an agent or workflow (e.g., \`ask\_myAgent\` or \`run\_myWorkflow\`) collides with an explicitly defined tool name or another derived name, the explicitly defined tool takes precedence, and a warning is logged. Agents/workflows leading to subsequent collisions are skipped.
+
+**description?:** (`string`): Optional description of what the MCP server does.
+
+**instructions?:** (`string`): Optional instructions describing how to use the server and its features.
+
+**repository?:** (`Repository`): Optional repository information for the server's source code.
+
+**releaseDate?:** (`string`): Optional release date of this server version (ISO 8601 string). Defaults to the time of instantiation if not provided.
+
+**isLatest?:** (`boolean`): Optional flag indicating if this is the latest version. Defaults to true if not provided.
+
+**packageCanonical?:** (`'npm' | 'docker' | 'pypi' | 'crates' | string`): Optional canonical packaging format if the server is distributed as a package (e.g., 'npm', 'docker').
+
+**packages?:** (`PackageInfo[]`): Optional list of installable packages for this server.
+
+**remotes?:** (`RemoteInfo[]`): Optional list of remote access points for this server.
+
+**resources?:** (`MCPServerResources`): An object defining how the server should handle MCP resources. See Resource Handling section for details.
+
+**prompts?:** (`MCPServerPrompts`): An object defining how the server should handle MCP prompts. See Prompt Handling section for details.
+
 ## 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:
@@ -1010,6 +89,7 @@ A powerful feature of `MCPServer` is its ability to automatically expose your Ma
 - **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`.
@@ -1033,12 +113,13 @@ This allows you to quickly expose the generative capabilities of your agents thr
 
 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")` |
+| 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;
@@ -1144,6 +225,16 @@ httpServer.listen(PORT, () => {
 
 Here are the details for the values needed by the `startSSE` method:
 
+**url:** (`URL`): The web address the user is requesting.
+
+**ssePath:** (`string`): The specific part of the URL where clients will connect for SSE (e.g., '/sse').
+
+**messagePath:** (`string`): The specific part of the URL where clients will send messages (e.g., '/message').
+
+**req:** (`any`): The incoming request object from your web server.
+
+**res:** (`any`): The response object from your web server, used to send data back.
+
 ### 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.
@@ -1186,6 +277,16 @@ httpServer.listen(PORT, () => {
 
 Here are the details for the values needed by the `startHonoSSE` method:
 
+**url:** (`URL`): The web address the user is requesting.
+
+**ssePath:** (`string`): The specific part of the URL where clients will connect for SSE (e.g., '/hono-sse').
+
+**messagePath:** (`string`): The specific part of the URL where clients will send messages (e.g., '/message').
+
+**req:** (`any`): The incoming request object from your web server.
+
+**res:** (`any`): The response object from your web server, used to send data back.
+
 ### 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.
@@ -1268,37 +369,58 @@ serve(async (req) => {
 });
 ```
 
-> **Note:**
+> **Info:** **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.).
 
-**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
+Here are the details for the values needed by the `startHTTP` method:
 
-Use the default session-based mode (without `serverless: true`) for:
-- Long-lived Node.js servers
-- Docker containers
-- Traditional hosting (VPS, dedicated servers)
+**url:** (`URL`): The web address the user is requesting.
 
-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.
+**httpPath:** (`string`): The specific part of the URL where the MCP server will handle HTTP requests (e.g., '/mcp').
 
-**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
+**req:** (`http.IncomingMessage`): The incoming request object from your web server.
 
-These features work normally in long-lived server environments (Node.js servers, Docker containers, etc.).
+**res:** (`http.ServerResponse`): The response object from your web server, used to send data back.
 
-Here are the details for the values needed by the `startHTTP` method:
+**options:** (`StreamableHTTPServerTransportOptions`): Optional configuration for the HTTP transport. See the options table below for more details.
 
 The `StreamableHTTPServerTransportOptions` object allows you to customize the behavior of the HTTP transport. Here are the available options:
 
+**serverless:** (`boolean`): If \`true\`, runs in stateless mode without session management. Each request is handled independently with a fresh server instance. Essential for serverless environments (Cloudflare Workers, Supabase Edge Functions, Vercel Edge, etc.) where sessions cannot persist between invocations. Defaults to \`false\`.
+
+**sessionIdGenerator:** (`(() => string) | undefined`): A function that generates a unique session ID. This should be a cryptographically secure, globally unique string. Return \`undefined\` to disable session management.
+
+**onsessioninitialized:** (`(sessionId: string) => void`): A callback that is invoked when a new session is initialized. This is useful for tracking active MCP sessions.
+
+**enableJsonResponse:** (`boolean`): If \`true\`, the server will return plain JSON responses instead of using Server-Sent Events (SSE) for streaming. Defaults to \`false\`.
+
+**eventStore:** (`EventStore`): An event store for message resumability. Providing this enables clients to reconnect and resume message streams.
+
 ### close()
 
 This method closes the server and releases all resources.
@@ -1391,6 +513,12 @@ async executeTool(
 ): Promise<any>
 ```
 
+**toolId:** (`string`): The ID/name of the tool to execute.
+
+**args:** (`any`): The arguments to pass to the tool's execute function.
+
+**executionContext?:** (`object`): Optional context for the tool execution, like messages or a toolCallId.
+
 ## Resource Handling
 
 ### What are MCP Resources?
@@ -1408,8 +536,8 @@ Resources are identified by unique URIs (e.g., `file:///home/user/documents/repo
 
 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.
+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.
 
@@ -1643,11 +771,11 @@ await serverWithPrompts.prompts.notifyListChanged();
 - 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).
+For practical examples of setting up and deploying an MCPServer, see the [Publishing an MCP Server guide](https://mastra.ai/docs/mcp/publishing-mcp-server).
 
 The example at the beginning of this page also demonstrates how to instantiate `MCPServer` with both tools and agents.
 
@@ -1949,6 +1077,18 @@ const customMiddleware = createOAuthMiddleware({
 
 ### OAuth Middleware Options
 
+**oauth.resource:** (`string`): The canonical URL of your MCP server. This is returned in Protected Resource Metadata.
+
+**oauth.authorizationServers:** (`string[]`): URLs of authorization servers that can issue tokens for this resource.
+
+**oauth.scopesSupported?:** (`string[]`): Scopes supported by this MCP server. (Default: `['mcp:read', 'mcp:write']`)
+
+**oauth.resourceName?:** (`string`): Human-readable name for this resource server.
+
+**oauth.validateToken?:** (`(token: string, resource: string) => Promise<TokenValidationResult>`): Function to validate access tokens. If not provided, tokens are accepted without validation (NOT recommended for production).
+
+**mcpPath?:** (`string`): Path where the MCP endpoint is served. Only requests to this path require authentication. (Default: `'/mcp'`)
+
 ## Authentication Context
 
 Tools can access request metadata via `context.mcp.extra` when using HTTP-based transports. This allows you to pass authentication info, user context, or any custom data from your HTTP middleware to your MCP tools.
@@ -1957,7 +1097,7 @@ Tools can access request metadata via `context.mcp.extra` when using HTTP-based
 
 Whatever you set on `req.auth` in your HTTP middleware becomes available as `context.mcp.extra.authInfo` in your tools:
 
-```
+```text
 req.auth = { ... }  →  context?.mcp?.extra?.authInfo.extra = { ... }
 ```
 
@@ -2017,17 +1157,46 @@ execute: async (inputData, context) => {
 };
 ```
 
+### Passing `RequestContext` through to agent
+
+```typescript
+execute: async (inputData, context) => {
+  // Access the auth data you set in middleware
+  const authInfo = context?.mcp?.extra?.authInfo;
+
+  const requestContext = context.requestContext || new RequestContext().set('someKey', authInfo)
+
+  if (!authInfo?.extra?.userId) {
+    return { error: "Authentication required" };
+  }
+
+  // Use the auth data
+  console.log("User ID:", authInfo.extra.userId);
+  console.log("Email:", authInfo.extra.email);
+
+  const agent = context?.mastra?.getAgentById('some-agent-id');
+
+  if (!agent) {
+    return { error: "Agent 'some-agent-id' not found" }
+  }
+
+  const response = await agent.generate(prompt, { requestContext })
+
+  return response.text
+};
+```
+
 ### The `extra` Object
 
 The full `context.mcp.extra` object contains:
 
-| Property | Description |
-|----------|-------------|
-| `authInfo` | Whatever you set on `req.auth` in your middleware |
-| `sessionId` | Session identifier for the MCP connection |
-| `signal` | AbortSignal for request cancellation |
-| `sendNotification` | MCP protocol function for sending notifications |
-| `sendRequest` | MCP protocol function for sending requests |
+| Property           | Description                                       |
+| ------------------ | ------------------------------------------------- |
+| `authInfo`         | Whatever you set on `req.auth` in your middleware |
+| `sessionId`        | Session identifier for the MCP connection         |
+| `signal`           | AbortSignal for request cancellation              |
+| `sendNotification` | MCP protocol function for sending notifications   |
+| `sendRequest`      | MCP protocol function for sending requests        |
 
 ### Complete Example
 
@@ -2102,205 +1271,5 @@ app.listen(3000);
 
 ## 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).
+- For connecting to MCP servers in Mastra, see the [MCPClient documentation](https://mastra.ai/reference/tools/mcp-client).
+- For more about the Model Context Protocol, see the [@modelcontextprotocol/sdk documentation](https://github.com/modelcontextprotocol/typescript-sdk).