@mastra/mcp-docs-server 1.1.42-alpha.8 → 1.1.42

package/.docs/docs/agent-builder/memory.md

@@ -37,7 +37,7 @@ new MastraEditor({
       agent: {
         memory: {
           observationalMemory: {
-            model: 'openai/gpt-5.4',
+            model: 'openai/gpt-5.5',
           },
         },
       },

package/.docs/docs/agents/a2a.md

@@ -81,7 +81,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support Agent',
   instructions: 'Answer user questions and delegate weather questions when needed.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: {
     remoteWeatherAgent,
   },

package/.docs/docs/agents/acp.md

@@ -84,7 +84,7 @@ export const codeSupervisor = new Agent({
   id: 'code-supervisor',
   name: 'Code Supervisor',
   instructions: 'Delegate code editing tasks to the code-agent subagent.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: {
     codeAgent,
   },
@@ -113,7 +113,7 @@ export const codeSupervisor = new Agent({
   id: 'code-supervisor',
   name: 'Code Supervisor',
   instructions: 'Use the code-agent tool when a task requires repository inspection or code edits.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: {
     codeAgentTool,
   },
@@ -178,14 +178,14 @@ export const codeAgent = new AcpAgent({
   description: 'An ACP-compatible coding agent',
   command: 'claude',
   args: ['--acp'],
-  model: '__AI_SDK_ANTHROPIC_MODEL_SONNET__',
+  model: 'claude-sonnet-4-6',
 })
 ```
 
 You can also change the model at runtime with `setModel()`:
 
 ```typescript
-await codeAgent.setModel('__AI_SDK_ANTHROPIC_MODEL_SONNET__')
+await codeAgent.setModel('claude-sonnet-4-6')
 ```
 
 If the ACP agent advertises available models and your model ID doesn't match any of them, Mastra throws an error listing the valid options:

package/.docs/docs/agents/adding-voice.md

@@ -20,7 +20,7 @@ export const agent = new Agent({
   id: 'voice-agent',
   name: 'Voice Agent',
   instructions: `You are a helpful assistant with both STT and TTS capabilities.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   voice,
 })
 
@@ -109,7 +109,7 @@ export const agent = new Agent({
   id: 'speech-to-speech-agent',
   name: 'Speech-to-Speech Agent',
   instructions: `You are a helpful assistant with speech-to-speech capabilities.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: {
     // Tools configured on Agent are passed to voice provider
     search,
@@ -146,7 +146,7 @@ export const agent = new Agent({
   id: 'support-line',
   name: 'Support Line',
   instructions: ({ requestContext }) => `Help user ${requestContext.get('user')}.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   voice: ({ requestContext }) => new OpenAIRealtimeVoice({ apiKey: requestContext.get('apiKey') }),
 })
 
@@ -240,7 +240,7 @@ export const convertToText = async (input: string | NodeJS.ReadableStream): Prom
 export const hybridVoiceAgent = new Agent({
   id: 'hybrid-voice-agent',
   name: 'Hybrid Voice Agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   instructions: 'You can speak and listen using different providers.',
   voice: new CompositeVoice({
     input: new OpenAIVoice(),
@@ -252,7 +252,7 @@ export const unifiedVoiceAgent = new Agent({
   id: 'unified-voice-agent',
   name: 'Unified Voice Agent',
   instructions: 'You are an agent with both STT and TTS capabilities.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   voice: new OpenAIVoice(),
 })
 
@@ -294,7 +294,7 @@ export const agent = new Agent({
   id: 'voice-agent',
   name: 'Voice Agent',
   instructions: `You are a helpful assistant with both STT and TTS capabilities.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 
   // Create a composite voice using OpenAI for listening and PlayAI for speaking
   voice: new CompositeVoice({
@@ -319,7 +319,7 @@ export const agent = new Agent({
   id: 'aisdk-voice-agent',
   name: 'AI SDK Voice Agent',
   instructions: `You are a helpful assistant with voice capabilities.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 
   // Pass AI SDK models directly to CompositeVoice
   voice: new CompositeVoice({

package/.docs/docs/agents/agent-approval.md

@@ -412,7 +412,7 @@ const supervisorAgent = new Agent({
   name: 'Supervisor Agent',
   instructions: `You coordinate data retrieval tasks.
     Delegate to data-agent for user lookups.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: { dataAgent },
   memory: new Memory(),
 })

package/.docs/docs/agents/background-tasks.md

@@ -80,7 +80,7 @@ import { Agent } from '@mastra/core/agent'
 export const researcher = new Agent({
   id: 'researcher',
   instructions: 'You research topics and answer questions.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: { researchTool, summarizeTool },
   backgroundTasks: {
     tools: {
@@ -175,7 +175,7 @@ import { Agent } from '@mastra/core/agent'
 const supervisor = new Agent({
   id: 'supervisor',
   instructions: 'Coordinate research and writing using the available agents.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: { researchAgent, writingAgent },
   backgroundTasks: {
     tools: {

package/.docs/docs/agents/channels.md

@@ -23,7 +23,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support Agent',
   instructions: 'You are a helpful support assistant.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   channels: {
     adapters: {
       slack: createSlackAdapter(),

package/.docs/docs/agents/code-mode.md

@@ -1,6 +1,6 @@
 # Code mode
 
-> **Experimental:** This feature is experimental. Breaking changes may occur without a major version bump until the API is stable.
+> **Alpha:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
 
 Code mode gives an agent a single tool that runs a short TypeScript program in a sandbox. Instead of calling tools one at a time, the model writes a program that orchestrates your existing tools as `external_*` functions, batching calls with `Promise.all`, aggregating with `reduce`, branching, and doing math in a real runtime, then returns a single result.
 
@@ -56,7 +56,7 @@ const { tool, instructions } = createCodeMode({
 const agent = new Agent({
   name: 'shop-assistant',
   instructions: ['You are a helpful shopping assistant.', instructions],
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: { execute_typescript: tool },
 })
 ```
@@ -144,7 +144,7 @@ const inventory = createCodeMode({
 const agent = new Agent({
   name: 'ops-assistant',
   instructions: ['You are an ops assistant.', sales.instructions, inventory.instructions],
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: { sales_code: sales.tool, inventory_code: inventory.tool },
 })
 ```

package/.docs/docs/agents/guardrails.md

@@ -246,7 +246,7 @@ costGuard.onViolation = ({ processorId, message, detail }) => {
 
 // Log moderation violations
 const moderation = new ModerationProcessor({
-  model: '__OPENAI_MODEL_NANO__',
+  model: 'openai/gpt-5-nano',
   strategy: 'block',
 })
 
@@ -360,7 +360,7 @@ See [workflows as processors](https://mastra.ai/docs/agents/processors) for more
 Guardrail processors don't need your primary model. Use a small, fast model for classification tasks:
 
 ```typescript
-const GUARDRAIL_MODEL = '__OPENAI_MODEL_NANO__'
+const GUARDRAIL_MODEL = 'openai/gpt-5-nano'
 
 new ModerationProcessor({ model: GUARDRAIL_MODEL })
 new PIIDetector({ model: GUARDRAIL_MODEL })

package/.docs/docs/agents/networks.md

@@ -27,7 +27,7 @@ export const routingAgent = new Agent({
   name: 'Routing Agent',
   instructions: `
     You are a network of writers and researchers. The user will ask you to research a topic. Always respond with a complete report—no bullet points. Write in full paragraphs, like a blog post. Do not answer with incomplete or uncertain information.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: {
     researchAgent,
     writingAgent,

package/.docs/docs/agents/overview.md

@@ -19,7 +19,7 @@ export const testAgent = new Agent({
   id: 'test-agent',
   name: 'Test Agent',
   instructions: 'You are a helpful assistant.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 ```
 

package/.docs/docs/agents/processors.md

@@ -382,7 +382,7 @@ import { TokenLimiter } from '@mastra/core/processors'
 
 const agent = new Agent({
   name: 'my-agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   inputProcessors: [new TokenLimiter(127000)],
 })
 ```
@@ -647,7 +647,7 @@ const moderationWorkflow = createWorkflow({
 const agent = new Agent({
   id: 'moderated-agent',
   name: 'Moderated Agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   inputProcessors: [moderationWorkflow],
 })
 ```
@@ -686,7 +686,7 @@ export class QualityChecker implements Processor {
 const agent = new Agent({
   id: 'quality-agent',
   name: 'Quality Agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   outputProcessors: [new QualityChecker()],
   maxProcessorRetries: 3, // Maximum retry attempts. If unset, retries are disabled (unless errorProcessors are configured, in which case it defaults to 10).
 })

package/.docs/docs/agents/response-caching.md

@@ -1,6 +1,6 @@
 # Response Caching
 
-> **Experimental:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
+> **Alpha:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
 
 Response caching skips the LLM call and replays a previously cached response when an agent receives an identical request. Use it to reduce latency and avoid paying for repeated calls.
 

package/.docs/docs/agents/sdk-agents.md

@@ -0,0 +1,261 @@
+# SDK agents
+
+SDK agents let you use other agent SDK frameworks inside Mastra. Use them to register SDK-backed agents in a Mastra project while the provider SDK keeps its own runtime, tools, permissions, and agent loop.
+
+## When to use SDK agents
+
+- A vendor SDK already owns the agent loop, tools, permissions, or local runtime.
+- You want to register that SDK-backed agent in a Mastra project.
+- You need Mastra-compatible `generate()` and `stream()` outputs.
+- You want usage, cost, and tool activity from the SDK run to appear in Mastra observability.
+
+## Supported SDK agents
+
+- [Claude Agent SDK](#claude-agent-sdk): Use `@mastra/claude` to register a Claude SDK agent and call it with Mastra `generate()` and `stream()`.
+- [Cursor Agent SDK](#cursor-agent-sdk): Use `@mastra/cursor` to register a Cursor SDK agent and call it with Mastra `generate()` and `stream()`.
+
+## Claude Agent SDK
+
+Use `@mastra/claude` for Claude Code runtime configuration, permissions, tools, and agent-loop behavior.
+
+### Install Claude packages
+
+Install the Mastra package and the Claude Agent SDK peer dependency:
+
+**npm**:
+
+```bash
+npm install @mastra/claude @anthropic-ai/claude-agent-sdk
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/claude @anthropic-ai/claude-agent-sdk
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/claude @anthropic-ai/claude-agent-sdk
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/claude @anthropic-ai/claude-agent-sdk
+```
+
+Set the Claude SDK credential:
+
+```bash
+export ANTHROPIC_API_KEY="..."
+```
+
+### Create a Claude SDK agent
+
+Configure Claude Agent SDK through `sdkOptions`.
+
+```typescript
+import { ClaudeSDKAgent } from '@mastra/claude'
+
+export const claudeSDKAgent = new ClaudeSDKAgent({
+  id: 'claude-sdk-agent',
+  name: 'Claude SDK Agent',
+  description: 'Use Claude Agent SDK through Mastra.',
+  sdkOptions: {
+    model: 'claude-sonnet-4-6',
+    cwd: process.cwd(),
+  },
+})
+```
+
+### Add Claude SDK tools
+
+Claude Agent SDK tools are provided through Claude SDK Model Context Protocol (MCP) servers. Create the server with the Claude SDK, then pass it through `sdkOptions.mcpServers`.
+
+```typescript
+import { createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk'
+import { ClaudeSDKAgent } from '@mastra/claude'
+import { getTemperature } from '../tools/get-temperature'
+
+const weatherServer = createSdkMcpServer({
+  name: 'weather',
+  version: '1.0.0',
+  tools: [getTemperature],
+})
+
+export const claudeSDKAgent = new ClaudeSDKAgent({
+  id: 'claude-sdk-agent',
+  name: 'Claude SDK Agent',
+  description: 'Use Claude Agent SDK through Mastra.',
+  sdkOptions: {
+    model: 'claude-sonnet-4-6',
+    cwd: process.cwd(),
+    mcpServers: {
+      weather: weatherServer,
+    },
+    allowedTools: ['mcp__weather__get_temperature'],
+  },
+})
+```
+
+The `allowedTools` value uses Claude Agent SDK MCP tool naming: `mcp__<server name>__<tool name>`.
+
+## Cursor Agent SDK
+
+Use `@mastra/cursor` to register a Cursor SDK agent in Mastra while keeping Cursor-specific setup in Cursor SDK options.
+
+### Install Cursor packages
+
+Install the Mastra package and the Cursor SDK peer dependency:
+
+**npm**:
+
+```bash
+npm install @mastra/cursor @cursor/sdk
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/cursor @cursor/sdk
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/cursor @cursor/sdk
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/cursor @cursor/sdk
+```
+
+Set the Cursor SDK credential:
+
+```bash
+export CURSOR_API_KEY="..."
+```
+
+### Create a Cursor SDK agent
+
+Configure Cursor Agent SDK through `sdkOptions`.
+
+```typescript
+import { CursorSDKAgent } from '@mastra/cursor'
+
+export const cursorSDKAgent = new CursorSDKAgent({
+  id: 'cursor-sdk-agent',
+  name: 'Cursor SDK Agent',
+  description: 'Use Cursor Agent SDK through Mastra.',
+  sdkOptions: {
+    apiKey: process.env.CURSOR_API_KEY,
+    model: {
+      id: 'gpt-5.5',
+    },
+    local: {
+      cwd: process.cwd(),
+    },
+  },
+})
+```
+
+Cursor local agents require an explicit model. Set it in `sdkOptions.model`.
+
+### Use an existing Cursor SDK agent
+
+If your app already creates a Cursor SDK agent, pass that agent to `CursorSDKAgent` instead:
+
+```typescript
+import { Agent as CursorAgent } from '@cursor/sdk'
+import { CursorSDKAgent } from '@mastra/cursor'
+
+const cursorAgent = CursorAgent.create({
+  apiKey: process.env.CURSOR_API_KEY,
+  model: {
+    id: 'gpt-5.5',
+  },
+  local: {
+    cwd: process.cwd(),
+  },
+})
+
+export const cursorSDKAgent = new CursorSDKAgent({
+  id: 'cursor-sdk-agent',
+  name: 'Cursor SDK Agent',
+  description: 'Use Cursor Agent SDK through Mastra.',
+  agent: cursorAgent,
+})
+```
+
+### Add Cursor SDK tools
+
+Cursor Agent SDK tools are configured with Cursor SDK options. Pass Model Context Protocol (MCP) servers through `sdkOptions.mcpServers`:
+
+```typescript
+import { CursorSDKAgent } from '@mastra/cursor'
+import { mcpServers } from '../mcp/cursor'
+
+export const cursorSDKAgent = new CursorSDKAgent({
+  id: 'cursor-sdk-agent',
+  name: 'Cursor SDK Agent',
+  description: 'Use Cursor Agent SDK through Mastra.',
+  sdkOptions: {
+    apiKey: process.env.CURSOR_API_KEY,
+    model: {
+      id: 'gpt-5.5',
+    },
+    local: {
+      cwd: process.cwd(),
+    },
+    mcpServers,
+  },
+})
+```
+
+## Register SDK agents
+
+Register SDK agents in the Mastra instance like other agents:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { claudeSDKAgent } from './agents/claude-sdk-agent'
+import { cursorSDKAgent } from './agents/cursor-sdk-agent'
+
+export const mastra = new Mastra({
+  agents: {
+    claudeSDKAgent,
+    cursorSDKAgent,
+  },
+})
+```
+
+After registration, call them with `mastra.getAgentById()`:
+
+```typescript
+import { mastra } from './index'
+
+const agent = mastra.getAgentById('cursor-sdk-agent')
+const stream = await agent.stream('Inspect this project and describe the test setup.')
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk)
+}
+```
+
+## Observability
+
+SDK agents create Mastra agent and model spans for `generate()` and `stream()` calls. Mastra records SDK-provided usage, tool activity, and provider metadata when the vendor SDK exposes those events.
+
+Claude SDK runs can include SDK-estimated cost from the Claude result message. Cursor SDK runs include token usage from Cursor interaction updates.
+
+For storage and dashboard setup, see [Observability](https://mastra.ai/docs/observability/overview).
+
+## Related
+
+- [Agents overview](https://mastra.ai/docs/agents/overview)
+- [Tools](https://mastra.ai/docs/agents/using-tools)
+- [Observability](https://mastra.ai/docs/observability/overview)

package/.docs/docs/agents/signals.md

@@ -1,6 +1,6 @@
 # Signals
 
-> **Experimental:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
+> **Alpha:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
 
 Signals are a way to interact with an agent through a thread. Instead of starting every interaction with `agent.stream()`, subscribe to a thread and send messages or signals. Mastra either wakes the agent when the thread is idle, drops input into the running agent loop, or queues input for the next turn.
 

package/.docs/docs/agents/structured-output.md

@@ -178,7 +178,7 @@ const response = await testAgent.generate('Analyze the TypeScript programming la
         differentiators: z.array(z.string()),
       }),
     }),
-    model: 'openai/gpt-5.4',
+    model: 'openai/gpt-5.5',
   },
 })
 
@@ -248,7 +248,7 @@ When `model` is provided to the `structuredOutput` property, Mastra uses a separ
 const response = await testAgent.generate('Tell me about TypeScript.', {
   structuredOutput: {
     schema: yourSchema,
-    model: 'openai/gpt-5.4',
+    model: 'openai/gpt-5.5',
   },
 })
 ```
@@ -267,7 +267,7 @@ const response = await testAgent.generate('Return my profile as structured data.
       hometown: z.string(),
       petName: z.string(),
     }),
-    model: 'openai/gpt-5.4',
+    model: 'openai/gpt-5.5',
     useAgent: true,
   },
 })
@@ -284,7 +284,7 @@ const result = await agent.stream('weather in vancouver?', {
   prepareStep: async ({ stepNumber }) => {
     if (stepNumber === 0) {
       return {
-        model: 'openai/gpt-5.4',
+        model: 'openai/gpt-5.5',
         tools: {
           weatherTool,
         },
@@ -292,7 +292,7 @@ const result = await agent.stream('weather in vancouver?', {
       }
     }
     return {
-      model: 'openai/gpt-5.4',
+      model: 'openai/gpt-5.5',
       tools: undefined,
       structuredOutput: {
         schema: z.object({

package/.docs/docs/agents/supervisor-agents.md

@@ -41,7 +41,7 @@ const supervisor = new Agent({
   id: 'supervisor',
   instructions: `You coordinate research and writing using specialized agents.
     Delegate to research-agent for facts, then writing-agent for content.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: { researchAgent, writingAgent },
   memory: new Memory({
     storage: new LibSQLStore({ id: 'storage', url: 'file:mastra.db' }),
@@ -326,7 +326,7 @@ Enable the [backgroundTasks manager](https://mastra.ai/reference/configuration)
 const supervisor = new Agent({
   id: 'supervisor',
   instructions: 'Coordinate research and writing using the available agents.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: { researchAgent, writingAgent },
   backgroundTasks: {
     tools: {

package/.docs/docs/agents/using-tools.md

@@ -52,7 +52,7 @@ export const weatherAgent = new Agent({
   instructions: `
     You are a helpful weather assistant.
     Use the weatherTool to fetch current weather data.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: { weatherTool },
 })
 ```
@@ -145,7 +145,7 @@ export const weatherAgent = new Agent({
     You are a helpful weather assistant.
     Use the weatherTool to fetch current weather data.
     Use the hazardsTool to provide information about potential weather hazards.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: { weatherTool, hazardsTool },
 })
 ```
@@ -162,14 +162,14 @@ const writer = new Agent({
   name: 'Writer',
   description: 'Drafts and edits written content',
   instructions: 'You are a skilled writer.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 
 export const supervisor = new Agent({
   id: 'supervisor',
   name: 'Supervisor',
   instructions: 'Coordinate the writer to produce content.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: { writer },
 })
 ```
@@ -186,7 +186,7 @@ export const researchAgent = new Agent({
   id: 'research-agent',
   name: 'Research Agent',
   instructions: 'You are a research assistant.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   workflows: { researchWorkflow },
 })
 ```

package/.docs/docs/browser/agent-browser.md

@@ -52,7 +52,7 @@ const browser = new AgentBrowser({
 export const browserAgent = new Agent({
   id: 'browser-agent',
   name: 'Browser Agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   browser,
   instructions: `You are a web automation assistant.
 

package/.docs/docs/browser/browser-viewer.md

@@ -73,7 +73,7 @@ const workspace = new Workspace({
 
 const browserAgent = new Agent({
   id: 'browser-agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   workspace,
   instructions: `You are a web automation assistant.
 Use browser-use commands to navigate and interact with websites.`,

package/.docs/docs/browser/overview.md

@@ -72,7 +72,7 @@ export const webAgent = new Agent({
   id: 'web-agent',
   name: 'Web Agent',
   description: 'A web automation assistant that can navigate websites and complete tasks.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   browser,
   instructions:
     'You are a web automation assistant. Use browser tools to navigate websites and complete tasks.',