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

package/.docs/raw/reference/storage/upstash.mdx

@@ -15,13 +15,13 @@ The Upstash storage implementation provides a serverless-friendly storage soluti
 
 ## Installation
 
-```bash copy
+```bash
 npm install @mastra/upstash@beta
 ```
 
 ## Usage
 
-```typescript copy showLineNumbers
+```typescript
 import { UpstashStore } from "@mastra/upstash";
 
 const storage = new UpstashStore({
@@ -91,3 +91,75 @@ For optimal performance:
 - Use appropriate key prefixes to organize data
 - Monitor Redis memory usage
 - Consider data expiration policies if needed
+
+## Usage Example
+
+### Adding memory to an agent
+
+To add Upstash memory to an agent use the `Memory` class and create a new `storage` key using `UpstashStore` and a new `vector` key using `UpstashVector`. The configuration can point to either a remote service or a local setup.
+
+```typescript title="src/mastra/agents/example-upstash-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { UpstashStore } from "@mastra/upstash";
+
+export const upstashAgent = new Agent({
+  id: "upstash-agent",
+  name: "Upstash Agent",
+  instructions:
+    "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: "openai/gpt-5.1",
+  memory: new Memory({
+    storage: new UpstashStore({
+      id: 'upstash-agent-storage',
+      url: process.env.UPSTASH_REDIS_REST_URL!,
+      token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+    }),
+    options: {
+      generateTitle: true, // Explicitly enable automatic title generation
+    },
+  }),
+});
+```
+
+### Using the agent
+
+Use `memoryOptions` to scope recall for this request. Set `lastMessages: 5` to limit recency-based recall, and use `semanticRecall` to fetch the `topK: 3` most relevant messages, including `messageRange: 2` neighboring messages for context around each match.
+
+```typescript title="src/test-upstash-agent.ts"
+import "dotenv/config";
+
+import { mastra } from "./mastra";
+
+const threadId = "123";
+const resourceId = "user-456";
+
+const agent = mastra.getAgent("upstashAgent");
+
+const message = await agent.stream("My name is Mastra", {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+});
+
+await message.textStream.pipeTo(new WritableStream());
+
+const stream = await agent.stream("What's my name?", {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+  memoryOptions: {
+    lastMessages: 5,
+    semanticRecall: {
+      topK: 3,
+      messageRange: 2,
+    },
+  },
+});
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```

package/.docs/raw/reference/streaming/agents/stream.mdx

@@ -11,7 +11,7 @@ The `.stream()` method enables real-time streaming of responses from an agent wi
 
 ## Usage example
 
-```ts title="index.ts" copy
+```ts title="index.ts"
 const stream = await agent.stream("message for agent");
 ```
 
@@ -477,6 +477,27 @@ const stream = await agent.stream("message for agent");
       description:
         "Save messages incrementally after each stream step completes (default: false).",
     },
