@mastra/mcp-docs-server 1.0.0-beta.0 → 1.0.0-beta.10

package/.docs/raw/reference/tools/mcp-client.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: MCPClient | Tools & MCP | Mastra Docs"
+title: "Reference: MCPClient | Tools & MCP"
 description: API Reference for MCPClient - A class for managing multiple Model Context Protocol servers and their tools.
 ---
 
@@ -99,6 +99,13 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
       description:
         "For SSE fallback: Custom fetch configuration for SSE connections. Required when using custom headers with SSE.",
     },
+    {
+      name: "fetch",
+      type: "FetchLike",
+      isOptional: true,
+      description:
+        "For HTTP servers: Custom fetch implementation used for all network requests. When provided, this function will be used for all HTTP requests, allowing you to add dynamic authentication headers (e.g., refreshing bearer tokens), customize request behavior per-request, or intercept and modify requests/responses. When `fetch` is provided, `requestInit`, `eventSourceInit`, and `authProvider` become optional, as you can handle these concerns within your custom fetch function.",
+    },
     {
       name: "logger",
       type: "LogHandler",
@@ -291,23 +298,6 @@ mcpClient.resources.onListChanged("myWeatherServer", () => {
 });
 ```
 
-### `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",
-});
-```
-
 ### `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.
@@ -451,6 +441,23 @@ await mcpClient.elicitation.onRequest("interactiveServer", async (request) => {
 });
 ```
 
+### `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.
@@ -516,6 +523,63 @@ mcpClient.prompts.onListChanged("myWeatherServer", () => {
 });
 ```
 
+### `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.
@@ -632,7 +696,6 @@ For tools where you have a single connection to the MCP server for you entire ap
 ```typescript
 import { MCPClient } from "@mastra/mcp";
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 
 const mcp = new MCPClient({
   servers: {
@@ -657,7 +720,7 @@ const mcp = new MCPClient({
 const agent = new Agent({
   name: "Multi-tool Agent",
   instructions: "You have access to multiple tool servers.",
-  model: openai("gpt-4"),
+  model: "openai/gpt-5.1",
   tools: await mcp.listTools(),
 });
 
@@ -707,13 +770,12 @@ When you need a new MCP connection for each user, use `listToolsets()` and add t
 ```typescript
 import { Agent } from "@mastra/core/agent";
 import { MCPClient } from "@mastra/mcp";
-import { openai } from "@ai-sdk/openai";
 
 // 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-4"),
+  model: "openai/gpt-5.1",
 });
 
 // Later, configure MCP with user-specific settings
@@ -799,11 +861,40 @@ MCPClient handles server connections gracefully:
 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:
+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: {
@@ -828,6 +919,23 @@ const sseClient = new MCPClient({
     },
   },
 });
+
+// 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

package/.docs/raw/reference/tools/mcp-server.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: MCPServer | Tools & MCP | Mastra Docs"
+title: "Reference: MCPServer | Tools & MCP"
 description: API Reference for MCPServer - A class for exposing Mastra tools and capabilities as a Model Context Protocol server.
 ---
 
@@ -16,7 +16,6 @@ It supports both [stdio (subprocess) and SSE (HTTP) MCP transports](https://mode
 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 { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 import { createTool } from "@mastra/core/tools";
 import { MCPServer } from "@mastra/mcp";
@@ -28,7 +27,7 @@ const myAgent = new Agent({
   name: "MyExampleAgent",
   description: "A generalist to help with basic questions."
   instructions: "You are a helpful assistant.",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
 });
 
 const weatherTool = createTool({
@@ -186,6 +185,55 @@ The description for this generated tool will be: "Ask agent `<agent.name>` a que
 
 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.
@@ -420,11 +468,11 @@ const server = new MCPServer({
 
 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",
@@ -434,10 +482,10 @@ serve(async (req) => {
         serverless: true, // ← Enable stateless mode for serverless
       },
     });
-    
+
     return toFetchResponse(nodeRes);
   }
-  
+
   return new Response("Not found", { status: 404 });
 });
 ```
@@ -918,7 +966,7 @@ await serverWithPrompts.prompts.notifyListChanged();
 
 ## Examples
 
-For practical examples of setting up and deploying an MCPServer, see the [Deploying an MCPServer Example](/examples/v1/agents/deploying-mcp-server).
+For practical examples of setting up and deploying an MCPServer, see the [Publishing an MCP Server guide](/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.
 

package/.docs/raw/reference/tools/vector-query-tool.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: createVectorQueryTool() | Tools & MCP | Mastra Docs"
+title: "Reference: createVectorQueryTool() | Tools & MCP"
 description: Documentation for the Vector Query Tool in Mastra, which facilitates semantic search over vector stores with filtering and reranking capabilities.
 ---
 
@@ -13,13 +13,13 @@ The `createVectorQueryTool()` function creates a tool for semantic search over v
 ## Basic Usage
 
 ```typescript
-import { openai } from "@ai-sdk/openai";
 import { createVectorQueryTool } from "@mastra/rag";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 
 const queryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
 });
 ```
 
@@ -303,7 +303,7 @@ The tool determines the number of results to return based on the user's query, w
 const queryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   enableFilter: true,
 });
 ```
@@ -334,9 +334,9 @@ For an example of how agent-driven filtering works, see the [Agent-Driven Metada
 const queryTool = createVectorQueryTool({
   vectorStoreName: "milvus",
   indexName: "documentation",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   reranker: {
-    model: openai("gpt-4o-mini"),
+    model: "openai/gpt-5.1",
     options: {
       weights: {
         semantic: 0.5, // Semantic relevance weight
@@ -364,7 +364,7 @@ The reranker processes the initial vector search results and returns a reordered
 const queryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   description:
     "Search through document archives to find relevant information for answering questions about company policies and procedures",
 });
@@ -384,7 +384,7 @@ The `databaseConfig` parameter allows you to leverage unique features and optimi
     const pineconeQueryTool = createVectorQueryTool({
       vectorStoreName: "pinecone",
       indexName: "docs",
-      model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
       databaseConfig: {
         pinecone: {
           namespace: "production",  // Organize vectors by environment
@@ -411,7 +411,7 @@ The `databaseConfig` parameter allows you to leverage unique features and optimi
     const pgVectorQueryTool = createVectorQueryTool({
       vectorStoreName: "postgres",
       indexName: "embeddings",
-      model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
       databaseConfig: {
         pgvector: {
           minScore: 0.7,    // Only return results above 70% similarity
@@ -437,7 +437,7 @@ The `databaseConfig` parameter allows you to leverage unique features and optimi
     const chromaQueryTool = createVectorQueryTool({
       vectorStoreName: "chroma",
       indexName: "documents",
-      model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
       databaseConfig: {
         chroma: {
           where: {                    // Metadata filtering
@@ -467,7 +467,7 @@ The `databaseConfig` parameter allows you to leverage unique features and optimi
     const multiDbQueryTool = createVectorQueryTool({
       vectorStoreName: "dynamic-store", // Will be set at runtime
       indexName: "docs",
-      model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
       databaseConfig: {
         pinecone: {
           namespace: "default"
@@ -501,7 +501,7 @@ import { RequestContext } from "@mastra/core/request-context";
 const queryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   databaseConfig: {
     pinecone: {
       namespace: "development",
@@ -534,7 +534,7 @@ This approach allows you to:
 const queryTool = createVectorQueryTool({
   vectorStoreName: "pinecone",
   indexName: "docs",
-  model: openai.embedding("text-embedding-3-small"),
+      model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
 });
 ```
 
@@ -555,7 +555,7 @@ requestContext.set("filter", { category: "docs" });
 requestContext.set("databaseConfig", {
   pinecone: { namespace: "runtime-namespace" },
 });
-requestContext.set("model", openai.embedding("text-embedding-3-small"));
+requestContext.set("model", "openai/text-embedding-3-small");
 
 const response = await agent.generate(
   "Find documentation from the knowledge base.",
@@ -568,14 +568,13 @@ const response = await agent.generate(
 For more information on request context, please see:
 
 - [Agent Request Context](/docs/v1/server-db/request-context)
-- [Tool Request Context](/docs/v1/tools-mcp/overview#using-requestcontext)
+- [Request Context](/docs/v1/server-db/request-context#accessing-values-with-tools)
 
 ## Usage Without a Mastra Server
 
 The tool can be used by itself to retrieve documents matching a query:
 
 ```typescript copy showLineNumbers title="src/index.ts"
-import { openai } from "@ai-sdk/openai";
 import { RequestContext } from "@mastra/core/request-context";
 import { createVectorQueryTool } from "@mastra/rag";
 import { PgVector } from "@mastra/pg";
@@ -589,7 +588,7 @@ const vectorQueryTool = createVectorQueryTool({
   vectorStoreName: "pgVector", // optional since we're passing in a store
   vectorStore: pgVector,
   indexName: "embeddings",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
 });
 
 const requestContext = new RequestContext();

package/.docs/raw/reference/vectors/astra.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Astra Vector Store | Vectors | Mastra Docs"
+title: "Reference: Astra Vector Store | Vectors"
 description: Documentation for the AstraVector class in Mastra, which provides vector search using DataStax Astra DB.
 ---
 

package/.docs/raw/reference/vectors/chroma.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Chroma Vector Store | Vectors | Mastra Docs"
+title: "Reference: Chroma Vector Store | Vectors"
 description: Documentation for the ChromaVector class in Mastra, which provides vector search using ChromaDB.
 ---
 
@@ -335,6 +335,8 @@ interface IndexStats {
 
 ### updateVector()
 
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
 <PropertiesTable
   content={[
     {
@@ -345,7 +347,14 @@ interface IndexStats {
     {
       name: "id",
       type: "string",
-      description: "ID of the vector to update",
+      isOptional: true,
+      description: "ID of the vector to update (mutually exclusive with filter)",
+    },
+    {
+      name: "filter",
+      type: "Record<string, any>",
+      isOptional: true,
+      description: "Metadata filter to identify vector(s) to update (mutually exclusive with id)",
     },
     {
       name: "update",
@@ -374,6 +383,24 @@ The `update` object can contain:
   ]}
 />
 
+Example:
+
+```typescript
+// Update by ID
+await vectorStore.updateVector({
+  indexName: 'docs',
+  id: 'vec_123',
+  update: { metadata: { status: 'reviewed' } }
+});
+
+// Update by filter
+await vectorStore.updateVector({
+  indexName: 'docs',
+  filter: { source_id: 'manual.pdf' },
+  update: { metadata: { version: 2 } }
+});
+```
+
 ### deleteVector()
 
 <PropertiesTable
@@ -391,6 +418,59 @@ The `update` object can contain:
   ]}
 />
 
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. This method enables bulk deletion and source-based vector management. Either `ids` or `filter` must be provided, but not both.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index containing the vectors to delete",
+    },
+    {
+      name: "ids",
+      type: "string[]",
+      isOptional: true,
+      description: "Array of vector IDs to delete (mutually exclusive with filter)",
+    },
+    {
+      name: "filter",
+      type: "Record<string, any>",
+      isOptional: true,
+      description: "Metadata filter to identify vectors to delete (mutually exclusive with ids)",
+    },
+  ]}
+/>
+
+Example:
+
+```typescript
+// Delete all chunks from a document
+await vectorStore.deleteVectors({
+  indexName: 'docs',
+  filter: { source_id: 'manual.pdf' }
+});
+
+// Delete multiple vectors by ID
+await vectorStore.deleteVectors({
+  indexName: 'docs',
+  ids: ['vec_1', 'vec_2', 'vec_3']
+});
+
+// Delete old temporary documents
+await vectorStore.deleteVectors({
+  indexName: 'docs',
+  filter: {
+    $and: [
+      { bucket: 'temp' },
+      { indexed_at: { $lt: '2025-01-01' } }
+    ]
+  }
+});
+```
+
 ## Response Types
 
 Query results are returned in this format: