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

package/.docs/raw/rag/vector-databases.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Storing Embeddings in A Vector Database | RAG | Mastra Docs"
+title: "Storing Embeddings in A Vector Database | RAG"
 description: Guide on vector storage options in Mastra, including embedded and dedicated vector databases for similarity search.
 ---
 
@@ -252,6 +252,27 @@ await store.createIndex({
   dimension: 1536,
 });
 
+await store.upsert({
+  indexName: "my-collection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+  </TabItem>
+
+  <TabItem value="elasticsearch" label="ElasticSearch">
+
+```ts title="vector-store.ts" showLineNumbers copy
+import { ElasticSearchVector } from "@mastra/elasticsearch";
+
+const store = new ElasticSearchVector({ url: process.env.ELASTICSEARCH_URL });
+
+await store.createIndex({
+  indexName: "my-collection",
+  dimension: 1536,
+});
+
 await store.upsert({
   indexName: "my-collection",
   vectors: embeddings,
@@ -459,6 +480,20 @@ Each vector database enforces specific naming conventions for indexes and collec
     - Example: `My_Index` is not valid (contains uppercase letters)
     - Example: `_myindex` is not valid (begins with underscore)
   </TabItem>
+  <TabItem value="elasticsearch" label="ElasticSearch">
+    Index names must:
+    - Use only lowercase letters
+    - Not exceed 255 bytes (counting multi-byte characters)
+    - Not begin with underscores, hyphens, or plus signs
+    - Not contain spaces, commas
+    - Not contain special characters (e.g. `:`, `"`, `*`, `+`, `/`, `\`, `|`, `?`, `#`, `>`, `<`)
+    - Not be "." or ".."
+    - Not start with "." (deprecated except for system/hidden indices)
+    - Example: `my-index-123` is valid
+    - Example: `My_Index` is not valid (contains uppercase letters)
+    - Example: `_myindex` is not valid (begins with underscore)
+    - Example: `.myindex` is not valid (begins with dot, deprecated)
+  </TabItem>
   <TabItem value="s3vectors" label="S3 Vectors">
     Index names must:
     - Be unique within the same vector bucket
@@ -496,8 +531,6 @@ The upsert operation:
 - Creates new vectors if they don't exist
 - Automatically handles batching for large datasets
 
-For complete examples of upserting embeddings in different vector stores, see the [Upsert Embeddings](/examples/v1/rag/upsert/upsert-embeddings) guide.
-
 ## Adding Metadata
 
 Vector stores support rich metadata (any JSON-serializable fields) for filtering and organization. Since metadata is stored with no fixed schema, use consistent field naming to avoid unexpected query results.
@@ -536,6 +569,64 @@ Key metadata considerations:
 - Only include fields you plan to filter or sort by - extra fields add overhead
 - Add timestamps (e.g., 'createdAt', 'lastUpdated') to track content freshness
 
+## Deleting Vectors
+
+When building RAG applications, you often need to clean up stale vectors when documents are deleted or updated. Mastra provides the `deleteVectors` method that supports deleting vectors by metadata filters, making it easy to remove all embeddings associated with a specific document.
+
+### Delete by Metadata Filter
+
+The most common use case is deleting all vectors for a specific document when a user deletes it:
+
+```ts title="delete-vectors.ts" showLineNumbers copy
+// Delete all vectors for a specific document
+await store.deleteVectors({
+  indexName: "myCollection",
+  filter: { docId: "document-123" },
+});
+```
+
+This is particularly useful when:
+- A user deletes a document and you need to remove all its chunks
+- You're re-indexing a document and want to remove old vectors first
+- You need to clean up vectors for a specific user or tenant
+
+### Delete Multiple Documents
+
+You can also use complex filters to delete vectors matching multiple conditions:
+
+```ts title="delete-vectors-advanced.ts" showLineNumbers copy
+// Delete all vectors for multiple documents
+await store.deleteVectors({
+  indexName: "myCollection",
+  filter: {
+    docId: { $in: ["doc-1", "doc-2", "doc-3"] },
+  },
+});
+
+// Delete vectors for a specific user's documents
+await store.deleteVectors({
+  indexName: "myCollection",
+  filter: {
+    $and: [
+      { userId: "user-123" },
+      { status: "archived" },
+    ],
+  },
+});
+```
+
+### Delete by Vector IDs
+
+If you have specific vector IDs to delete, you can pass them directly:
+
+```ts title="delete-by-ids.ts" showLineNumbers copy
+// Delete specific vectors by their IDs
+await store.deleteVectors({
+  indexName: "myCollection",
+  ids: ["vec-1", "vec-2", "vec-3"],
+});
+```
+
 ## Best Practices
 
 - Create indexes before bulk insertions

package/.docs/raw/reference/agents/agent.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent Class | Agents | Mastra Docs"
+title: "Reference: Agent Class | Agents"
 description: "Documentation for the `Agent` class in Mastra, which provides the foundation for creating AI agents with various capabilities."
 ---
 
@@ -12,7 +12,6 @@ The `Agent` class is the foundation for creating AI agents in Mastra. It provide
 ### Basic string instructions
 
 ```typescript title="src/mastra/agents/string-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 
 // String instructions
@@ -20,7 +19,7 @@ export const agent = new Agent({
   id: "test-agent",
   name: "Test Agent",
   instructions: "You are a helpful assistant that provides concise answers.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
 });
 
 // System message object
@@ -31,7 +30,7 @@ export const agent2 = new Agent({
     role: "system",
     content: "You are an expert programmer",
   },
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
 });
 
 // Array of system messages
@@ -42,7 +41,7 @@ export const agent3 = new Agent({
     { role: "system", content: "You are a helpful assistant" },
     { role: "system", content: "You have expertise in TypeScript" },
   ],
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
 });
 ```
 
@@ -51,7 +50,6 @@ export const agent3 = new Agent({
 Use CoreSystemMessage format to access additional properties like `providerOptions` for provider-specific configurations:
 
 ```typescript title="src/mastra/agents/core-message-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 
 export const agent = new Agent({
@@ -67,14 +65,13 @@ export const agent = new Agent({
       },
     },
   },
-  model: openai("gpt-5"),
+  model: "openai/gpt-5.1",
 });
 ```
 
 ### Multiple CoreSystemMessages
 
 ```typescript title="src/mastra/agents/multi-message-agent.ts" showLineNumbers copy
-import { anthropic } from "@ai-sdk/anthropic";
 import { Agent } from "@mastra/core/agent";
 
 // This could be customizable based on the user
@@ -97,7 +94,7 @@ export const agent = new Agent({
       },
     },
   ],
-  model: anthropic("claude-sonnet-4-20250514"),
+  model: "anthropic/claude-sonnet-4-20250514",
 });
 ```
 
@@ -129,8 +126,8 @@ export const agent = new Agent({
       name: "instructions",
       type: "SystemMessage | ({ requestContext: RequestContext }) => SystemMessage | Promise<SystemMessage>",
       isOptional: false,
-      description: `Instructions that guide the agent's behavior. Can be a string, array of strings, system message object, 
-        array of system messages, or a function that returns any of these types dynamically. 
+      description: `Instructions that guide the agent's behavior. Can be a string, array of strings, system message object,
+        array of system messages, or a function that returns any of these types dynamically.
         SystemMessage types: string | string[] | CoreSystemMessage | CoreSystemMessage[] | SystemModelMessage | SystemModelMessage[]`,
     },
     {
@@ -215,17 +212,24 @@ export const agent = new Agent({
     },
     {
       name: "inputProcessors",
-      type: "Processor[] | ({ requestContext: RequestContext }) => Processor[] | Promise<Processor[]>",
+      type: "(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>",
       isOptional: true,
       description:
-        "Input processors that can modify or validate messages before they are processed by the agent. Must implement the `processInput` function.",
+        "Input processors that can modify or validate messages before they are processed by the agent. Can be individual Processor objects or workflows created with `createWorkflow()` using ProcessorStepSchema.",
     },
     {
       name: "outputProcessors",
-      type: "Processor[] | ({ requestContext: RequestContext }) => Processor[] | Promise<Processor[]>",
+      type: "(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>",
       isOptional: true,
       description:
-        "Output processors that can modify or validate messages from the agent, before it is sent to the client. Must implement either (or both) of the `processOutputResult` and `processOutputStream` functions.",
+        "Output processors that can modify or validate messages from the agent before they are sent to the client. Can be individual Processor objects or workflows.",
+    },
+    {
+      name: "maxProcessorRetries",
+      type: "number",
+      isOptional: true,
+      description:
+        "Maximum number of times a processor can request retrying the LLM step.",
     },
   ]}
 />
@@ -245,4 +249,3 @@ export const agent = new Agent({
 ## Related
 
 - [Agents overview](/docs/v1/agents/overview)
-- [Calling Agents](/examples/v1/agents/calling-agents)

package/.docs/raw/reference/agents/generate.mdx

@@ -1,8 +1,10 @@
 ---
-title: "Reference: Agent.generate() | Agents | Mastra Docs"
+title: "Reference: Agent.generate() | Agents"
 description: "Documentation for the `Agent.generate()` method in Mastra agents, which enables non-streaming generation of responses with enhanced capabilities."
 ---
 
+import { MODEL_SETTINGS_OBJECT } from "@site/src/components/ModelSettingsProperties";
+
 # Agent.generate()
 
 The `.generate()` method enables non-streaming response generation from an agent, with enhanced capabilities and flexible output formats. It accepts messages and optional generation options, supporting both Mastra’s native format and AI SDK v5 compatibility.
@@ -17,6 +19,14 @@ const mastraResult = await agent.generate("message for agent");
 const aiSdkResult = await agent.generate("message for agent", {
   format: "aisdk",
 });
+
+// With model settings (e.g., limiting output tokens)
+const limitedResult = await agent.generate("Write a short poem about coding", {
+  modelSettings: {
+    maxOutputTokens: 50,
+    temperature: 0.7,
+  },
+});
 ```
 
 :::info
@@ -114,12 +124,6 @@ const aiSdkResult = await agent.generate("message for agent", {
         },
       ],
     },
-    {
-      name: "tracingContext",
-      type: "TracingContext",
-      isOptional: true,
-      description: "Tracing context for span hierarchy and metadata.",
-    },
     {
       name: "returnScorerData",
       type: "boolean",
@@ -243,6 +247,17 @@ const aiSdkResult = await agent.generate("message for agent", {
             },
           ],
         },
+        {
+          parameters: [
+            {
+              name: "providerOptions",
+              type: "ProviderOptions",
+              isOptional: true,
+              description:
+                "Provider-specific options passed to the internal structuring agent. Use this to control model behavior like reasoning effort for thinking models (e.g., `{ openai: { reasoningEffort: 'low' } }`).",
+            },
+          ],
+        },
       ],
     },
     {
@@ -392,91 +407,7 @@ const aiSdkResult = await agent.generate("message for agent", {
         },
       ],
     },
-    {
-      name: "modelSettings",
-      type: "CallSettings",
-      isOptional: true,
-      description: "Model-specific settings like temperature, topP, etc.",
-      properties: [
-        {
-          parameters: [
-            {
-              name: "temperature",
-              type: "number",
-              isOptional: true,
-              description:
-                "Controls randomness in generation (0-2). Higher values make output more random.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "maxRetries",
-              type: "number",
-              isOptional: true,
-              description:
-                "Maximum number of retry attempts for failed requests.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "topP",
-              type: "number",
-              isOptional: true,
-              description:
-                "Nucleus sampling parameter (0-1). Controls diversity of generated text.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "topK",
-              type: "number",
-              isOptional: true,
-              description:
-                "Top-k sampling parameter. Limits vocabulary to k most likely tokens.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "presencePenalty",
-              type: "number",
-              isOptional: true,
-              description:
-                "Penalty for token presence (-2 to 2). Reduces repetition.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "frequencyPenalty",
-              type: "number",
-              isOptional: true,
-              description:
-                "Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "stopSequences",
-              type: "string[]",
-              isOptional: true,
-              description:
-                "Array of strings that will stop generation when encountered.",
-            },
-          ],
-        },
-      ],
-    },
+    MODEL_SETTINGS_OBJECT,
     {
       name: "threadId",
       type: "string",
@@ -650,15 +581,52 @@ const aiSdkResult = await agent.generate("message for agent", {
             },
           ],
         },
+        {
+          parameters: [
+            {
+              name: "requestContextKeys",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "traceId",
+              type: "string",
+              isOptional: true,
+              description:
+                "Trace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "parentSpanId",
+              type: "string",
+              isOptional: true,
+              description:
+                "Parent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "tags",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Tags to apply to this trace. String labels for categorizing and filtering traces.",
+            },
+          ],
+        },
       ],
     },
-    {
-      name: "maxTokens",
-      type: "number",
-      isOptional: true,
-      description:
-        "Conditions for stopping execution (e.g., step count, token limit).",
-    },
   ]}
 />
 