+    {
+      name: "requireToolApproval",
+      type: "boolean",
+      isOptional: true,
+      description:
+        "When true, all tool calls require explicit approval before execution. The stream will emit `tool-call-approval` chunks and pause until `approveToolCall()` or `declineToolCall()` is called.",
+    },
+    {
+      name: "autoResumeSuspendedTools",
+      type: "boolean",
+      isOptional: true,
+      description:
+        "When true, automatically resumes suspended tools when the user sends a new message on the same thread. The agent extracts `resumeData` from the user's message based on the tool's `resumeSchema`. Requires memory to be configured.",
+    },
+    {
+      name: "toolCallConcurrency",
+      type: "number",
+      isOptional: true,
+      description:
+        "Maximum number of tool calls to execute concurrently. Defaults to 1 when approval may be required, otherwise 10.",
+    },
     {
       name: "providerOptions",
       type: "Record<string, Record<string, JSONValue>>",
@@ -654,7 +675,7 @@ const stream = await agent.stream("message for agent");
 
 ### Mastra Format (Default)
 
-```ts title="index.ts" showLineNumbers copy
+```ts title="index.ts"
 import { stepCountIs } from "ai-v5";
 
 const stream = await agent.stream("Tell me a story", {
@@ -682,7 +703,7 @@ const fullText = await stream.text;
 
 To use the stream with AI SDK v5, you can convert it using our utility function `toAISdkStream`.
 
-```ts title="index.ts" showLineNumbers copy
+```ts title="index.ts"
 import { stepCountIs, createUIMessageStreamResponse } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
 
@@ -703,7 +724,7 @@ return createUIMessageStreamResponse({
 
 All callback functions are now available as top-level properties for a cleaner API experience.
 
-```ts title="index.ts" showLineNumbers copy
+```ts title="index.ts"
 const stream = await agent.stream("Tell me a story", {
   onFinish: (result) => {
     console.log("Streaming finished:", result);
@@ -730,7 +751,7 @@ for await (const chunk of stream.textStream) {
 
 ### Advanced Example with Options
 
-```ts title="index.ts" showLineNumbers copy
+```ts title="index.ts"
 import { z } from "zod";
 import { stepCountIs } from "ai";
 
@@ -765,3 +786,4 @@ await agent.stream("message for agent", {
 
 - [Generating responses](/docs/v1/agents/overview#generating-responses)
 - [Streaming responses](/docs/v1/agents/overview#generating-responses)
+- [Agent Approval](/docs/v1/agents/agent-approval)

package/.docs/raw/reference/streaming/agents/streamLegacy.mdx

@@ -15,7 +15,7 @@ The `.streamLegacy()` method is the legacy version of the agent streaming API, u
 
 ## Usage example
 
-```typescript copy
+```typescript
 await agent.streamLegacy("message for agent");
 ```
 
@@ -534,7 +534,7 @@ await agent.streamLegacy("message for agent");
 
 ## Extended usage example
 
-```typescript showLineNumbers copy
+```typescript
 await agent.streamLegacy("message for agent", {
   temperature: 0.7,
   maxSteps: 3,

package/.docs/raw/reference/streaming/workflows/observeStream.mdx

@@ -9,7 +9,7 @@ The `.observeStream()` method opens a new `ReadableStream` to a workflow run tha
 
 ## Usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 run.stream({

package/.docs/raw/reference/streaming/workflows/resumeStream.mdx

@@ -9,7 +9,7 @@ The `.resumeStream()` method resumes a suspended workflow run with new data, all
 
 ## Usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 const stream = run.stream({

package/.docs/raw/reference/streaming/workflows/stream.mdx

@@ -5,18 +5,22 @@ description: Documentation for the `Run.stream()` method in workflows, which ena
 
 # Run.stream()
 
-The `.stream()` method enables real-time streaming of responses from a workflow.
+The `.stream()` method enables real-time streaming of responses from a workflow. It returns a `ReadableStream` of events directly.
 
 ## Usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
-const stream = run.stream({
+const stream = await run.stream({
   inputData: {
     value: "initial data",
   },
 });
+
+for await (const chunk of stream) {
+  console.log(chunk);
+}
 ```
 
 ## Parameters
@@ -129,42 +133,37 @@ const stream = run.stream({
 
 ## Returns
 
+Returns a `WorkflowRunOutput` object that implements the async iterable interface (can be used directly in `for await...of` loops) and provides access to the stream and workflow execution results.
+
 <PropertiesTable
   content={[
     {
-      name: "stream",
-      type: "MastraWorkflowStream<ChunkType>",
+      name: "fullStream",
+      type: "ReadableStream<WorkflowStreamEvent>",
       description:
-        "A custom stream that extends ReadableStream<ChunkType> with additional workflow-specific properties",
+        "A ReadableStream of workflow events that you can iterate over to track progress in real-time. You can also iterate over the WorkflowRunOutput object directly.",
     },
     {
-      name: "stream.status",
-      type: "Promise<RunStatus>",
-      description: "A promise that resolves to the current workflow run status",
-    },
-    {
-      name: "stream.result",
-      type: "Promise<WorkflowResult<TState, TOutput, TSteps>>",
+      name: "result",
+      type: "Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>",
       description: "A promise that resolves to the final workflow result",
     },
     {
-      name: "stream.usage",
-      type: "Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cacheInputTokens?: number }>",
-      description: "A promise that resolves to token usage statistics",
+      name: "status",
+      type: "WorkflowRunStatus",
+      description: "The current workflow run status ('running', 'suspended', 'success', 'failed', 'canceled', or 'tripwire')",
     },
     {
-      name: "stream.traceId",
-      type: "string",
-      isOptional: true,
-      description:
-        "The trace ID associated with this execution when Tracing is enabled.",
+      name: "usage",
+      type: "Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cachedInputTokens?: number }>",
+      description: "A promise that resolves to token usage statistics",
     },
   ]}
 />
 
 ## Extended usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 const stream = run.stream({
@@ -173,7 +172,21 @@ const stream = run.stream({
   },
 });
 
+// Iterate over stream events (you can iterate over stream directly or use stream.fullStream)
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+
+// Access the final result
 const result = await stream.result;
+console.log("Final result:", result);
+
+// Access token usage
+const usage = await stream.usage;
+console.log("Token usage:", usage);
+
+// Check current status
+console.log("Status:", stream.status);
 ```
 
 ## Stream Events

package/.docs/raw/reference/streaming/workflows/timeTravelStream.mdx

@@ -9,7 +9,7 @@ The `.timeTravelStream()` method re-executes a workflow starting from any specif
 
 ## Usage example
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 const output = run.timeTravelStream({
@@ -76,7 +76,7 @@ The stream emits various workflow events during execution:
 
 ### Processing events during time travel
 
-```typescript showLineNumbers copy
+```typescript
 const run = await workflow.createRun();
 
 const output = run.timeTravelStream({
@@ -104,7 +104,7 @@ console.log("Time travel completed:", result);
 
 ### Time travel stream with context
 
-```typescript showLineNumbers copy
+```typescript
 const output = run.timeTravelStream({
   step: "step2",
   context: {
@@ -128,7 +128,7 @@ const result = await output.result;
 
 ### Time travel stream with nested workflows
 
-```typescript showLineNumbers copy
+```typescript
 const output = run.timeTravelStream({
   step: ["nestedWorkflow", "step3"],
   inputData: { value: 10 },

package/.docs/raw/reference/templates/overview.mdx

@@ -20,7 +20,7 @@ Mastra templates are pre-built project structures that demonstrate specific use
 
 Install a template using the `create-mastra` command:
 
-```bash copy
+```bash
 npx create-mastra@beta --template template-name
 ```
 
@@ -123,7 +123,6 @@ const agent = new Agent({
   name: "example-agent",
   model: "openai/gpt-5.1", // or other provider strings
   instructions: "Your agent instructions here",
-  // ... other configuration
 });
 ```
 

package/.docs/raw/reference/tools/create-tool.mdx

@@ -9,7 +9,7 @@ The `createTool()` function is used to define custom tools that your Mastra agen
 
 ## Usage example
 
-```typescript title="src/mastra/tools/reverse-tool.ts" showLineNumbers copy
+```typescript title="src/mastra/tools/reverse-tool.ts"
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 
@@ -63,6 +63,27 @@ export const tool = createTool({
         "A Zod schema defining the expected output structure of the tool's `execute` function.",
       isOptional: true,
     },
+    {
+      name: "suspendSchema",
+      type: "Zod schema",
+      description:
+        "A Zod schema defining the structure of the payload passed to `suspend()`. This payload is returned to the client when the tool suspends execution.",
+      isOptional: true,
+    },
+    {
+      name: "resumeSchema",
+      type: "Zod schema",
+      description:
+        "A Zod schema defining the expected structure of `resumeData` when the tool is resumed. Used by the agent to extract data from user messages when `autoResumeSuspendedTools` is enabled.",
+      isOptional: true,
+    },
+    {
+      name: "requireApproval",
+      type: "boolean",
+      description:
+        "When true, the tool requires explicit approval before execution. The agent will emit a `tool-call-approval` chunk and pause until approved or declined.",
+      isOptional: true,
+    },
     {
       name: "execute",
       type: "function",
@@ -194,7 +215,6 @@ export const tool = createTool({
   onInputStart: ({ toolCallId, messages, abortSignal }) => {
     console.log(`Tool ${toolCallId} input streaming started`);
   },
-  // ... other properties
 });
 ```
 
@@ -209,7 +229,6 @@ export const tool = createTool({
   onInputDelta: ({ inputTextDelta, toolCallId, messages, abortSignal }) => {
     console.log(`Received input chunk: ${inputTextDelta}`);
   },
-  // ... other properties
 });
 ```
 
@@ -228,7 +247,6 @@ export const tool = createTool({
     console.log(`Tool received complete input:`, input);
     // input is fully typed based on inputSchema
   },
-  // ... other properties
 });
 ```
 
@@ -284,5 +302,6 @@ Hook errors are caught and logged automatically, but do not prevent tool executi
 
 - [MCP Overview](/docs/v1/mcp/overview)
 - [Using Tools with Agents](/docs/v1/agents/using-tools)
+- [Agent Approval](/docs/v1/agents/agent-approval)
 - [Tool Streaming](/docs/v1/streaming/tool-streaming)
-- [Request Context](/docs/v1/server-db/request-context#accessing-values-with-tools)
+- [Request Context](/docs/v1/server/request-context#accessing-values-with-tools)

package/.docs/raw/reference/tools/graph-rag-tool.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Reference: createGraphRAGTool() | Tools & MCP"
-description: Documentation for the Graph RAG Tool in Mastra, which enhances RAG by building a graph of semantic relationships between documents.
+description: Documentation for the GraphRAG Tool in Mastra, which enhances RAG by building a graph of semantic relationships between documents.
 ---
 
 # createGraphRAGTool()
@@ -253,8 +253,8 @@ const response = await agent.generate(
 
 For more information on request context, please see:
 
-- [Agent Request Context](/docs/v1/server-db/request-context)
-- [Request Context](/docs/v1/server-db/request-context#accessing-values-with-tools)
+- [Agent Request Context](/docs/v1/server/request-context)
+- [Request Context](/docs/v1/server/request-context#accessing-values-with-tools)
 
 ## Related
 

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

@@ -326,7 +326,7 @@ This agent-driven approach:
 
 For detailed filter syntax and store-specific capabilities, see the [Metadata Filters](../rag/metadata-filters) documentation.
 
-For an example of how agent-driven filtering works, see the [Agent-Driven Metadata Filtering](/examples/v1/rag/usage/filter-rag) example.
+For an example of how agent-driven filtering works, see the [Agent-Driven Metadata Filtering](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/filter-rag) example.
 
 ## Example with Reranking
 
@@ -567,14 +567,14 @@ const response = await agent.generate(
 
 For more information on request context, please see:
 
-- [Agent Request Context](/docs/v1/server-db/request-context)
-- [Request Context](/docs/v1/server-db/request-context#accessing-values-with-tools)
+- [Agent Request Context](/docs/v1/server/request-context)
+- [Request Context](/docs/v1/server/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"
+```typescript title="src/index.ts"
 import { RequestContext } from "@mastra/core/request-context";
 import { createVectorQueryTool } from "@mastra/rag";
 import { PgVector } from "@mastra/pg";

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

@@ -142,7 +142,7 @@ Returns an array of index names as strings.
 
 Returns:
 
-```typescript copy
+```typescript
 interface IndexStats {
   dimension: number;
   count: number;
@@ -219,7 +219,7 @@ interface IndexStats {
 
 Query results are returned in this format:
 
-```typescript copy
+```typescript
 interface QueryResult {
   id: string;
   score: number;
@@ -232,7 +232,7 @@ interface QueryResult {
 
 The store throws typed errors that can be caught:
 
-```typescript copy
+```typescript
 try {
   await store.query({
     indexName: "index_name",

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

@@ -313,7 +313,7 @@ Returns an array of index names as strings.
 
 Returns:
 
-```typescript copy
+```typescript
 interface IndexStats {
   dimension: number;
   count: number;
@@ -475,7 +475,7 @@ await vectorStore.deleteVectors({
 
 Query results are returned in this format:
 
-```typescript copy
+```typescript
 interface QueryResult {
   id: string;
   score: number;
@@ -489,7 +489,7 @@ interface QueryResult {
 
 The store throws typed errors that can be caught:
 
-```typescript copy
+```typescript
 try {
   await store.query({
     indexName: "index_name",

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

@@ -9,7 +9,7 @@ The ConvexVector class provides vector storage and similarity search using [Conv
 
 ## Installation
 
-```bash copy
+```bash
 npm install @mastra/convex@beta
 ```
 
@@ -94,7 +94,7 @@ const vectorStore = new ConvexVector({
   ]}
 />
 
-```typescript copy
+```typescript
 await vectorStore.createIndex({
   indexName: "my_vectors",
   dimension: 1536,
@@ -130,7 +130,7 @@ await vectorStore.createIndex({
   ]}
 />
 
-```typescript copy
+```typescript
 await vectorStore.upsert({
   indexName: "my_vectors",
   vectors: [[0.1, 0.2, 0.3, ...]],
@@ -176,7 +176,7 @@ await vectorStore.upsert({
   ]}
 />
 
-```typescript copy
+```typescript
 const results = await vectorStore.query({
   indexName: "my_vectors",
   queryVector: [0.1, 0.2, 0.3, ...],
@@ -189,7 +189,7 @@ const results = await vectorStore.query({
 
 Returns an array of index names as strings.
 
-```typescript copy
+```typescript
 const indexes = await vectorStore.listIndexes();
 // ["my_vectors", "embeddings", ...]
 ```
@@ -208,7 +208,7 @@ const indexes = await vectorStore.listIndexes();
 
 Returns:
 
-```typescript copy
+```typescript
 interface IndexStats {
   dimension: number;
   count: number;
@@ -230,7 +230,7 @@ interface IndexStats {
 
 Deletes the index and all its vectors.
 
-```typescript copy
+```typescript
 await vectorStore.deleteIndex({ indexName: "my_vectors" });
 ```
 
@@ -265,7 +265,7 @@ Update a single vector by ID or by metadata filter. Either `id` or `filter` must
   ]}
 />
 
-```typescript copy
+```typescript
 // Update by ID
 await vectorStore.updateVector({
   indexName: "my_vectors",
@@ -303,7 +303,7 @@ await vectorStore.updateVector({
   ]}
 />
 
-```typescript copy
+```typescript
 await vectorStore.deleteVector({ indexName: "my_vectors", id: "vector123" });
 ```
 
@@ -333,7 +333,7 @@ Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` m
   ]}
 />
 
-```typescript copy
+```typescript
 // Delete by IDs
 await vectorStore.deleteVectors({
   indexName: "my_vectors",
@@ -351,7 +351,7 @@ await vectorStore.deleteVectors({
 
 Query results are returned in this format:
 
-```typescript copy
+```typescript
 interface QueryResult {
   id: string;
   score: number;
@@ -364,7 +364,7 @@ interface QueryResult {
 
 ConvexVector supports metadata filtering with various operators:
 
-```typescript copy
+```typescript
 // Simple equality
 const results = await vectorStore.query({
   indexName: "my_vectors",

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

@@ -14,13 +14,13 @@ The `CouchbaseVector` class provides vector search using [Couchbase Vector Searc
 
 ## Installation
 
-```bash copy
+```bash
 npm install @mastra/couchbase@beta
 ```
 
 ## Usage Example
 
-```typescript copy
+```typescript
 import { CouchbaseVector } from "@mastra/couchbase";
 
 const store = new CouchbaseVector({
@@ -209,7 +209,7 @@ Returns information about the index.
 
 Returns:
 
-```typescript copy
+```typescript
 interface IndexStats {
   dimension: number;
   count: number;
@@ -307,7 +307,7 @@ Closes the Couchbase client connection. Should be called when done using the sto
 
 Query results are returned in this format:
 
-```typescript copy
+```typescript
 interface QueryResult {
   id: string;
   score: number;
@@ -320,7 +320,7 @@ interface QueryResult {
 
 The store throws typed errors that can be caught:
 
-```typescript copy
+```typescript
 try {
   await store.query({
     indexName: "my_index",