@mastra/mcp-docs-server 1.2.11-alpha.1 → 1.2.11-alpha.4

package/.docs/docs/agent-controller/channels.md

@@ -0,0 +1,109 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Channels
+
+Channels connect an AgentController to messaging platforms like Slack, Discord, and Telegram, so a controller-backed session runs inside a chat thread. Inbound platform messages route into a controller [`Session`](https://mastra.ai/docs/agent-controller/session), and the agent's streamed output renders back to the platform with native streaming, tool approval cards, and typing status.
+
+AgentController channels build on the same channel layer as [agent channels](https://mastra.ai/docs/capabilities/channels/overview): the same adapters, the same configuration shape, and the same rendering pipeline. The difference is what receives the message. On an agent, the message goes straight into the agent loop. On an AgentController, the message goes into a durable session that tracks the active mode, model, permission grants, and state across the whole conversation.
+
+## Configure a controller
+
+Pass a `channels` configuration to the AgentController constructor. It accepts the same shape as the [`Agent` channels option](https://mastra.ai/docs/capabilities/channels/overview):
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { AgentController } from '@mastra/core/agent-controller'
+import { createSlackAdapter } from '@chat-adapter/slack'
+import { LibSQLStore } from '@mastra/libsql'
+
+const agent = new Agent({
+  id: 'assistant',
+  name: 'assistant',
+  instructions: 'Help the user plan and complete tasks.',
+  model: 'anthropic/claude-sonnet-4-6',
+})
+
+export const agentController = new AgentController({
+  id: 'my-agent-controller',
+  agent,
+  storage: new LibSQLStore({ url: 'file:./data.db' }),
+  modes: [
+    {
+      id: 'plan',
+      name: 'Plan',
+      metadata: { default: true },
+      instructions: 'Reason about changes before making them.',
+    },
+    { id: 'build', name: 'Build', instructions: 'Implement the approved plan.' },
+  ],
+  channels: {
+    adapters: {
+      slack: createSlackAdapter(),
+    },
+  },
+})
+```
+
+Register the controller on the Mastra instance. Mastra registers the webhook routes and initializes the channel layer:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+import { agentController } from './agent-controller'
+
+export const mastra = new Mastra({
+  agentControllers: { agentController },
+  storage: new LibSQLStore({
+    url: process.env.DATABASE_URL,
+  }),
+})
+```
+
+## Webhook routes
+
+Controller channel webhooks follow the same pattern as agent channels, under an `agent-controllers` path:
+
+```text
+/api/agent-controllers/<CONTROLLER_ID>/channels/<PLATFORM>/webhook
+```
+
+For example, a Slack adapter on a controller with the `my-agent-controller` ID uses:
+
+```text
+/api/agent-controllers/my-agent-controller/channels/slack/webhook
+```
+
+Point the platform's webhook, event, or interactions URL to this path. See [Webhook routes](https://mastra.ai/docs/capabilities/channels/overview) for local tunneling and platform setup.
+
+## One session per chat thread
+
+Each chat thread maps to one durable controller session. The first message in a Slack or Discord thread creates a Mastra thread and a controller session keyed to it; every later message in that chat thread reuses both. The session carries the active mode, model, permission grants, and state for the life of the conversation, just like a session driven from a terminal or web UI.
+
+By default the session key derives from the platform and the external thread ID (`channel:slack:<THREAD_ID>`). Pass `resolveResourceId` in the channels configuration to control the mapping yourself.
+
+Avoid mapping multiple active chat threads to one session. A session works on one Mastra thread at a time, and a message arriving from a different chat thread rebinds the session to that thread, which cancels any run still in flight on the previous one.
+
+## Tool approvals
+
+Tools that require approval render as interactive cards with Approve and Deny buttons, the same as [agent channel tool approvals](https://mastra.ai/docs/capabilities/channels/overview). The controller run pauses at the session's approval gate until a user acts on the card, then resumes and streams the continuation back to the thread.
+
+Two behaviors follow from routing approvals through the session:
+
+- A new message in the thread while an approval is pending declines that approval, the same as sending a new message in a terminal session. The new message supersedes the pending ask.
+- On adapters that can't render approval buttons (`toolDisplay: 'text'`), tools run without approval prompts so runs can't stall on a card nobody can act on.
+
+See [Tool approvals and permissions](https://mastra.ai/docs/agent-controller/tool-approvals) for policies, categories, and session grants.
+
+## Limits
+
+- Adapters can be constructed manually as shown above. The managed connect flow (`mastra.channels.slack.connect(...)`) also supports controller-owned installations — call it with an options object (`connect({ id, name })`) to connect a controller that has no registered agent. Adapters without controller support must still be constructed manually.
+- Controller sessions are in-memory objects, so channels-backed controllers need a long-lived server. Serverless deployment isn't supported for controller channels; agent channels support it as described in [Serverless deployment](https://mastra.ai/docs/capabilities/channels/overview).
+- Pending tool approvals don't survive a server restart. An approval card acted on after a restart is ignored as stale.
+- Mode switching from chat (for example, a `/mode` slash command) isn't available yet.
+
+## Related
+
+- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
+- [Session](https://mastra.ai/docs/agent-controller/session)
+- [Tool approvals and permissions](https://mastra.ai/docs/agent-controller/tool-approvals)
+- [Channels reference](https://mastra.ai/reference/agents/channels)

package/.docs/docs/capabilities/channels/overview.md

@@ -253,4 +253,5 @@ Vercel's managed Redis integration and Upstash Redis both work well. For more on
 ## Related
 
 - [Channels reference](https://mastra.ai/reference/agents/channels)
+- [AgentController channels](https://mastra.ai/docs/agent-controller/channels)
 - 📹 [Mastra channels workshop](https://www.youtube.com/watch?v=E9KFsZEnQO8\&t=5s)

package/.docs/docs/deployment/cloud-providers.md

@@ -18,5 +18,6 @@ The following guides show how to deploy Mastra to specific cloud providers:
 - [Azure App Services](https://mastra.ai/guides/deployment/azure-app-services)
 - [Cloudflare](https://mastra.ai/guides/deployment/cloudflare)
 - [Digital Ocean](https://mastra.ai/guides/deployment/digital-ocean)
+- [Kubernetes](https://mastra.ai/guides/deployment/kubernetes)
 - [Netlify](https://mastra.ai/guides/deployment/netlify)
 - [Vercel](https://mastra.ai/guides/deployment/vercel)

package/.docs/docs/deployment/overview.md

@@ -48,6 +48,7 @@ Use this option for auto-scaling, minimal infrastructure management, or when you
 - [Azure App Services](https://mastra.ai/guides/deployment/azure-app-services)
 - [Cloudflare](https://mastra.ai/guides/deployment/cloudflare)
 - [Digital Ocean](https://mastra.ai/guides/deployment/digital-ocean)
+- [Kubernetes](https://mastra.ai/guides/deployment/kubernetes)
 - [Netlify](https://mastra.ai/guides/deployment/netlify)
 - [Vercel](https://mastra.ai/guides/deployment/vercel)
 

package/.docs/docs/mastra-platform/overview.md

@@ -5,13 +5,15 @@
 The [Mastra platform](https://projects.mastra.ai) provides three products for deploying, monitoring, and managing AI applications built with the Mastra framework:
 
 - [**Observability**](https://mastra.ai/docs/mastra-platform/observability): The baseline product for every platform project, with searchable traces, logs, and metrics across Mastra projects and deploys
-- [**Studio**](https://mastra.ai/docs/mastra-platform/studio): A hosted visual environment for testing agents, running workflows, and inspecting traces. Starting with Studio also gives you Observability.
+- [**Studio**](https://mastra.ai/docs/mastra-platform/studio): A hosted visual environment for testing agents and running workflows, with tools for inspecting traces. Starting with Studio also gives you Observability.
 - [**Server**](https://mastra.ai/docs/mastra-platform/server): A production deployment target that runs your Mastra application as an API server. Starting with Server also gives you Observability.
 
 Deploy with a single command, [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy), or connect a GitHub repository for push-to-deploy. See the [GitHub integration](https://mastra.ai/docs/mastra-platform/github) for the repository-linked flow.
 
 Each project can run multiple [**Environments**](https://mastra.ai/docs/mastra-platform/environments) (for example `production` and `staging`), provision [**Hosted databases**](https://mastra.ai/docs/mastra-platform/database) from the CLI or project settings to persist application data, and get a managed [**Workspace**](https://mastra.ai/docs/mastra-platform/workspace) per environment that gives agents a filesystem and a sandbox with no manual configuration.
 
+[**Trace Intelligence**](https://mastra.ai/docs/mastra-platform/trace-intelligence) finds recurring goals, outcomes, behaviors, and sentiment across your agent traces. Trace Intelligence is available in private beta for selected projects.
+
 ## Get started
 
 Choose the path that matches what you want to do:
@@ -22,7 +24,7 @@ Choose the path that matches what you want to do:
 
 ## Key concepts
 
-**Projects** are the shared parent entity across all products. A single project can have Observability, a Studio deployment, and a Server deployment. Projects belong to an **Organization**, which is the multi-tenant container for your team.
+**Projects** are the shared parent entity across all products. A single project can include every product: Observability, Studio, and Server. Projects belong to an **Organization**, which is the multi-tenant container for your team.
 
 Your Mastra application is built from three building blocks:
 

package/.docs/docs/mastra-platform/trace-intelligence.md

@@ -0,0 +1,123 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Trace Intelligence on Mastra platform
+
+Trace Intelligence finds recurring patterns across your agent's interactions. It analyzes traces captured by Mastra Observability, produces trace signals for four dimensions, and clusters similar trace signals into themes.
+
+Use Trace Intelligence to investigate questions such as:
+
+- What are users trying to accomplish?
+- Which goals tend to succeed, remain unresolved, or become blocked?
+- Which agent behaviors appear in successful and unsuccessful interactions?
+- How does user sentiment relate to goals and outcomes?
+
+> **Private beta:** Trace Intelligence is available by invitation for selected Mastra platform projects.
+
+## Get access
+
+1. Submit the [Trace Intelligence private beta form](https://mastra.ai/trace-intelligence) to request access.
+2. Confirm that [Mastra platform Observability](https://mastra.ai/docs/mastra-platform/observability) is enabled and that completed agent traces appear under **Traces**.
+3. Requires at least `@mastra/core@1.53.0` and `mastra@1.20.2`. Upgrade your project then deploy or redeploy Studio for the enrolled project. Local Studio and server-only deployments aren't supported during the private beta.
+4. Open the deployed Studio and select **Intelligence** in the sidebar.
+5. Send representative traffic to your agent and allow time for analysis.
+
+Once Mastra enrolls the project, you don't need to change your agent definition or calls.
+
+### When data is available
+
+Trace Intelligence needs enough processed traces from one agent to identify recurring patterns. Initial themes are usually available after at least **100 completed traces** from that agent have been processed.
+
+The trace count under **Traces** can reach 100 before Trace Intelligence is ready because the analysis pipeline runs asynchronously. Processing can take several minutes after the threshold is reached. Traces that can't be analyzed don't contribute, so 100 is a minimum, not an exact UI trigger.
+
+Trace Intelligence updates automatically as more traces arrive. Studio needs themes for at least two trace signal types before it can display the relationship flow.
+
+Use representative traffic. A small set of repeated test prompts can produce unrepresentative results, such as one broad theme or mostly Noise.
+
+## Understand the analysis
+
+Each analyzable completed trace produces four trace signals:
+
+| Trace signal  | Meaning                                                                                                |
+| ------------- | ------------------------------------------------------------------------------------------------------ |
+| **Goal**      | What the user is trying to achieve or have completed.                                                  |
+| **Outcome**   | The final completed, partial, blocked, failed, unresolved, or unclear state.                           |
+| **Behavior**  | Observable agent actions and patterns, including tool use, omissions, retries, failures, and recovery. |
+| **Sentiment** | The user's emotional state or attitude.                                                                |
+
+Themes are clusters generated from similar trace signals. Clustering happens independently for each trace signal type. One trace can belong to a separate theme in every dimension: Goal, Outcome, Behavior, and Sentiment.
+
+### Themes and relationships
+
+The flow chart connects themes in adjacent trace signal columns:
+
+- A **node** represents a theme. Its count is the number of distinct traces assigned to that theme in the selected snapshot.
+- A **ribbon** connects traces assigned to themes in both adjacent columns. Its width represents the shared trace count.
+- Hover over or focus a node or ribbon to isolate its relationships.
+
+The flow shows association, not causation or execution order. For example, a ribbon between a Goal and an Outcome means that both themes occurred in the same traces. It doesn't show that the goal caused the outcome.
+
+### Distributions, Other, and Noise
+
+The cards below the flow show each trace signal's theme distribution:
+
+- **Trace count**: The number of distinct traces assigned to a theme in the selected snapshot.
+- **Stage share**: The percentage of analyzed traces for that trace signal assigned to the theme.
+
+Studio shows the most common themes for each trace signal type. It may combine smaller themes into **Other** to preserve totals without overcrowding the chart.
+
+**Noise** contains summaries that didn't consistently match a recurring theme in the selected snapshot. It doesn't necessarily indicate an error or a low-quality interaction. Noise can include rare requests and emerging patterns. It can also contain ambiguous interactions or unrelated cases. A large Noise share can indicate highly varied traffic or insufficient data for stable themes.
+
+### Snapshots
+
+A snapshot is a moving analysis window over a set of traces. Snapshots can overlap, so don't add their trace counts together. Compare trace count and stage share together because traffic volume can change between windows.
+
+A theme can persist, disappear, split, merge, or return across snapshots. Treat theme names and descriptions as generated summaries, not fixed taxonomies.
+
+## Use the Trace Intelligence page
+
+1. Use the **Agent** selector to switch between agents with available analysis. An agent doesn't appear until its first themes are ready.
+2. Select a theme in the flow to filter every column to traces containing that theme.
+3. Select **View theme details** to inspect its description, trace count, stage share, generated examples, and history.
+4. Select **Clear filter** to restore the complete flow.
+
+You can also:
+
+- Select a theme in a distribution card to open its details and generated example summaries.
+- Select **Noise** in a distribution card to inspect its distribution and generated example summaries.
+- Drag the distribution cards to reorder the trace signal columns and see a different relationship perspective.
+- Use the timeline to select a snapshot, or select **Play** to watch themes change over time.
+- Open a theme's history to see whether it persisted and how its coverage changed.
+
+Filtering the flow by a theme is unavailable for snapshots with more than 2,000 traces. Choose another snapshot or clear the active filter to return to the full flow. Theme and Noise details remain available from the distribution cards.
+
+## Troubleshooting
+
+### Intelligence isn't in the sidebar
+
+Confirm that Mastra enrolled the correct project, that you use the beta-compatible Mastra version, and that you redeployed Studio. The private beta doesn't support local Studio.
+
+### An agent is missing
+
+Confirm that its completed traces are listed under **Traces**. The agent is listed only after its first themes are ready. If it recently reached 100 traces, allow time for asynchronous processing.
+
+### The relationship flow is unavailable
+
+The flow requires themes for at least two trace signal types. Continue sending representative traffic and allow processing to finish.
+
+### Most summaries are Noise
+
+Collect more representative traffic and compare a later snapshot. Varied or rare interactions are harder to group, while repeated test prompts can produce an unrepresentative distribution.
+
+## Private-beta limitations
+
+- Trace Intelligence is available only for enrolled projects in deployed Studio.
+- Initial analysis requires at least 100 processed traces per agent. Some agents may require more.
+- Results depend on the diversity and quality of captured traces.
+- Trace signal summaries, theme labels, clustering, thresholds, and UI behavior can change during the beta.
+
+When reporting feedback, include the organization ID, project ID, agent ID, selected snapshot, and the theme or Noise examples that illustrate the issue.
+
+## Related
+
+- [Observability on Mastra platform](https://mastra.ai/docs/mastra-platform/observability)
+- [Studio on Mastra platform](https://mastra.ai/docs/mastra-platform/studio)

package/.docs/docs/rag/vector-databases.md

@@ -35,6 +35,23 @@ For detailed setup instructions and best practices, see the [official MongoDB At
 
 MongoDB works seamlessly with VoyageAI's embedding models, which are optimized for retrieval tasks. For complete examples and specialized models, see the [VoyageAI embeddings documentation](https://mastra.ai/models/embeddings) and [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb).
 
+### Hybrid Search (Vector + Full-Text)
+
+MongoDB supports hybrid search that fuses vector similarity with BM25 full-text search using server-side `$rankFusion` (requires MongoDB >= 8.0; generally available from 8.1, and enabled on Atlas 8.0.x). This is useful when you want to combine semantic and keyword-based retrieval:
+
+```ts
+await store.createSearchIndex({ indexName: 'myCollection', fields: ['text'] })
+const results = await store.hybridQuery({
+  indexName: 'myCollection',
+  queryVector: embedding,
+  query: 'search terms',
+  paths: ['text'],
+  topK: 10,
+})
+```
+
+See the [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb) for details on `createSearchIndex()`, `textQuery()`, and `hybridQuery()`.
+
 **PgVector**:
 
 ```ts

package/.docs/docs/voice/overview.md

@@ -773,6 +773,10 @@ await voiceAgent.voice.send(micStream)
 
 Visit the [xAI Realtime Voice Reference](https://mastra.ai/reference/voice/xai-realtime) for more information on the xAI voice provider.
 
+### Realtime voice
+
+Run live calls a user can talk over, in the browser or over the phone. Mastra hands the audio loop to LiveKit, which covers voice activity detection, semantic turn detection, and barge-in, while your agent generates each reply with its own model, tools, and memory. For setup and configuration options, check out [Realtime voice](https://mastra.ai/docs/voice/realtime-voice).
+
 ## Voice configuration
 
 Each voice provider can be configured with different models and options. Below are the detailed configuration options for all supported providers:
@@ -1248,5 +1252,6 @@ For more information on the CompositeVoice, refer to the [CompositeVoice Referen
 - [AWS Nova Sonic Voice](https://mastra.ai/reference/voice/aws-nova-sonic)
 - [Deepgram Voice](https://mastra.ai/reference/voice/deepgram)
 - [Inworld Voice](https://mastra.ai/reference/voice/inworld)
+- [LiveKit](https://mastra.ai/reference/voice/livekit)
 - [PlayAI Voice](https://mastra.ai/reference/voice/playai)
 - [Voice Examples](https://github.com/mastra-ai/voice-examples)

package/.docs/docs/voice/{livekit.md → realtime-voice.md}

@@ -1,10 +1,12 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Using LiveKit with Mastra
+# Realtime voice
 
-[LiveKit](https://livekit.io) is an open source WebRTC platform for realtime audio and video. The [`@mastra/livekit`](https://mastra.ai/reference/voice/livekit) package connects Mastra agents to the [LiveKit Agents framework](https://docs.livekit.io/agents/): LiveKit owns the audio loop like voice activity detection, streaming speech-to-text, semantic turn detection, barge-in, and text-to-speech. Your Mastra agent generates every reply with its own model, tools, and memory.
+Realtime voice turns a Mastra agent into a live call a user can talk over, in the browser or over the phone. Mastra builds it on [LiveKit](https://livekit.io), an open source WebRTC platform for realtime audio and video.
 
-Use this integration when you need low-latency, interruptible voice conversations. For provider-based speech-to-speech without LiveKit, see [Speech to Speech](https://mastra.ai/docs/voice/speech-to-speech).
+The [`@mastra/livekit`](https://mastra.ai/reference/voice/livekit) package connects Mastra agents to the [LiveKit Agents framework](https://docs.livekit.io/agents/): LiveKit owns the audio loop like voice activity detection, streaming speech-to-text, semantic turn detection, barge-in, and text-to-speech. Your Mastra agent generates every reply with its own model, tools, and memory.
+
+Use realtime voice when you need low-latency, interruptible voice conversations. For provider-based speech-to-speech without LiveKit, see [Speech to Speech](https://mastra.ai/docs/voice/speech-to-speech).
 
 ## Quickstart
 

package/.docs/docs/workspace/filesystem.md

@@ -29,6 +29,7 @@ Available providers:
 - [`FilesSDKFilesystem`](https://mastra.ai/reference/workspace/files-sdk-filesystem): Stores files in any [FilesSDK](https://files-sdk.dev) adapter (S3, R2, GCS, Azure Blob, Vercel Blob, local filesystem, and more) — useful when you want one provider that can target multiple backends
 - [`AgentFSFilesystem`](https://mastra.ai/reference/workspace/agentfs-filesystem): Stores files in a Turso/SQLite database via AgentFS
 - [`MesaFilesystem`](https://mastra.ai/reference/workspace/mesa-filesystem): Stores files in versioned Mesa repos
+- [`ArchilFilesystem`](https://mastra.ai/reference/workspace/archil-filesystem): Stores files on Archil elastic, serverless disks
 
 > **Tip:** `LocalFilesystem` is the simplest way to get started as it requires no external services. For cloud storage, use `S3Filesystem`, `GCSFilesystem`, or `AzureBlobFilesystem`. For versioned storage, use `MesaFilesystem`. For database-backed storage without external services, use `AgentFSFilesystem`.
 

package/.docs/docs/workspace/sandbox.md

@@ -24,10 +24,13 @@ A sandbox provider executes commands in a controlled environment:
 - [`AppleContainerSandbox`](https://mastra.ai/reference/workspace/apple-container-sandbox): Executes commands in local OCI Linux containers using Apple's `container` CLI
 - [`BlaxelSandbox`](https://mastra.ai/reference/workspace/blaxel-sandbox): Executes commands in isolated Blaxel cloud sandboxes
 - [`DaytonaSandbox`](https://mastra.ai/reference/workspace/daytona-sandbox): Executes commands in isolated Daytona cloud sandboxes
+- [`DockerSandbox`](https://mastra.ai/reference/workspace/docker-sandbox): Executes commands in long-lived Docker containers on the local machine
 - [`E2BSandbox`](https://mastra.ai/reference/workspace/e2b-sandbox): Executes commands in isolated E2B cloud sandboxes
 - [`ModalSandbox`](https://mastra.ai/reference/workspace/modal-sandbox): Executes commands in isolated Modal cloud sandboxes
 - [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox): Executes commands in a sandbox tied to a Mastra Platform environment
 - [`RailwaySandbox`](https://mastra.ai/reference/workspace/railway-sandbox): Executes commands in ephemeral, isolated Railway cloud sandboxes
+- [`VercelSandbox`](https://mastra.ai/reference/workspace/vercel-sandbox): Executes commands in an ephemeral Vercel Sandbox Firecracker MicroVM
+- [`VercelServerlessSandbox`](https://mastra.ai/reference/workspace/vercel-serverless): Executes commands as stateless Vercel serverless functions
 
 ## Basic usage
 
@@ -235,5 +238,7 @@ Use `null` or `false` for cloud sandboxes (for example, E2B, Daytona, or Modal)
 - [`E2BSandbox` reference](https://mastra.ai/reference/workspace/e2b-sandbox)
 - [`LocalSandbox` reference](https://mastra.ai/reference/workspace/local-sandbox)
 - [`ModalSandbox` reference](https://mastra.ai/reference/workspace/modal-sandbox)
+- [`VercelSandbox` reference](https://mastra.ai/reference/workspace/vercel-sandbox)
+- [`VercelServerlessSandbox` reference](https://mastra.ai/reference/workspace/vercel-serverless)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)
 - [Filesystem](https://mastra.ai/docs/workspace/filesystem)