@mastra/mcp-docs-server 1.2.3 → 1.2.4-alpha.5

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

@@ -63,6 +63,7 @@ import { createDiscordAdapter } from '@chat-adapter/discord'
 import { createSlackAdapter } from '@chat-adapter/slack'
 
 const agent = new Agent({
+  id: 'example',
   name: 'Example',
   instructions: '...',
   model: 'openai/gpt-5.5',
@@ -118,6 +119,7 @@ import { Agent } from '@mastra/core/agent'
 import { createSlackAdapter } from '@chat-adapter/slack'
 
 const agent = new Agent({
+  id: 'streaming-agent',
   name: 'Streaming Agent',
   instructions: '...',
   model: 'openai/gpt-5.5',
@@ -145,6 +147,7 @@ import { defaultTypingStatus } from '@mastra/core/channels'
 import { createDiscordAdapter } from '@chat-adapter/discord'
 
 const agent = new Agent({
+  id: 'custom-typing-agent',
   name: 'Custom Typing Agent',
   instructions: '...',
   model: 'openai/gpt-5.5',
@@ -177,6 +180,7 @@ import { Agent } from '@mastra/core/agent'
 import { createSlackAdapter } from '@chat-adapter/slack'
 
 const agent = new Agent({
+  id: 'custom-handler-agent',
   name: 'Custom Handler Agent',
   instructions: '...',
   model: 'openai/gpt-5.5',
@@ -222,6 +226,7 @@ import { Agent } from '@mastra/core/agent'
 import { createSlackAdapter } from '@chat-adapter/slack'
 
 const agent = new Agent({
+  id: 'sso-agent',
   name: 'SSO Agent',
   instructions: '...',
   model: 'openai/gpt-5.5',

package/.docs/reference/evals/hallucination.md

@@ -155,6 +155,7 @@ const hallucinationScorer = createHallucinationScorer({
 })
 
 const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   model: 'openai/gpt-5.5',
   instructions: 'You are a helpful assistant.',

package/.docs/reference/evals/prompt-alignment.md

@@ -219,6 +219,7 @@ Measure how well your AI agents follow user instructions:
 
 ```typescript
 const agent = new Agent({
+  id: 'coding-assistant',
   name: 'CodingAssistant',
   instructions: 'You are a helpful coding assistant. Always provide working code examples.',
   model: 'openai/gpt-5.5',

package/.docs/reference/index.md

@@ -348,6 +348,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.timeTravel()](https://mastra.ai/reference/workflows/run-methods/timeTravel)
 - [AgentCoreRuntimeSandbox](https://mastra.ai/reference/workspace/agentcore-runtime-sandbox)
 - [AgentFSFilesystem](https://mastra.ai/reference/workspace/agentfs-filesystem)
+- [AppleContainerSandbox](https://mastra.ai/reference/workspace/apple-container-sandbox)
 - [ArchilFilesystem](https://mastra.ai/reference/workspace/archil-filesystem)
 - [AzureBlobFilesystem](https://mastra.ai/reference/workspace/azure-blob-filesystem)
 - [BlaxelSandbox](https://mastra.ai/reference/workspace/blaxel-sandbox)
@@ -359,6 +360,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [GoogleDriveFilesystem](https://mastra.ai/reference/workspace/google-drive-filesystem)
 - [LocalFilesystem](https://mastra.ai/reference/workspace/local-filesystem)
 - [LocalSandbox](https://mastra.ai/reference/workspace/local-sandbox)
+- [MesaFilesystem](https://mastra.ai/reference/workspace/mesa-filesystem)
 - [ModalSandbox](https://mastra.ai/reference/workspace/modal-sandbox)
 - [RailwaySandbox](https://mastra.ai/reference/workspace/railway-sandbox)
 - [S3Filesystem](https://mastra.ai/reference/workspace/s3-filesystem)

package/.docs/reference/memory/memory-class.md

@@ -9,6 +9,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'test-agent',
   name: 'test-agent',
   instructions: 'You are an agent with memory.',
   model: 'openai/gpt-5.5',

package/.docs/reference/memory/observational-memory.md

@@ -11,6 +11,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
@@ -203,6 +204,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
@@ -232,6 +234,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
@@ -261,6 +264,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5.5',
@@ -281,6 +285,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5.5',
@@ -308,6 +313,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'health-assistant',
   name: 'health-assistant',
   instructions: 'You are a health and wellness assistant.',
   model: 'openai/gpt-5.5',
@@ -351,6 +357,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
@@ -666,6 +673,7 @@ const om = new ObservationalMemory({
 })
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',

package/.docs/reference/observability/tracing/exporters/langfuse.md

@@ -102,6 +102,7 @@ const exporter = new LangfuseExporter()
 const prompt = await exporter.client.prompt.get('customer-support', { type: 'text' })
 
 const agent = new Agent({
+  id: 'support-agent',
   name: 'support-agent',
   instructions: prompt.compile(),
   model: 'openai/gpt-5.5',

package/.docs/reference/processors/batch-parts-processor.md

@@ -41,6 +41,7 @@ import { Agent } from '@mastra/core/agent'
 import { BatchPartsProcessor } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'batched-agent',
   name: 'batched-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',

package/.docs/reference/processors/cost-guard-processor.md

@@ -55,6 +55,7 @@ costGuard.onViolation = ({ detail }) => {
 }
 
 const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   model: 'openai/gpt-5-nano',
   processors: {

package/.docs/reference/processors/message-history-processor.md

@@ -43,6 +43,7 @@ const storage = new PostgresStorage({
 })
 
 export const agent = new Agent({
+  id: 'memory-agent',
   name: 'memory-agent',
   instructions: 'You are a helpful assistant with conversation memory',
   model: 'openai/gpt-5.5',

package/.docs/reference/processors/moderation-processor.md

@@ -57,6 +57,7 @@ import { Agent } from '@mastra/core/agent'
 import { ModerationProcessor } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'moderated-agent',
   name: 'moderated-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',
@@ -82,6 +83,7 @@ import { Agent } from '@mastra/core/agent'
 import { BatchPartsProcessor, ModerationProcessor } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'output-moderated-agent',
   name: 'output-moderated-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',

package/.docs/reference/processors/pii-detector.md

@@ -59,6 +59,7 @@ import { Agent } from '@mastra/core/agent'
 import { PIIDetector } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'private-agent',
   name: 'private-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',
@@ -87,6 +88,7 @@ import { Agent } from '@mastra/core/agent'
 import { BatchPartsProcessor, PIIDetector } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'output-pii-agent',
   name: 'output-pii-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',

package/.docs/reference/processors/prefill-error-handler.md

@@ -24,6 +24,7 @@ import { Agent } from '@mastra/core/agent'
 import { PrefillErrorHandler } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'anthropic/claude-opus-4-7',
@@ -45,6 +46,7 @@ const customErrorHandler: Processor = {
 }
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'anthropic/claude-opus-4-7',

package/.docs/reference/processors/processor-interface.md

@@ -726,7 +726,7 @@ Configure processors that implement `processAPIError` in `errorProcessors`:
 
 ```typescript
 const agent = new Agent({
-  // ...
+  id: 'agent',
   errorProcessors: [new PrefillErrorHandler()],
 })
 ```
@@ -987,6 +987,7 @@ import { Agent } from '@mastra/core/agent'
 import { PrefillErrorHandler } from '@mastra/core/processors'
 
 const agent = new Agent({
+  id: 'support-agent',
   name: 'support-agent',
   model: 'openai/gpt-5',
   instructions: '...',
@@ -1005,7 +1006,7 @@ Each array also accepts a function so processors can be built per-request from `
 
 ```typescript
 new Agent({
-  // ...
+  id: 'processor-interface-agent',
   inputProcessors: ({ requestContext }) => {
     const blockedWords = requestContext.get('blockedWords') ?? []
     return [new ContentFilter(blockedWords)]

package/.docs/reference/processors/prompt-injection-detector.md

@@ -51,6 +51,7 @@ import { Agent } from '@mastra/core/agent'
 import { PromptInjectionDetector } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'secure-agent',
   name: 'secure-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',

package/.docs/reference/processors/provider-history-compat.md

@@ -13,6 +13,7 @@ import { Agent } from '@mastra/core/agent'
 import { ProviderHistoryCompat } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'anthropic/claude-sonnet-4-5',
@@ -112,6 +113,7 @@ const stripUnsupportedAssistantMetadata: CompatRule = {
 }
 
 export const agent = new Agent({
+  id: 'custom-provider-agent',
   name: 'custom-provider-agent',
   instructions: 'You are a helpful assistant.',
   model: 'example-provider/model',

package/.docs/reference/processors/regex-filter-processor.md

@@ -48,6 +48,7 @@ import { Agent } from '@mastra/core/agent'
 import { RegexFilterProcessor } from '@mastra/core/processors'
 
 const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   model: 'openai/gpt-5-nano',
   processors: {

package/.docs/reference/processors/response-cache.md

@@ -16,6 +16,7 @@ import { ResponseCache } from '@mastra/core/processors'
 const cache = new InMemoryServerCache()
 
 const agent = new Agent({
+  id: 'search-agent',
   name: 'Search Agent',
   instructions: 'You answer questions concisely.',
   model: 'openai/gpt-5',

package/.docs/reference/processors/semantic-recall-processor.md

@@ -80,6 +80,7 @@ const semanticRecall = new SemanticRecall({
 })
 
 export const agent = new Agent({
+  id: 'semantic-memory-agent',
   name: 'semantic-memory-agent',
   instructions: 'You are a helpful assistant with semantic memory recall',
   model: 'openai/gpt-5.5',

package/.docs/reference/processors/skill-search-processor.md

@@ -71,6 +71,7 @@ const skillSearch = new SkillSearchProcessor({
 })
 
 const agent = new Agent({
+  id: 'skill-agent',
   name: 'skill-agent',
   instructions:
     'You are a helpful assistant. Use search_skills to find relevant skills, then load_skill to load their instructions.',

package/.docs/reference/processors/stream-error-retry-processor.md

@@ -13,6 +13,7 @@ import { Agent } from '@mastra/core/agent'
 import { StreamErrorRetryProcessor } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'openai-agent',
   name: 'openai-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5',
@@ -49,6 +50,7 @@ const isECONNRESET = (error: unknown) => {
 }
 
 export const agent = new Agent({
+  id: 'resilient-agent',
   name: 'resilient-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5',

package/.docs/reference/processors/system-prompt-scrubber.md

@@ -55,6 +55,7 @@ import { Agent } from '@mastra/core/agent'
 import { BatchPartsProcessor, SystemPromptScrubber } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'scrubbed-agent',
   name: 'scrubbed-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',

package/.docs/reference/processors/token-limiter-processor.md

@@ -79,6 +79,7 @@ import { Memory } from '@mastra/memory'
 import { TokenLimiterProcessor } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'context-limited-agent',
   name: 'context-limited-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',
@@ -100,6 +101,7 @@ import { Agent } from '@mastra/core/agent'
 import { TokenLimiterProcessor } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'multi-step-agent',
   name: 'multi-step-agent',
   instructions: 'You are a helpful research assistant with access to tools',
   model: 'openai/gpt-5.5',
@@ -123,6 +125,7 @@ import { Agent } from '@mastra/core/agent'
 import { TokenLimiterProcessor } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'response-limited-agent',
   name: 'response-limited-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',

package/.docs/reference/processors/tool-call-filter.md

@@ -88,6 +88,7 @@ import { Agent } from '@mastra/core/agent'
 import { ToolCallFilter } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'filtered-agent',
   name: 'filtered-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',
@@ -113,6 +114,7 @@ import { Agent } from '@mastra/core/agent'
 import { ToolCallFilter } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'no-tools-context-agent',
   name: 'no-tools-context-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',

package/.docs/reference/processors/tool-search-processor.md

@@ -144,6 +144,7 @@ const toolSearch = new ToolSearchProcessor({
 })
 
 const agent = new Agent({
+  id: 'dynamic-tools-agent',
   name: 'dynamic-tools-agent',
   instructions:
     'You are a helpful assistant with access to many tools. Use search_tools to find relevant tools, then load_tool to make them available.',
@@ -225,6 +226,7 @@ import { Agent } from '@mastra/core/agent'
 import { ToolSearchProcessor, TokenLimiter } from '@mastra/core/processors'
 
 const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   model: 'openai/gpt-5.5',
   inputProcessors: [

package/.docs/reference/processors/working-memory-processor.md

@@ -65,6 +65,7 @@ const storage = new PostgresStorage({
 })
 
 export const agent = new Agent({
+  id: 'personalized-agent',
   name: 'personalized-agent',
   instructions: 'You are a helpful assistant that remembers user preferences',
   model: 'openai/gpt-5.5',

package/.docs/reference/signals/signal-provider.md

@@ -44,6 +44,7 @@ Register with an agent:
 import { Agent } from '@mastra/core/agent'
 
 const agent = new Agent({
+  id: 'agent',
   signals: [new SlackSignals()],
 })
 ```

package/.docs/reference/signals/task-signal-provider.md

@@ -13,6 +13,7 @@ import { Agent } from '@mastra/core/agent'
 import { TaskSignalProvider } from '@mastra/core/signals'
 
 const agent = new Agent({
+  id: 'coder',
   name: 'coder',
   instructions: '...',
   model,

package/.docs/reference/signals/webhook-signal-provider.md

@@ -30,6 +30,7 @@ Register with an agent and subscribe a thread:
 import { Agent } from '@mastra/core/agent'
 
 const agent = new Agent({
+  id: 'agent',
   signals: [webhookProvider],
 })
 

package/.docs/reference/templates/overview.md

@@ -201,6 +201,7 @@ We recommend using OpenAI, Anthropic, or Google model providers for templates. C
 import { Agent } from '@mastra/core/agent'
 
 const agent = new Agent({
+  id: 'example-agent',
   name: 'example-agent',
   model: 'openai/gpt-5.5', // or other provider strings
   instructions: 'Your agent instructions here',

package/.docs/reference/tools/create-code-mode.md

@@ -40,6 +40,7 @@ const { tool, instructions } = createCodeMode({
 })
 
 export const shopAgent = new Agent({
+  id: 'shop-assistant',
   name: 'shop-assistant',
   instructions: ['You are a helpful shopping assistant.', instructions],
   model: 'openai/gpt-5.5',

package/.docs/reference/tools/create-tool.md

@@ -298,6 +298,8 @@ export const weatherTool = createTool({
 
 **execute.context.mcp** (`MCPToolExecutionContext`): MCP-specific context (elicitation, etc.)
 
+**execute.context.observe** (`ToolObserve`): Observability helpers for recording child spans and structured logs from inside a tool's execute function. Always provided — when no tracing context is active, \`span\` runs the function directly and \`log\` is a no-op.
+
 **onInputStart** (`function`): Optional callback invoked when the tool call input streaming begins. Receives \`toolCallId\`, \`messages\`, and \`abortSignal\`.
 
 **onInputDelta** (`function`): Optional callback invoked for each incremental chunk of input text as it streams in. Receives \`inputTextDelta\`, \`toolCallId\`, \`messages\`, and \`abortSignal\`.

package/.docs/reference/tools/mcp-client.md

@@ -1063,6 +1063,7 @@ const mcpClient = new MCPClient({
 
 // Use with an agent — requestContext is automatically forwarded
 const agent = new Agent({
+  id: 'my-agent',
   name: 'My Agent',
   instructions: 'You are a helpful assistant.',
   model: openai('gpt-5.4'),

package/.docs/reference/tools/mcp-server.md

@@ -112,7 +112,7 @@ When you provide agents in the `agents` configuration property, `MCPServer` will
 
 The description for this generated tool will be: "Ask agent `<agent.name>` a question. Agent description: `<agent.description>`".
 
-**Important**: For an agent to be converted into a tool, it **must** have a non-empty `description` string property set in its configuration when it was instantiated (e.g., `new Agent({ name: 'myAgent', description: 'This agent does X.', ... })`). If an agent is passed to `MCPServer` with a missing or empty `description`, an error will be thrown when the `MCPServer` is instantiated, and server setup will fail.
+**Important**: For an agent to be converted into a tool, it **must** have a non-empty `description` string property set in its configuration when it was instantiated (e.g., `new Agent({ id: 'my-agent', name: 'myAgent', description: 'This agent does X.', ... })`). If an agent is passed to `MCPServer` with a missing or empty `description`, an error will be thrown when the `MCPServer` is instantiated, and server setup will fail.
 
 This allows you to quickly expose the generative capabilities of your agents through the MCP, enabling clients to "ask" your agents questions directly.
 

package/.docs/reference/voice/voice.addInstructions.md

@@ -18,6 +18,7 @@ const voice = new OpenAIRealtimeVoice({
 
 // Create an agent with the voice provider
 const agent = new Agent({
+  id: 'customer-support-agent',
   name: 'Customer Support Agent',
   instructions: 'You are a helpful customer support agent for a software company.',
   model: 'openai/gpt-5.5',

package/.docs/reference/workspace/agentcore-runtime-sandbox.md

@@ -52,6 +52,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'dev-agent',
   name: 'dev-agent',
   model: 'anthropic/claude-sonnet-4-6',
   instructions: 'You are a helpful development assistant.',

package/.docs/reference/workspace/agentfs-filesystem.md

@@ -46,6 +46,7 @@ const workspace = new Workspace({
 })
 
 const agent = new Agent({
+  id: 'file-agent',
   name: 'file-agent',
   model: 'openai/gpt-5.5',
   workspace,