package/.docs/raw/reference/agents/generateLegacy.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.generateLegacy() (Legacy) | Agents | Mastra Docs"
+title: "Reference: Agent.generateLegacy() (Legacy) | Agents"
 description: "Documentation for the legacy `Agent.generateLegacy()` method in Mastra agents. This method is deprecated and will be removed in a future version."
 ---
 
@@ -590,12 +590,12 @@ await agent.generateLegacy(
         sentiment: z.enum(["positive", "negative", "neutral"]),
         confidence: z.number(),
       }),
-      model: openai("gpt-4o-mini"),
+      model: "openai/gpt-5.1",
       errorStrategy: "warn",
     },
     // Output processors for response validation
     outputProcessors: [
-      new ModerationProcessor({ model: openai("gpt-4.1-nano") }),
+      new ModerationProcessor({ model: "openai/gpt-4.1-nano" }),
       new TokenLimiterProcessor({ maxTokens: 1000 }),
     ],
   },

package/.docs/raw/reference/agents/getDefaultGenerateOptions.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.getDefaultGenerateOptionsLegacy() | Agents | Mastra Docs"
+title: "Reference: Agent.getDefaultGenerateOptionsLegacy() | Agents"
 description: "Documentation for the `Agent.getDefaultGenerateOptionsLegacy()` method in Mastra agents, which retrieves the default options used for generateLegacy calls."
 ---
 

