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

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: