@mastra/mcp-docs-server 1.0.0-beta.4 → 1.0.0-beta.6

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

@@ -124,12 +124,6 @@ const limitedResult = await agent.generate("Write a short poem about coding", {
         },
       ],
     },
-    {
-      name: "tracingContext",
-      type: "TracingContext",
-      isOptional: true,
-      description: "Tracing context for span hierarchy and metadata.",
-    },
     {
       name: "returnScorerData",
       type: "boolean",
@@ -253,6 +247,17 @@ const limitedResult = await agent.generate("Write a short poem about coding", {
             },
           ],
         },
+        {
+          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' } }`).",
+            },
+          ],
+        },
       ],
     },
     {
@@ -576,6 +581,50 @@ const limitedResult = await agent.generate("Write a short poem about coding", {
             },
           ],
         },
+        {
+          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.",
+            },
+          ],
+        },
       ],
     },
   ]}

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

@@ -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/getLLM.mdx

@@ -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/network.mdx

@@ -17,7 +17,6 @@ The `.network()` method enables multi-agent collaboration and routing. This meth
 
 ```typescript copy
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import { agent1, agent2 } from "./agents";
 import { workflow1 } from "./workflows";
 import { tool1, tool2 } from "./tools";
@@ -27,7 +26,7 @@ const agent = new Agent({
   name: "Network Agent",
   instructions:
     "You are a network agent that can help users with a variety of tasks.",
-  model: openai("gpt-4o"),
+  model: "openai/gpt-5.1",
   agents: {
     agent1,
     agent2,
@@ -42,7 +41,7 @@ const agent = new Agent({
 });
 
 await agent.network(`
-  Find me the weather in Tokyo. 
+  Find me the weather in Tokyo.
   Based on the weather, plan an activity for me.
 `);
 ```