package/.docs/raw/reference/agents/getDefaultOptions.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.getDefaultOptions() | Agents | Mastra Docs"
+title: "Reference: Agent.getDefaultOptions() | Agents"
 description: "Documentation for the `Agent.getDefaultOptions()` method in Mastra agents, which retrieves the default options used for stream and generate calls."
 ---
 

package/.docs/raw/reference/agents/getDefaultStreamOptions.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.getDefaultStreamOptionsLegacy() | Agents | Mastra Docs"
+title: "Reference: Agent.getDefaultStreamOptionsLegacy() | Agents"
 description: "Documentation for the `Agent.getDefaultStreamOptionsLegacy()` method in Mastra agents, which retrieves the default options used for streamLegacy calls."
 ---
 

package/.docs/raw/reference/agents/getDescription.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.getDescription() | Agents | Mastra Docs"
+title: "Reference: Agent.getDescription() | Agents"
 description: "Documentation for the `Agent.getDescription()` method in Mastra agents, which retrieves the agent's description."
 ---
 

package/.docs/raw/reference/agents/getInstructions.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.getInstructions() | Agents | Mastra Docs"
+title: "Reference: Agent.getInstructions() | Agents"
 description: "Documentation for the `Agent.getInstructions()` method in Mastra agents, which retrieves the instructions that guide the agent's behavior."
 ---
 

package/.docs/raw/reference/agents/getLLM.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.getLLM() | Agents | Mastra Docs"
+title: "Reference: Agent.getLLM() | Agents"
 description: "Documentation for the `Agent.getLLM()` method in Mastra agents, which retrieves the language model instance."
 ---
 
@@ -46,7 +46,7 @@ await agent.getLLM();
 ```typescript copy
 await agent.getLLM({
   requestContext: new RequestContext(),
-  model: openai("gpt-4"),
+  model: "openai/gpt-5.1",
 });
 ```
 

package/.docs/raw/reference/agents/getMemory.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.getMemory() | Agents | Mastra Docs"
+title: "Reference: Agent.getMemory() | Agents"
 description: "Documentation for the `Agent.getMemory()` method in Mastra agents, which retrieves the memory system associated with the agent."
 ---
 

package/.docs/raw/reference/agents/getModel.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.getModel() | Agents | Mastra Docs"
+title: "Reference: Agent.getModel() | Agents"
 description: "Documentation for the `Agent.getModel()` method in Mastra agents, which retrieves the language model that powers the agent."
 ---
 

package/.docs/raw/reference/agents/getTools.mdx

@@ -0,0 +1,69 @@
+---
+title: "Reference: Agent.getTools() | Agents"
+description: "Documentation for the `Agent.getTools()` method in Mastra agents, which retrieves the tools that the agent can use."
+---
+
+# Agent.getTools()
+
+The `.getTools()` method retrieves the tools configured for an agent, resolving them if they're a function. These tools extend the agent's capabilities, allowing it to perform specific actions or access external systems.
+
+## Usage example
+
+```typescript copy
+await agent.getTools();
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "options",
+      type: "{ requestContext?: RequestContext }",
+      isOptional: true,
+      defaultValue: "{}",
+      description: "Optional configuration object containing runtime context.",
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "tools",
+      type: "TTools | Promise<TTools>",
+      description:
+        "The tools configured for the agent, either as a direct object or a promise that resolves to the tools.",
+    },
+  ]}
+/>
+
+## Extended usage example
+
+```typescript copy
+await agent.getTools({
+  requestContext: new RequestContext(),
+});
+```
+
+### Options parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "requestContext",
+      type: "RequestContext",
+      isOptional: true,
+      defaultValue: "new RequestContext()",
+      description:
+        "Runtime context for dependency injection and contextual information.",
+    },
+  ]}
+/>
+
+## Related
+
+- [Using tools with agents](/docs/v1/agents/using-tools)
+- [MCP Overview](/docs/v1/mcp/overview)

package/.docs/raw/reference/agents/getVoice.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.getVoice() | Agents | Mastra Docs"
+title: "Reference: Agent.getVoice() | Agents"
 description: "Documentation for the `Agent.getVoice()` method in Mastra agents, which retrieves the voice provider for speech capabilities."
 ---
 

package/.docs/raw/reference/agents/listAgents.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.listAgents() | Agents | Mastra Docs"
+title: "Reference: Agent.listAgents() | Agents"
 description: "Documentation for the `Agent.listAgents()` method in Mastra agents, which retrieves the sub-agents that the agent can access."
 ---
 

package/.docs/raw/reference/agents/listScorers.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.listScorers() | Agents | Mastra Docs"
+title: "Reference: Agent.listScorers() | Agents"
 description: "Documentation for the `Agent.listScorers()` method in Mastra agents, which retrieves the scoring configuration."
 ---
 

package/.docs/raw/reference/agents/listTools.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.listTools() | Agents | Mastra Docs"
+title: "Reference: Agent.listTools() | Agents"
 description: "Documentation for the `Agent.listTools()` method in Mastra agents, which retrieves the tools that the agent can use."
 ---
 
@@ -66,4 +66,4 @@ await agent.listTools({
 ## Related
 
 - [Using tools with agents](/docs/v1/agents/using-tools)
-- [Creating tools](/docs/v1/tools-mcp/overview)
+- [Creating tools](/docs/v1/mcp/overview)

package/.docs/raw/reference/agents/listWorkflows.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Agent.listWorkflows() | Agents | Mastra Docs"
+title: "Reference: Agent.listWorkflows() | Agents"
 description: "Documentation for the `Agent.listWorkflows()` method in Mastra agents, which retrieves the workflows that the agent can execute."
 ---