@mastra/mcp-docs-server 1.0.0-beta.3 → 1.0.0-beta.5

package/.docs/raw/rag/retrieval.mdx

@@ -27,14 +27,14 @@ Mastra provides flexible retrieval options with support for semantic search, fil
 The simplest approach is direct semantic search. This method uses vector similarity to find chunks that are semantically similar to the query:
 
 ```ts showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { embed } from "ai";
 import { PgVector } from "@mastra/pg";
+import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
 
 // Convert query to embedding
 const { embedding } = await embed({
   value: "What are the main points in the article?",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
 });
 
 // Query vector store
@@ -156,7 +156,7 @@ Sometimes you want to give your agent the ability to query a vector database dir
 const vectorQueryTool = createVectorQueryTool({
   vectorStoreName: "pgVector",
   indexName: "embeddings",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
 });
 ```
 
@@ -177,7 +177,7 @@ The Vector Query Tool supports database-specific configurations that enable you
 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", // Isolate data by environment
@@ -189,7 +189,7 @@ const pineconeQueryTool = createVectorQueryTool({
 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, // Filter low-quality results
@@ -203,7 +203,7 @@ const pgVectorQueryTool = createVectorQueryTool({
 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: { category: "technical" },
@@ -216,7 +216,7 @@ const chromaQueryTool = createVectorQueryTool({
 const lanceQueryTool = createVectorQueryTool({
   vectorStoreName: "lance",
   indexName: "documents",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   databaseConfig: {
     lance: {
       tableName: "myVectors", // Specify which table to query
@@ -272,13 +272,12 @@ When implementing filtering, these prompts are required in the agent's instructi
   <TabItem value="pgvector" label="pgVector">
 
 ```ts showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { PGVECTOR_PROMPT } from "@mastra/pg";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${PGVECTOR_PROMPT}
@@ -292,13 +291,12 @@ export const ragAgent = new Agent({
   <TabItem value="pinecone" label="Pinecone">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { PINECONE_PROMPT } from "@mastra/pinecone";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${PINECONE_PROMPT}
@@ -312,13 +310,12 @@ export const ragAgent = new Agent({
   <TabItem value="qdrant" label="Qdrant">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { QDRANT_PROMPT } from "@mastra/qdrant";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${QDRANT_PROMPT}
@@ -332,13 +329,12 @@ export const ragAgent = new Agent({
   <TabItem value="chroma" label="Chroma">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { CHROMA_PROMPT } from "@mastra/chroma";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${CHROMA_PROMPT}
@@ -352,13 +348,12 @@ export const ragAgent = new Agent({
   <TabItem value="astra" label="Astra">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { ASTRA_PROMPT } from "@mastra/astra";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${ASTRA_PROMPT}
@@ -372,13 +367,12 @@ export const ragAgent = new Agent({
   <TabItem value="libsql" label="LibSQL">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { LIBSQL_PROMPT } from "@mastra/libsql";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${LIBSQL_PROMPT}
@@ -392,13 +386,12 @@ export const ragAgent = new Agent({
   <TabItem value="upstash" label="Upstash">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { UPSTASH_PROMPT } from "@mastra/upstash";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${UPSTASH_PROMPT}
@@ -412,13 +405,12 @@ export const ragAgent = new Agent({
   <TabItem value="vectorize" label="Vectorize">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { VECTORIZE_PROMPT } from "@mastra/vectorize";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${VECTORIZE_PROMPT}
@@ -432,13 +424,12 @@ export const ragAgent = new Agent({
   <TabItem value="mongodb" label="MongoDB">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { MONGODB_PROMPT } from "@mastra/mongodb";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${MONGODB_PROMPT}
@@ -452,13 +443,12 @@ export const ragAgent = new Agent({
   <TabItem value="opensearch" label="OpenSearch">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { OPENSEARCH_PROMPT } from "@mastra/opensearch";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${OPENSEARCH_PROMPT}
@@ -472,13 +462,12 @@ export const ragAgent = new Agent({
   <TabItem value="s3vectors" label="S3Vectors">
 
 ```ts title="vector-store.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { S3VECTORS_PROMPT } from "@mastra/s3vectors";
 
 export const ragAgent = new Agent({
   id: "rag-agent",
   name: "RAG Agent",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   instructions: `
   Process queries using the provided context. Structure responses to be concise and relevant.
   ${S3VECTORS_PROMPT}
@@ -502,7 +491,6 @@ Initial vector similarity search can sometimes miss nuanced relevance. Re-rankin
 Here's how to use re-ranking:
 
 ```ts showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import {
   rerankWithScorer as rerank,
   MastraAgentRelevanceScorer
@@ -516,7 +504,7 @@ const initialResults = await pgVector.query({
 });
 
 // Create a relevance scorer
-const relevanceProvider = new MastraAgentRelevanceScorer('relevance-scorer', openai("gpt-4o-mini"));
+const relevanceProvider = new MastraAgentRelevanceScorer('relevance-scorer', "openai/gpt-5.1");
 
 // Re-rank the results
 const rerankedResults = await rerank({
@@ -561,7 +549,7 @@ Example setup:
 const graphQueryTool = createGraphQueryTool({
   vectorStoreName: "pgVector",
   indexName: "embeddings",
-  model: openai.embedding("text-embedding-3-small"),
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
   graphOptions: {
     threshold: 0.7,
   },

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

@@ -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[]`,
     },
     {

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

@@ -3,6 +3,8 @@ 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
@@ -392,91 +402,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",
@@ -652,13 +578,6 @@ const aiSdkResult = await agent.generate("message for agent", {
         },
       ],
     },
-    {
-      name: "maxTokens",
-      type: "number",
-      isOptional: true,
-      description:
-        "Conditions for stopping execution (e.g., step count, token limit).",
-    },
   ]}
 />
 

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

@@ -3,6 +3,8 @@ title: "Reference: Agent.network() | Agents"
 description: "Documentation for the `Agent.network()` method in Mastra agents, which enables multi-agent collaboration and routing."
 ---
 
+import { MODEL_SETTINGS_OBJECT } from "@site/src/components/ModelSettingsProperties";
+
 # Agent.network()
 
 :::caution Experimental Feature
@@ -15,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";
@@ -25,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,
@@ -40,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.
 `);
 ```
@@ -208,91 +209,7 @@ await agent.network(`
         },
       ],
     },
-    {
-      name: "modelSettings",
-      type: "CallSettings",
-      isOptional: true,
-      description:
-        "Model-specific settings like temperature, maxTokens, topP, etc. These are passed to the underlying language model.",
-      properties: [
-        {
-          parameters: [
-            {
-              name: "temperature",
-              type: "number",
-              isOptional: true,
-              description:
-                "Controls randomness in the model's output. Higher values (e.g., 0.8) make the output more random, lower values (e.g., 0.2) make it more focused and deterministic.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "maxRetries",
-              type: "number",
-              isOptional: true,
-              description: "Maximum number of retries for failed requests.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "topP",
-              type: "number",
-              isOptional: true,
-              description:
-                "Nucleus sampling. This is a number between 0 and 1. It is recommended to set either temperature or topP, but not both.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "topK",
-              type: "number",
-              isOptional: true,
-              description:
-                "Only sample from the top K options for each subsequent token. Used to remove 'long tail' low probability responses.",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "presencePenalty",
-              type: "number",
-              isOptional: true,
-              description:
-                "Presence penalty setting. It affects the likelihood of the model to repeat information that is already in the prompt. A number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition).",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "frequencyPenalty",
-              type: "number",
-              isOptional: true,
-              description:
-                "Frequency penalty setting. It affects the likelihood of the model to repeatedly use the same words or phrases. A number between -1 (increase repetition) and 1 (maximum penalty, decrease repetition).",
-            },
-          ],
-        },
-        {
-          parameters: [
-            {
-              name: "stopSequences",
-              type: "string[]",
-              isOptional: true,
-              description:
-                "Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.",
-            },
-          ],
-        },
-      ],
-    },
+    MODEL_SETTINGS_OBJECT,
     {
       name: "runId",
       type: "string",

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/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)