@@ -155,6 +154,50 @@ await agent.network(`
             },
           ],
         },
+        {
+          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.",
+            },
+          ],
+        },
       ],
     },
     {

package/.docs/raw/reference/cli/mastra.mdx

@@ -75,7 +75,8 @@ ANTHROPIC_BASE_URL=https://anthropic.internal \
 mastra dev
 ```
 
-These are forwarded by the AI SDK and work with any `openai()` or `anthropic()` calls.
+These are forwarded to the Mastra model router and will work with any `"openai/..."`
+or `"anthropic/..."` model selections.
 
 ## `mastra build`
 

package/.docs/raw/reference/client-js/agents.mdx

@@ -174,11 +174,11 @@ response.processDataStream({
 
 #### AI SDK compatible format
 
-To stream AI SDK-formatted parts on the client from an `agent.stream(...)` response, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and use `toAISdkFormat`:
+To stream AI SDK-formatted parts on the client from an `agent.stream(...)` response, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and use `toAISdkStream`:
 
 ```typescript title="client-ai-sdk-transform.ts" copy
 import { createUIMessageStream } from "ai";
-import { toAISdkFormat } from "@mastra/ai-sdk";
+import { toAISdkStream } from "@mastra/ai-sdk";
 import type { ChunkType, MastraModelOutput } from "@mastra/core/stream";
 
 const response = await agent.stream({ messages: "Tell me a story" });
@@ -195,7 +195,7 @@ const chunkStream: ReadableStream<ChunkType> = new ReadableStream<ChunkType>({
 
 const uiMessageStream = createUIMessageStream({
   execute: async ({ writer }) => {
-    for await (const part of toAISdkFormat(
+    for await (const part of toAISdkStream(
       chunkStream as unknown as MastraModelOutput,
       { from: "agent" },
     )) {

package/.docs/raw/reference/client-js/memory.mdx

@@ -133,6 +133,49 @@ const result = await thread.deleteMessages([
 // Returns: { success: true, message: "Message deleted successfully" }
 ```
 
+## Working Memory
+
+Working memory allows agents to maintain persistent information about users across interactions. It can be scoped to either a specific thread or across all threads for a resource (user).
+
+### Get Working Memory
+
+Retrieve the current working memory for a thread:
+
+```typescript
+const workingMemory = await mastraClient.getWorkingMemory({
+  agentId: "agent-1",
+  threadId: "thread-1",
+  resourceId: "user-123", // Optional, required for resource-scoped memory
+});
+```
+
+The response includes:
+- `workingMemory`: The current working memory content (string or null)
+- `source`: Whether the memory is from `"thread"` or `"resource"` scope
+- `workingMemoryTemplate`: The template used for working memory (if configured)
+- `threadExists`: Whether the thread exists
+
+### Update Working Memory
+
+Update the working memory content for a thread:
+
+```typescript
+await mastraClient.updateWorkingMemory({
+  agentId: "agent-1",
+  threadId: "thread-1",
+  workingMemory: `# User Profile
+- Name: John Doe
+- Location: New York
+- Preferences: Prefers formal communication
+`,
+  resourceId: "user-123", // Optional, required for resource-scoped memory
+});
+
+// Returns: { success: true }
+```
+
+**Note:** For resource-scoped working memory, you must provide the `resourceId` parameter. This allows the memory to persist across all conversation threads for that user.
+
 ### Get Memory Status
 
 Check the status of the memory system:

package/.docs/raw/reference/client-js/workflows.mdx

@@ -17,7 +17,7 @@ const workflows = await mastraClient.listWorkflows();
 
 ## Working with a Specific Workflow
 
-Get an instance of a specific workflow as defined by the const name:
+Get an instance of a specific workflow by its ID:
 
 ```typescript title="src/mastra/workflows/test-workflow.ts"
 export const testWorkflow = createWorkflow({
@@ -26,12 +26,12 @@ export const testWorkflow = createWorkflow({
 ```
 
 ```typescript
-const workflow = mastraClient.getWorkflow("testWorkflow");
+const workflow = mastraClient.getWorkflow("city-workflow");
 ```
 
 ## Workflow Methods
 
-### Get Workflow Details
+### details()
 
 Retrieve detailed information about a workflow:
 
@@ -39,109 +39,138 @@ Retrieve detailed information about a workflow:
 const details = await workflow.details();
 ```
 
-### Start workflow run asynchronously
+### createRun()
 
-Start a workflow run with inputData and await full run results:
+Create a new workflow run instance:
 
 ```typescript
 const run = await workflow.createRun();
 
+// Or with an existing runId
+const run = await workflow.createRun({ runId: "existing-run-id" });
+```
+
+### startAsync()
+
+Start a workflow run and await the full result:
+
+```typescript
+const run = await workflow.createRun();
+
+const result = await run.startAsync({
+  inputData: {
+    city: "New York",
+  },
+});
+```
+
+You can also pass `initialState` to set the starting values for the workflow's state:
+
+```typescript
 const result = await run.startAsync({
   inputData: {
     city: "New York",
   },
+  initialState: {
+    count: 0,
+    items: [],
+  },
 });
 ```
 
-### Resume Workflow run asynchronously
+The `initialState` object should match the structure defined in the workflow's `stateSchema`. See [Workflow State](/docs/v1/workflows/workflow-state) for more details.
 
-Resume a suspended workflow step and await full run result:
+### start()
+
+Start a workflow run without waiting for completion:
 
 ```typescript
 const run = await workflow.createRun();
 
+await run.start({
+  inputData: {
+    city: "New York",
+  },
+});
+
+// Poll for results later
+const result = await workflow.runExecutionResult(run.runId);
+```
+
+This is useful for long-running workflows where you want to start execution and check results later.
+
+### resumeAsync()
+
+Resume a suspended workflow step and await the full result:
+
+```typescript
+const run = await workflow.createRun({ runId: prevRunId });
+
 const result = await run.resumeAsync({
   step: "step-id",
   resumeData: { key: "value" },
 });
 ```
 
-### Resume Workflow
+### resume()
 
-Resume workflow run:
+Resume a suspended workflow step without waiting for completion:
 
 ```typescript
-try {
-  const workflow = mastraClient.getWorkflow("testWorkflow");
+const run = await workflow.createRun({ runId: prevRunId });
 
-  const run = await workflow.createRun({ runId: prevRunId });
-
-  run.resume({
-    step: "step-id",
-    resumeData: { key: "value" },
-  });
-} catch (e) {
-  console.error(e);
-}
+await run.resume({
+  step: "step-id",
+  resumeData: { key: "value" },
+});
 ```
 
-### Stream Workflow
+### stream()
 
 Stream workflow execution for real-time updates:
 
 ```typescript
-try {
-  const workflow = mastraClient.getWorkflow("testWorkflow");
-
-  const run = await workflow.createRun();
+const run = await workflow.createRun();
 
-  const stream = await run.stream({
-    inputData: {
-      city: "New York",
-    },
-  });
+const stream = await run.stream({
+  inputData: {
+    city: "New York",
+  },
+});
 
-  for await (const chunk of stream) {
-    console.log(JSON.stringify(chunk, null, 2));
-  }
-} catch (e) {
-  console.error("Workflow error:", e);
+for await (const chunk of stream) {
+  console.log(JSON.stringify(chunk, null, 2));
 }
 ```
 
-### Get Workflow Run result
+### runExecutionResult()
 
-Get the result of a workflow run:
+Get the execution result for a workflow run:
 
 ```typescript
-try {
-  const workflow = mastraClient.getWorkflow("testWorkflow");
-
-  const run = await workflow.createRun();
-
-  // start the workflow run
-  const startResult = await run.start({
-    inputData: {
-      city: "New York",
-    },
-  });
-
-  const result = await workflow.runExecutionResult(run.runId);
-
-  console.log(result);
-} catch (e) {
-  console.error(e);
-}
+const result = await workflow.runExecutionResult(runId);
 ```
 
-This is useful when dealing with long running workflows. You can use this to poll the result of the workflow run.
-
-### Workflow run result
+<h3>Run result format</h3>
 
 A workflow run result yields the following:
 
-| Field            | Type                                                                                                                                                                                                                                               | Description                                      |
-| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| `payload`        | `{currentStep?: {id: string, status: string, output?: Record<string, any>, payload?: Record<string, any>}, workflowState: {status: string, steps: Record<string, {status: string, output?: Record<string, any>, payload?: Record<string, any>}>}}` | The current step and workflow state of the run   |
-| `eventTimestamp` | `Date`                                                                                                                                                                                                                                             | The timestamp of the event                       |
-| `runId`          | `string`                                                                                                                                                                                                                                           | Unique identifier for this workflow run instance |
+<PropertiesTable
+  content={[
+    {
+      name: "runId",
+      type: "string",
+      description: "Unique identifier for this workflow run instance",
+    },
+    {
+      name: "eventTimestamp",
+      type: "Date",
+      description: "The timestamp of the event",
+    },
+    {
+      name: "payload",
+      type: "object",
+      description: "Contains currentStep (id, status, output, payload) and workflowState (status, steps record)",
+    },
+  ]}
+/>

package/.docs/raw/reference/core/getLogger.mdx

@@ -32,5 +32,5 @@ This method does not accept any parameters.
 
 ## Related
 
-- [Logging overview](/docs/v1/logging)
+- [Logging overview](/docs/v1/observability/logging)
 - [Logger reference](/reference/v1/logging/pino-logger)

package/.docs/raw/reference/core/listLogs.mdx

@@ -92,5 +92,5 @@ mastra.listLogs("456");
 
 ## Related
 
-- [Logging overview](/docs/v1/logging)
+- [Logging overview](/docs/v1/observability/logging)
 - [Logger reference](/reference/v1/logging/pino-logger)

package/.docs/raw/reference/core/listLogsByRunId.mdx

@@ -83,5 +83,5 @@ mastra.listLogsByRunId({ runId: "123", transportId: "456" });
 
 ## Related
 
-- [Logging overview](/docs/v1/logging)
+- [Logging overview](/docs/v1/observability/logging)
 - [Logger reference](/reference/v1/logging/pino-logger)

package/.docs/raw/reference/core/mastra-model-gateway.mdx

@@ -15,9 +15,8 @@ import { createOpenAICompatible } from '@ai-sdk/openai-compatible-v5';
 import type { LanguageModelV2 } from '@ai-sdk/provider-v5';
 
 class MyCustomGateway extends MastraModelGateway {
-  readonly id = 'my-custom-gateway';
+  readonly id = 'custom';
   readonly name = 'My Custom Gateway';
-  readonly prefix = 'custom';
 
   async fetchProviders(): Promise<Record<string, ProviderConfig>> {
     return {
@@ -66,7 +65,7 @@ class MyCustomGateway extends MastraModelGateway {
     {
       name: 'id',
       type: 'string',
-      description: 'Unique identifier for the gateway. Used for versioning and identification.',
+      description: 'Unique identifier for the gateway. This ID is used as the prefix for all providers from this gateway (e.g., "netlify/anthropic"). Exception: models.dev is a provider registry and doesn\'t use a prefix.',
     },
     {
       name: 'name',
@@ -76,18 +75,6 @@ class MyCustomGateway extends MastraModelGateway {
   ]}
 />
 
-## Optional Properties
-
-<PropertiesTable
-  content={[
-    {
-      name: 'prefix',
-      type: 'string | undefined',
-      description: 'Optional prefix for provider IDs. If set, all providers from this gateway will be prefixed (e.g., "netlify/openai"). Registry gateways typically don\'t have a prefix.',
-    },
-  ]}
-/>
-
 ## Required Methods
 
 ### fetchProviders()
@@ -217,15 +204,14 @@ Returns the gateway's unique identifier.
 
 ## Model ID Format
 
-When a gateway has a prefix, models are accessed using this format:
+For true gateways, the gateway ID is used as a prefix and models are accessed using this format:
 
 ```
-[prefix]/[provider]/[model]
+[gateway-id]/[provider]/[model]
 ```
 
 Examples:
-- With prefix `'custom'`: `'custom/my-provider/model-1'`
-- Without prefix: `'my-provider/model-1'`
+- Gateway with `id = 'custom'`: `'custom/my-provider/model-1'`
 
 ## Built-in Implementations
 

package/.docs/raw/reference/core/setLogger.mdx

@@ -45,5 +45,5 @@ This method does not return a value.
 
 ## Related
 
-- [Logging overview](/docs/v1/logging)
+- [Logging overview](/docs/v1/observability/logging)
 - [Logger reference](/reference/v1/logging/pino-logger)

package/.docs/raw/reference/core/setTelemetry.mdx

@@ -32,5 +32,5 @@ This method does not return a value.
 
 ## Related
 
-- [Logging](/docs/v1/logging)
+- [Logging](/docs/v1/observability/logging)
 - [PinoLogger](/reference/v1/logging/pino-logger)

package/.docs/raw/reference/deployer/netlify.mdx

@@ -9,12 +9,11 @@ The `NetlifyDeployer` class handles deployment of standalone Mastra applications
 
 ## Usage example
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts" copy
 import { Mastra } from "@mastra/core";
 import { NetlifyDeployer } from "@mastra/deployer-netlify";
 
 export const mastra = new Mastra({
-  // ...
   deployer: new NetlifyDeployer(),
 });
 ```