@mastra/mcp-docs-server 1.2.17-alpha.9 → 1.2.18-alpha.1

package/.docs/course/02-agent-tools-mcp/32-conclusion.md

@@ -14,4 +14,4 @@ The power of MCP lies in its ability to connect your agent to a wide variety of
 
 As you continue to develop your Mastra agent, consider exploring other MCP servers and tools that might be useful for your specific use case. The Mastra ecosystem is constantly growing, with new tools and capabilities being added regularly.
 
-For more information on MCP and available servers, check out the [Mastra MCP documentation](https://mastra.ai/docs/mcp/overview).
+For more information on MCP and available servers, check out the [Mastra MCP documentation](https://mastra.ai/docs/connections/mcp).

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

@@ -29,7 +29,7 @@ Each turn adds the full tool response to the agent's context window which can le
 
 With code mode, your tools keep running on the host with full validation, request context, and tracing. Only the model's orchestration code runs in the sandbox. Each `external_*` call is bridged back to the real tool on the host, and the function can reduce or aggregate results before returning one response to the agent.
 
-The function runs in a [Workspace sandbox](https://mastra.ai/docs/workspace/sandbox). A sandbox is required, because code mode runs model-authored code and the execution boundary must be chosen deliberately. Pass one via `sandbox`, or run the agent in a workspace that provides one. To execute on the host machine, pass `new LocalSandbox()` explicitly. This runs the function as a host `node` process with host privileges, so only use it for trusted or local development.
+The function runs in a [Workspace sandbox](https://mastra.ai/docs/sandbox/overview). A sandbox is required, because code mode runs model-authored code and the execution boundary must be chosen deliberately. Pass one via `sandbox`, or run the agent in a workspace that provides one. To execute on the host machine, pass `new LocalSandbox()` explicitly. This runs the function as a host `node` process with host privileges, so only use it for trusted or local development.
 
 Transports that bring their own execution boundary are the exception: with [`IsolatedVmCodeModeTransport`](https://mastra.ai/reference/tools/isolated-vm-transport) the program runs in an in-process V8 isolate and no sandbox is needed (see [In-process isolation](#in-process-isolation)).
 
@@ -183,5 +183,5 @@ See [Choosing a transport](https://mastra.ai/reference/tools/quickjs-transport)
 - [createCodeMode() reference](https://mastra.ai/reference/tools/create-code-mode)
 - [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport)
 - [QuickJsCodeModeTransport reference](https://mastra.ai/reference/tools/quickjs-transport)
-- [Tools](https://mastra.ai/docs/agents/using-tools)
-- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [Tools](https://mastra.ai/docs/agents/tools)
+- [Sandbox](https://mastra.ai/docs/sandbox/overview)

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

@@ -130,7 +130,7 @@ const scrubbedAgent = new Agent({
 
 Visit [`SystemPromptScrubber()`](https://mastra.ai/reference/processors/system-prompt-scrubber) reference for a full list of configuration options.
 
-> **Note:** When streaming responses over HTTP, Mastra redacts sensitive request data (system prompts, tool definitions, API keys) from stream chunks at the server level by default. See [Stream data redaction](https://mastra.ai/docs/server/mastra-server) for details.
+> **Note:** When streaming responses over HTTP, Mastra redacts sensitive request data (system prompts, tool definitions, API keys) from stream chunks at the server level by default. See [Stream data redaction](https://mastra.ai/docs/server/overview) for details.
 
 ## Hybrid processors
 

package/.docs/docs/agents/{agent-approval.md → human-in-the-loop.md}

@@ -48,7 +48,7 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
-> **Note:** Human-in-the-loop uses snapshots to capture request state. Configure a [storage provider](https://mastra.ai/docs/storage/overview) on your Mastra instance or you'll see a "snapshot not found" error.
+> **Note:** Human-in-the-loop uses snapshots to capture request state. Configure a [storage provider](https://mastra.ai/docs/storage) on your Mastra instance or you'll see a "snapshot not found" error.
 >
 > Snapshots for agent runs are minimal resume artifacts: they hold only what's needed to resume the suspended run and are deleted once the run finishes. Use [tracing](https://mastra.ai/docs/observability/overview) for the execution record and [memory](https://mastra.ai/docs/memory/overview) for the conversation history.
 
@@ -510,11 +510,11 @@ Each returned run includes the suspended tool calls (`toolCallId`, `toolName`, `
 
 The same discovery is available over HTTP as `GET /agents/:agentId/suspended-runs` and in the client SDK as [`agent.listSuspendedRuns()`](https://mastra.ai/reference/client-js/agents), so browser-based approval UIs can rediscover pending runs directly.
 
-> **Note:** Suspended runs only survive restarts when your Mastra instance is configured with a persistent [storage provider](https://mastra.ai/docs/storage/overview). The default in-memory store loses snapshots when the process exits.
+> **Note:** Suspended runs only survive restarts when your Mastra instance is configured with a persistent [storage provider](https://mastra.ai/docs/storage). The default in-memory store loses snapshots when the process exits.
 
 ## Tool approval: Supervisor agents
 
-A [supervisor agent](https://mastra.ai/docs/capabilities/subagents) coordinates multiple subagents using `.stream()` or `.generate()`. When a subagent calls a tool that requires approval, the request propagates up through the delegation chain and surfaces at the supervisor level:
+A [supervisor agent](https://mastra.ai/docs/subagents) coordinates multiple subagents using `.stream()` or `.generate()`. When a subagent calls a tool that requires approval, the request propagates up through the delegation chain and surfaces at the supervisor level:
 
 1. The supervisor delegates a task to a subagent.
 2. The subagent calls a tool that has `requireApproval: true` or uses `suspend()`.
@@ -673,8 +673,8 @@ if (output.finishReason === 'suspended') {
 
 ## Related
 
-- [Tools](https://mastra.ai/docs/agents/using-tools)
+- [Tools](https://mastra.ai/docs/agents/tools)
 - [Agent overview](https://mastra.ai/docs/agents/overview)
-- [MCP overview](https://mastra.ai/docs/mcp/overview)
+- [MCP overview](https://mastra.ai/docs/connections/mcp)
 - [Memory](https://mastra.ai/docs/memory/overview)
 - [Request context](https://mastra.ai/docs/server/request-context)

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

@@ -2,7 +2,7 @@
 
 # Agent networks
 
-> **Deprecated:** Agent networks are deprecated and will be removed in a future major release. [Supervisor agents](https://mastra.ai/docs/capabilities/subagents) using `agent.stream()` or `agent.generate()` are now the recommended approach. It provides the same multi-agent coordination with better control, a simpler API, and easier debugging.
+> **Deprecated:** Agent networks are deprecated and will be removed in a future major release. [Supervisor agents](https://mastra.ai/docs/subagents) using `agent.stream()` or `agent.generate()` are now the recommended approach. It provides the same multi-agent coordination with better control, a simpler API, and easier debugging.
 >
 > See the [migration guide](https://mastra.ai/reference/migrations/network-to-supervisor) to upgrade.
 
@@ -95,7 +95,7 @@ console.log(final?.summary)
 
 When a primitive requires approval, the stream emits an `agent-execution-approval` or `tool-execution-approval` chunk. Use `approveNetworkToolCall()` or `declineNetworkToolCall()` to respond.
 
-Network approval uses snapshots to capture execution state. Ensure a [storage provider](https://mastra.ai/docs/storage/overview) is enabled in your Mastra instance.
+Network approval uses snapshots to capture execution state. Ensure a [storage provider](https://mastra.ai/docs/storage) is enabled in your Mastra instance.
 
 ```typescript
 const stream = await routingAgent.network('Perform some sensitive action', {
@@ -180,5 +180,5 @@ Requirements for automatic resumption:
 
 ## Related
 
-- [Supervisor agents](https://mastra.ai/docs/capabilities/subagents)
+- [Supervisor agents](https://mastra.ai/docs/subagents)
 - [Migration: `.network()` to supervisor agents](https://mastra.ai/reference/migrations/network-to-supervisor)

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

@@ -165,7 +165,7 @@ Visit the [agent reference](https://mastra.ai/reference/agents/agent) for more i
 
 ## Use your agent
 
-After registration, retrieve your agent with [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById). Call `.generate()` for a complete response or `.stream()` to deliver tokens in real time. You can call agents from [workflow steps](https://mastra.ai/docs/workflows/agents-and-tools), [tools](https://mastra.ai/docs/agents/using-tools), the [Mastra Client](https://mastra.ai/reference/client-js/mastra-client), route handlers, [server adapters](https://mastra.ai/docs/server/server-adapters), or the command line. See [Integrations](https://mastra.ai/integrations) to use agents in your application framework.
+After registration, retrieve your agent with [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById). Call `.generate()` for a complete response or `.stream()` to deliver tokens in real time. You can call agents from [workflow steps](https://mastra.ai/docs/workflows/agents-and-tools), [tools](https://mastra.ai/docs/agents/tools), the [Mastra Client](https://mastra.ai/reference/client-js/mastra-client), route handlers, [server adapters](https://mastra.ai/docs/server/server-adapters), or the command line. See [Integrations](https://mastra.ai/integrations) to use agents in your application framework.
 
 When referencing an agent from your Mastra instance, use `mastra.getAgentById()` to ensure it has access to shared services such as instance-level storage, logging, and agent registry. A directly imported agent can still work with its own local configuration, but it won't have access to those shared services.
 
@@ -202,18 +202,18 @@ Once your agent is running, use this table to find the right page for what you w
 
 | Goal                                                           | Start here                                                             |
 | -------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| Give your agent tools to call external APIs or services        | [Tools](https://mastra.ai/docs/agents/using-tools)                     |
+| Give your agent tools to call external APIs or services        | [Tools](https://mastra.ai/docs/agents/tools)                           |
 | Keep context and preferences across conversations              | [Memory](https://mastra.ai/docs/memory/overview)                       |
 | Get typed objects back instead of plain text                   | [Structured output](https://mastra.ai/docs/agents/structured-output)   |
-| Human-in-the-loop: Pause execution and wait for human approval | [Human-in-the-loop](https://mastra.ai/docs/agents/agent-approval)      |
-| Build a multi-agent network                                    | [Supervisor agents](https://mastra.ai/docs/capabilities/subagents)     |
-| Register subagents                                             | [Tools](https://mastra.ai/docs/agents/using-tools)                     |
+| Human-in-the-loop: Pause execution and wait for human approval | [Human-in-the-loop](https://mastra.ai/docs/agents/human-in-the-loop)   |
+| Build a multi-agent network                                    | [Supervisor agents](https://mastra.ai/docs/subagents)                  |
+| Register subagents                                             | [Tools](https://mastra.ai/docs/agents/tools)                           |
 | Intercept or transform messages before and after generation    | [Processors](https://mastra.ai/docs/agents/processors)                 |
 | Keep your agent safe                                           | [Guardrails](https://mastra.ai/docs/agents/guardrails)                 |
-| Build agents that correct their work                           | [Rubric scorer](https://mastra.ai/docs/capabilities/subagents)         |
+| Build agents that correct their work                           | [Rubric scorer](https://mastra.ai/docs/subagents)                      |
 | Swap instructions or models based on request context           | [Dynamic configuration](https://mastra.ai/docs/server/request-context) |
 | Add speech-to-text or text-to-speech                           | [Voice](https://mastra.ai/reference/voice/overview)                    |
-| Connect to Slack, Discord, or Telegram                         | [Channels](https://mastra.ai/docs/capabilities/channels)               |
+| Connect to Slack, Discord, or Telegram                         | [Channels](https://mastra.ai/docs/channels)                            |
 
 ## Multi-agent systems
 

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

@@ -398,7 +398,7 @@ See the [`TokenLimiterProcessor` reference](https://mastra.ai/reference/processo
 
 Removes tool calls and results from messages sent to the LLM, saving tokens on verbose tool interactions. Optionally exclude only specific tools. This filter only affects the LLM input, filtered messages are still saved to memory.
 
-By default, `ToolCallFilter` filters the initial input before the agent loop starts. Use `filterAfterToolSteps` to also filter during each loop step while preserving recent tool-producing steps.
+By default, `ToolCallFilter` filters tool calls from prior history and leaves tool calls made during the current agent loop in place. Use `filterAfterToolSteps` to also filter during the loop while preserving the most recent tool-producing steps.
 
 ```typescript
 new ToolCallFilter({
@@ -426,7 +426,7 @@ See the [`ToolSearchProcessor` reference](https://mastra.ai/reference/processors
 
 Handles provider-specific history incompatibilities when agents reuse messages across model providers. It can rewrite the outbound LLM request before the provider call, or recover from known provider API errors and retry.
 
-Add `ProviderHistoryCompat` explicitly when you need provider history compatibility rules, reactive API error recovery, custom compatibility rules, or predictable processor ordering.
+Add `ProviderHistoryCompat` explicitly when you need provider history compatibility rules, reactive API error recovery, custom compatibility rules, or predictable processor ordering. For Azure OpenAI agents that use observational memory, the processor rewrites `<system-reminder>` wrappers in outbound prompts to avoid content moderation refusals. Stored history remains unchanged.
 
 See the [`ProviderHistoryCompat` reference](https://mastra.ai/reference/processors/provider-history-compat) for setup, built-in rules, and custom rule options.
 
@@ -640,7 +640,7 @@ Do not mention the reminder to the user or quote the tags back to them.`,
 await agent.generate('Your prompt', { maxSteps: MAX_STEPS })
 ```
 
-> **Note:** Reactive signals default to `tagName: 'system-reminder'`. Visit [Signals](https://mastra.ai/docs/long-running-agents/signals) for more on processor-emitted signals.
+> **Note:** Reactive signals default to `tagName: 'system-reminder'`. Visit [Signals](https://mastra.ai/docs/harness/signals) for more on processor-emitted signals.
 
 ### Deliver a reminder without retaining it
 

package/.docs/docs/agents/{using-tools.md → tools.md}

@@ -2,7 +2,7 @@
 
 # Tools
 
-Agents use tools to call APIs or query databases. They can also run custom functions from your codebase. Tools give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](https://mastra.ai/docs/mcp/overview) to expand an agent's capabilities.
+Agents use tools to call APIs or query databases. They can also run custom functions from your codebase. Tools give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](https://mastra.ai/docs/connections/mcp) to expand an agent's capabilities.
 
 **For AI agents:** Run `npx mastra api tool execute weather-tool '{"location":"San Francisco"}'` to test this tool directly instead of writing a temporary script. The command requires a running Mastra server; start the local server with `npx mastra dev`, or pass the reachable server's base URL with `--url`. Run `npx mastra api tool execute --schema` before constructing different input. Install Mastra's skill with `npx skills add mastra-ai/skills --skill mastra` for complete API CLI discovery, targeting, schema, authentication, and error-handling guidance.
 
@@ -166,7 +166,7 @@ export const weatherAgent = new Agent({
 
 ## Agents as tools
 
-Add subagents through the `agents` configuration to create a [supervisor](https://mastra.ai/docs/capabilities/subagents). Mastra converts each subagent to an `agent-<key>` tool. Include a `description` on each subagent so the supervisor knows when to delegate.
+Add subagents through the `agents` configuration to create a [supervisor](https://mastra.ai/docs/subagents). Mastra converts each subagent to an `agent-<key>` tool. Include a `description` on each subagent so the supervisor knows when to delegate.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -605,7 +605,7 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
-`askUserTool` supports free-text, single-select (`options` array), and multi-select (`selectionMode: 'multi_select'`) prompts. Pair it with `autoResumeSuspendedTools` so the agent resumes automatically from the user's next chat message. See [Automatic tool resumption](https://mastra.ai/docs/agents/agent-approval) for details.
+`askUserTool` supports free-text, single-select (`options` array), and multi-select (`selectionMode: 'multi_select'`) prompts. Pair it with `autoResumeSuspendedTools` so the agent resumes automatically from the user's next chat message. See [Automatic tool resumption](https://mastra.ai/docs/agents/human-in-the-loop) for details.
 
 ### Submit a plan for review
 
@@ -643,7 +643,7 @@ const agent = new Agent({
 })
 ```
 
-Only one task can be `in_progress` at a time. The list is stored in the thread-scoped `threadState` storage domain and projected onto the agent's [state-signal](https://mastra.ai/docs/long-running-agents/signals) lane, so it survives observational-memory truncation. See the [Task tools reference](https://mastra.ai/reference/tools/task-tools) for full schemas.
+Only one task can be `in_progress` at a time. The list is stored in the thread-scoped `threadState` storage domain and projected onto the agent's [state-signal](https://mastra.ai/docs/harness/signals) lane, so it survives observational-memory truncation. See the [Task tools reference](https://mastra.ai/reference/tools/task-tools) for full schemas.
 
 The [AgentController](https://mastra.ai/docs/harness/agent-controller) automatically includes all built-in tools in every mode, you don't need to add them manually. See [Tool approvals](https://mastra.ai/docs/harness/agent-controller) for AgentController-specific behavior.
 
@@ -651,11 +651,11 @@ The [AgentController](https://mastra.ai/docs/harness/agent-controller) automatic
 
 - [`createTool` reference](https://mastra.ai/reference/tools/create-tool)
 - [`Agent.generate()` reference](https://mastra.ai/reference/agents/generate): Runtime options for tool selection, steps, and callbacks
-- [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks): Run long-running tools without blocking the agent loop
-- [MCP overview](https://mastra.ai/docs/mcp/overview)
+- [Background tasks](https://mastra.ai/docs/harness/background-tasks): Run long-running tools without blocking the agent loop
+- [MCP overview](https://mastra.ai/docs/connections/mcp)
 - [Dynamic tool search](https://mastra.ai/reference/processors/tool-search-processor): Load tools on demand for agents with large tool libraries
 - [Tools with structured output](https://mastra.ai/docs/agents/structured-output): Model compatibility when combining tools and structured output
-- [Agent approval](https://mastra.ai/docs/agents/agent-approval)
+- [Agent approval](https://mastra.ai/docs/agents/human-in-the-loop)
 - [`askUserTool` reference](https://mastra.ai/reference/tools/ask-user-tool)
 - [`submitPlanTool` reference](https://mastra.ai/reference/tools/submit-plan-tool)
 - [Task tools reference](https://mastra.ai/reference/tools/task-tools)

package/.docs/docs/{server/auth → auth}/custom-auth-provider.md

@@ -509,5 +509,5 @@ See the [source code](https://github.com/mastra-ai/mastra/tree/main/auth) for im
 
 ## Related
 
-- [Auth Overview](https://mastra.ai/docs/server/auth): Authentication concepts and configuration
+- [Auth Overview](https://mastra.ai/docs/auth/overview): Authentication concepts and configuration
 - [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes): Controlling authentication on custom endpoints

package/.docs/docs/{server/auth → auth}/fga.md

@@ -284,6 +284,32 @@ class MyFGAProvider implements IFGAProvider {
 }
 ```
 
+### Propagating an actor into workflow steps
+
+A workflow run's `actor` reaches each step's execute context, but it isn't passed to the agent and tool calls that step makes. Steps that call an agent without an `actor` fall back to user membership resolution, which fails on system runs that have no user.
+
+Set `propagate: true` on the actor to have the framework forward it into the agent and tool calls it makes for declarative `.then(agent)` and `.then(tool)` steps in the run:
+
+```typescript
+await run.start({
+  inputData: { city: 'London' },
+  actor: { actorKind: 'system', sourceWorkflow: 'nightly-report', propagate: true },
+})
+```
+
+Propagation is opt-in and deliberately narrow:
+
+- The `true` shorthand never propagates. Use the object form to opt in.
+- Custom step `execute` functions are never covered. Read `actor` from the step context and pass it explicitly, so a step that acts on a user's behalf can't silently inherit system trust.
+- Pass `actor` when creating the step to override the run actor for that step, including `actor: undefined` to drop back to user authorization mid-run.
+
+```typescript
+// Runs as the system actor even though it loads user-supplied data.
+workflow.then(createStep(reportAgent))
+// Explicitly runs as the user instead.
+workflow.then(createStep(summaryAgent, { actor: undefined }))
+```
+
 ### Trust requirements
 
 The actor signal is trusted input, so construct it server-side:
@@ -299,5 +325,5 @@ The actor signal is trusted input, so construct it server-side:
 ## Related
 
 - [`IFGAProvider` reference](https://mastra.ai/reference/auth/fga)
-- [Authentication overview](https://mastra.ai/docs/server/auth)
+- [Authentication overview](https://mastra.ai/docs/auth/overview)
 - [WorkOS authentication](https://mastra.ai/integrations/auth/workos)

package/.docs/docs/{server/auth.md → auth/overview.md}

@@ -25,8 +25,8 @@ See [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes) for con
 
 ### Built-in
 
-- [Simple Auth](https://mastra.ai/docs/server/auth/simple-auth)
-- [JSON Web Token](https://mastra.ai/docs/server/auth/jwt)
+- [Simple Auth](https://mastra.ai/docs/auth/simple-auth)
+- [JSON Web Token](https://mastra.ai/docs/auth/jwt)
 
 ### Third-party integrations
 
@@ -41,5 +41,5 @@ See [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes) for con
 
 ### Advanced
 
-- [Composite Auth](https://mastra.ai/docs/server/auth/composite-auth)
-- [Custom Provider](https://mastra.ai/docs/server/auth/custom-auth-provider)
+- [Composite Auth](https://mastra.ai/docs/auth/composite-auth)
+- [Custom Provider](https://mastra.ai/docs/auth/custom-auth-provider)

package/.docs/docs/{server/auth → auth}/simple-auth.md

@@ -171,4 +171,4 @@ SimpleAuth is designed for simplicity, not production security:
 - No cryptographic verification
 - All tokens must be known at startup
 
-For production applications, consider using [JWT](https://mastra.ai/docs/server/auth/jwt), [Clerk](https://mastra.ai/integrations/auth/clerk), [Auth0](https://mastra.ai/integrations/auth/auth0), or another identity provider.
+For production applications, consider using [JWT](https://mastra.ai/docs/auth/jwt), [Clerk](https://mastra.ai/integrations/auth/clerk), [Auth0](https://mastra.ai/integrations/auth/auth0), or another identity provider.

package/.docs/docs/{server/auth → auth}/workers.md

@@ -130,8 +130,8 @@ Your auth provider's `authenticateToken` callback must recognize whatever creden
 
 ## Related
 
-- [Auth overview](https://mastra.ai/docs/server/auth): Available auth providers and how they work
-- [Token-based auth](https://mastra.ai/docs/server/auth/simple-auth): Token-to-user mapping authentication
+- [Auth overview](https://mastra.ai/docs/auth/overview): Available auth providers and how they work
+- [Token-based auth](https://mastra.ai/docs/auth/simple-auth): Token-to-user mapping authentication
 - [Worker deployment](https://mastra.ai/docs/deployment/workers): Set up split worker processes
 - [Workers reference](https://mastra.ai/reference/workers/overview): Configuration details for all worker types
 - [CLI reference](https://mastra.ai/reference/cli/mastra): `mastra worker build` and `mastra worker start`

package/.docs/docs/{capabilities/channels.md → channels.md}

@@ -50,7 +50,7 @@ export const yourAgent = new Agent({
 
 > **Note:** Channel adapters require provider-specific environment variables for credentials and request verification, such as bot tokens, signing secrets, app IDs, and webhook verification tokens. Check the guide for your platform or the [Chat SDK adapter catalog](https://chat-sdk.dev/adapters) for the exact variable names.
 
-We recommend configuring [storage](https://mastra.ai/docs/storage/overview) for channels. Storage lets Mastra persist channel state, thread subscriptions, tool approvals, and memory across restarts:
+We recommend configuring [storage](https://mastra.ai/docs/storage) for channels. Storage lets Mastra persist channel state, thread subscriptions, tool approvals, and memory across restarts:
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -284,7 +284,7 @@ Vercel and AWS Lambda require `waitUntil`, since they freeze the function as soo
 
 ### Coordinate instances with a shared pub/sub
 
-Channels route messages through the agent's [signal pipeline](https://mastra.ai/docs/long-running-agents/signals), and each run acquires a lease on its thread so one run owns the conversation at a time.
+Channels route messages through the agent's [signal pipeline](https://mastra.ai/docs/harness/signals), and each run acquires a lease on its thread so one run owns the conversation at a time.
 
 The default in-memory pub/sub can't cross instance boundaries, so on serverless a follow-up message can be routed to a different instance than the one running the agent.
 

package/.docs/docs/{agents → connections}/a2a.md

@@ -80,7 +80,7 @@ Use `A2AAgent` when another Mastra agent should delegate work to a remote agent.
 
 ## Consume A2A agents as subagents
 
-Use `A2AAgent` to wrap a remote A2A agent, then add it to a parent agent with the [supervisor agents](https://mastra.ai/docs/capabilities/subagents) pattern. Pass an explicit agent card URL when the remote server hosts multiple agents or uses a custom well-known path.
+Use `A2AAgent` to wrap a remote A2A agent, then add it to a parent agent with the [supervisor agents](https://mastra.ai/docs/subagents) pattern. Pass an explicit agent card URL when the remote server hosts multiple agents or uses a custom well-known path.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -221,7 +221,7 @@ A2A models human-in-the-loop (HITL) work with the `input-required` task state. W
 
 Mastra maps its agent suspension model to this state in both directions:
 
-- **As a server**: when an exposed agent suspends, the task transitions to `input-required`. This includes suspensions caused by [tool approval](https://mastra.ai/docs/agents/agent-approval) or a tool that calls `suspend()`. The task status message includes a text prompt and a data part with the structured `suspendPayload` and `resumeSchema`. A follow-up `message/send` or `message/stream` request with the same `taskId` resumes the suspended run with the provided input.
+- **As a server**: when an exposed agent suspends, the task transitions to `input-required`. This includes suspensions caused by [tool approval](https://mastra.ai/docs/agents/human-in-the-loop) or a tool that calls `suspend()`. The task status message includes a text prompt and a data part with the structured `suspendPayload` and `resumeSchema`. A follow-up `message/send` or `message/stream` request with the same `taskId` resumes the suspended run with the provided input.
 - **As a client**: when a remote task reaches `input-required` or `auth-required`, `A2AAgent` returns a suspended result with `finishReason: 'suspended'` and a `suspendPayload`. Calling `resumeGenerate()` or `resumeStream()` sends the input or credentials back to the remote task with the original `taskId`.
 
 ```typescript

package/.docs/docs/{agents → connections}/acp.md

@@ -4,7 +4,7 @@
 
 Mastra supports the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/overview/introduction) for running ACP-compatible coding agents from a Mastra agent. Use `@mastra/acp` to wrap a coding agent process as a Mastra tool or as a subagent.
 
-ACP is useful for coding agents such as Claude Code, Amp, Codex, or any other executable that implements ACP over standard input and output.
+ACP is useful for coding agents such as Claude Code, Cline, OpenCode, Amp, Codex, or any other executable that implements ACP over standard input and output.
 
 ## When to use ACP
 
@@ -30,6 +30,18 @@ The flow is:
 
 During execution, the ACP client also handles permission requests and file operations. File reads and writes go through Mastra's `Workspace`, so the ACP agent operates inside the workspace you provide.
 
+## Compatible agents
+
+Any executable that implements ACP over standard input and output works with `@mastra/acp`. You don't need a dedicated Mastra package for each agent. Install the agent, then pass its launch command through `command` and `args`.
+
+| Agent      | `command`  | `args`      |
+| ---------- | ---------- | ----------- |
+| Cline      | `cline`    | `['--acp']` |
+| OpenCode   | `opencode` | `['acp']`   |
+| Gemini CLI | `gemini`   | `['--acp']` |
+
+Each agent documents its own ACP mode, and launch flags change between releases. Check the agent's documentation for the current command, such as [Cline ACP](https://docs.cline.bot/usage/acp) or [OpenCode ACP](https://opencode.ai/docs/acp/).
+
 ## Getting started
 
 Install `@mastra/acp` in a project that already uses `@mastra/core`. The package requires `@mastra/core` version `1.34.0` or later.
@@ -75,8 +87,8 @@ const codeAgent = new AcpAgent({
   id: 'code-agent',
   name: 'Code Agent',
   description: 'An ACP-compatible coding agent that can inspect and edit files',
-  command: 'acp-agent',
-  args: ['--stdio'],
+  command: 'opencode',
+  args: ['acp'],
   cwd: process.cwd(),
 })
 
@@ -104,8 +116,8 @@ import { Agent } from '@mastra/core/agent'
 const codeAgentTool = createACPTool({
   id: 'code-agent',
   description: 'Use an ACP-compatible coding agent to inspect and edit code',
-  command: 'acp-agent',
-  args: ['--stdio'],
+  command: 'opencode',
+  args: ['acp'],
   cwd: process.cwd(),
 })
 
@@ -151,6 +163,6 @@ See the [AcpAgent workspace integration](https://mastra.ai/reference/acp/acp-age
 - [AcpAgent reference](https://mastra.ai/reference/acp/acp-agent)
 - [createACPTool() reference](https://mastra.ai/reference/acp/create-acp-tool)
 - [Agent reference](https://mastra.ai/reference/agents/agent)
-- [Subagents](https://mastra.ai/docs/capabilities/subagents)
+- [Subagents](https://mastra.ai/docs/subagents)
 - [Agent Client Protocol introduction](https://agentclientprotocol.com/overview/introduction)
 - [Agent Client Protocol schema](https://agentclientprotocol.com/protocol/schema)

package/.docs/docs/{mcp/overview.md → connections/mcp.md}

@@ -406,7 +406,7 @@ App iframes allow scripts, forms, and popups. They can't access the parent page'
 
 ## Next steps
 
-- [Use tools with agents](https://mastra.ai/docs/agents/using-tools)
+- [Use tools with agents](https://mastra.ai/docs/agents/tools)
 - [`MCPClient` reference](https://mastra.ai/reference/tools/mcp-client)
 - [`MCPServer` reference](https://mastra.ai/reference/tools/mcp-server)
 - [MCP Apps extension specification](https://github.com/modelcontextprotocol/ext-apps)

package/.docs/docs/connections/overview.md

@@ -4,10 +4,10 @@
 
 Connections let Mastra work with remote agents, coding agents, provider software development kit (SDK) runtimes, and external tools and resources. Choose a connection type based on which system owns the agent runtime and what you need to exchange.
 
-- [**Agent-to-Agent (A2A)**](https://mastra.ai/docs/agents/a2a): Expose or consume remote agents across service, framework, vendor, and language boundaries.
-- [**Agent Client Protocol (ACP)**](https://mastra.ai/docs/agents/acp): Run compatible coding-agent processes as Mastra tools or subagents.
-- [**SDK agents**](https://mastra.ai/docs/agents/sdk-agents): Register Claude, Cursor, or OpenAI SDK-backed agents while the provider SDK retains control of the runtime, tools, permissions, and agent loop.
-- [**Model Context Protocol (MCP)**](https://mastra.ai/docs/mcp/overview): Connect agents to external tools and resources, or expose Mastra agents, tools, workflows, prompts, and resources to MCP-compatible systems.
+- [**Model Context Protocol (MCP)**](https://mastra.ai/docs/connections/mcp): Connect agents to external tools and resources, or expose Mastra agents, tools, workflows, prompts, and resources to MCP-compatible systems.
+- [**Agent-to-Agent (A2A)**](https://mastra.ai/docs/connections/a2a): Expose or consume remote agents across service, framework, vendor, and language boundaries.
+- [**Agent Client Protocol (ACP)**](https://mastra.ai/docs/connections/acp): Run compatible coding-agent processes, such as Claude Code, Cline, or OpenCode, as Mastra tools or subagents.
+- [**SDK agents**](https://mastra.ai/docs/connections/sdk-agents): Register Claude, Cursor, or OpenAI SDK-backed agents while the provider SDK retains control of the runtime, tools, permissions, and agent loop.
 
 ## When to use connections
 
@@ -20,7 +20,7 @@ Use connections when you need to:
 
 ## Get started
 
-Start with the boundary you need to cross. Use [A2A](https://mastra.ai/docs/agents/a2a) for remote agent endpoints, [ACP](https://mastra.ai/docs/agents/acp) for coding-agent processes, [SDK agents](https://mastra.ai/docs/agents/sdk-agents) for provider-owned runtimes, or [MCP](https://mastra.ai/docs/mcp/overview) for tools and resources.
+Start with the boundary you need to cross. Use [A2A](https://mastra.ai/docs/connections/a2a) for remote agent endpoints, [ACP](https://mastra.ai/docs/connections/acp) for coding-agent processes, [SDK agents](https://mastra.ai/docs/connections/sdk-agents) for provider-owned runtimes, or [MCP](https://mastra.ai/docs/connections/mcp) for tools and resources.
 
 **A2A**:
 

package/.docs/docs/{agents → connections}/sdk-agents.md

@@ -17,6 +17,8 @@ SDK agents let you use other agent SDK frameworks inside Mastra. Use them to reg
 - [Cursor Agent SDK](#cursor-agent-sdk): Use `@mastra/cursor` to register a Cursor SDK agent and call it with Mastra `generate()` and `stream()`.
 - [OpenAI Agents SDK](#openai-agents-sdk): Use `@mastra/openai` to register an OpenAI SDK agent and call it with Mastra `generate()` and `stream()`.
 
+Coding agents without a dedicated Mastra package, such as Cline and OpenCode, run through the [Agent Client Protocol](https://mastra.ai/docs/connections/acp) instead.
+
 ## Claude Agent SDK
 
 Use `@mastra/claude` for Claude Code runtime configuration, permissions, tools, and agent-loop behavior.
@@ -423,5 +425,5 @@ For storage and dashboard setup, see [Observability](https://mastra.ai/docs/obse
 ## Related
 
 - [Agents overview](https://mastra.ai/docs/agents/overview)
-- [Tools](https://mastra.ai/docs/agents/using-tools)
+- [Tools](https://mastra.ai/docs/agents/tools)
 - [Observability](https://mastra.ai/docs/observability/overview)

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

@@ -21,5 +21,6 @@ The following pages show you how to deploy Mastra to specific cloud providers.
 - [Inngest](https://mastra.ai/integrations/deploy/inngest)
 - [Kubernetes](https://mastra.ai/integrations/deploy/kubernetes)
 - [Netlify](https://mastra.ai/integrations/deploy/netlify)
+- [Render](https://mastra.ai/integrations/deploy/render)
 - [Temporal](https://mastra.ai/integrations/deploy/temporal)
 - [Vercel](https://mastra.ai/integrations/deploy/vercel)

package/.docs/docs/deployment/mastra-server.md

@@ -102,7 +102,7 @@ If a `public` folder exists in your Mastra directory (`src/mastra/public`), its
 
 ### Mastra configuration
 
-The build process respects configuration in your Mastra instance. For server behavior like CORS, timeouts, and middleware, see [server overview](https://mastra.ai/docs/server/mastra-server). For all available options, see the [configuration reference](https://mastra.ai/reference/configuration).
+The build process respects configuration in your Mastra instance. For server behavior like CORS, timeouts, and middleware, see [server overview](https://mastra.ai/docs/server/overview). For all available options, see the [configuration reference](https://mastra.ai/reference/configuration).
 
 ## Build process
 
@@ -151,7 +151,7 @@ NODE_OPTIONS="--max-old-space-size=4096" mastra build
 
 ## Related
 
-- [Server Overview](https://mastra.ai/docs/server/mastra-server): Configure server behavior, middleware, and authentication
+- [Server Overview](https://mastra.ai/docs/server/overview): Configure server behavior, middleware, and authentication
 - [Server Adapters](https://mastra.ai/docs/server/server-adapters): Use Express or Hono instead of `mastra build`
 - [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes): Add custom HTTP endpoints
 - [Configuration Reference](https://mastra.ai/reference/configuration): Full configuration options

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

@@ -17,7 +17,7 @@ Mastra can run against any of these runtime environments:
 
 ### Mastra server
 
-Mastra provides a [server](https://mastra.ai/docs/server/mastra-server) powered by Hono that can be deployed independently. Use the `mastra build` command to build your application and deploy the output to your preferred VM, container, or PaaS platform.
+Mastra provides a [server](https://mastra.ai/docs/server/overview) powered by Hono that can be deployed independently. Use the `mastra build` command to build your application and deploy the output to your preferred VM, container, or PaaS platform.
 
 Use this option when you need full control over your infrastructure, long-running processes, or WebSocket connections. The [Mastra server deployment guide](https://mastra.ai/docs/deployment/mastra-server) provides more details.
 
@@ -52,6 +52,7 @@ Use this option for auto-scaling, minimal infrastructure management, or when you
 - [Inngest](https://mastra.ai/integrations/deploy/inngest)
 - [Kubernetes](https://mastra.ai/integrations/deploy/kubernetes)
 - [Netlify](https://mastra.ai/integrations/deploy/netlify)
+- [Render](https://mastra.ai/integrations/deploy/render)
 - [Temporal](https://mastra.ai/integrations/deploy/temporal)
 - [Vercel](https://mastra.ai/integrations/deploy/vercel)
 

package/.docs/docs/deployment/sandbox.md

@@ -362,12 +362,12 @@ jobs:
 
 ## Security
 
-- The sandbox URL is public. Anyone with the URL can reach your Mastra server, including Studio. Enable [server auth](https://mastra.ai/docs/server/auth) for anything beyond throwaway previews.
+- The sandbox URL is public. Anyone with the URL can reach your Mastra server, including Studio. Enable [server auth](https://mastra.ai/docs/auth/overview) for anything beyond throwaway previews.
 - Environment variables from your `.env` files are injected into the remote sandbox VM so the server can run. The deploy logs a warning when this happens. Don't deploy secrets you wouldn't put on a shared preview server.
-- To restrict access to Tier 3 traffic, pass a `secret` to `createSandboxHandler()` or `createSandboxProxy()`. The helpers attach it as the `x-mastra-sandbox-secret` header on forwarded requests. Configure [server auth](https://mastra.ai/docs/server/auth) to require that header, and direct hits to the sandbox URL get rejected while traffic through your domain works.
+- To restrict access to Tier 3 traffic, pass a `secret` to `createSandboxHandler()` or `createSandboxProxy()`. The helpers attach it as the `x-mastra-sandbox-secret` header on forwarded requests. Configure [server auth](https://mastra.ai/docs/auth/overview) to require that header, and direct hits to the sandbox URL get rejected while traffic through your domain works.
 
 ## Related
 
 - [Deployment overview](https://mastra.ai/docs/deployment/overview)
-- [Server authentication](https://mastra.ai/docs/server/auth)
+- [Server authentication](https://mastra.ai/docs/auth/overview)
 - [`WorkspaceSandbox` reference](https://mastra.ai/reference/workspace/sandbox)

package/.docs/docs/deployment/workers.md

@@ -339,7 +339,7 @@ MASTRA_STEP_EXECUTION_URL=http://api:4111/api
 
 Without this variable, the orchestration worker attempts to execute steps in its own process, which doesn't have access to the full Mastra runtime in a split deployment.
 
-The endpoint uses the server's normal auth pipeline. If the API has an auth provider, set `MASTRA_WORKER_AUTH_TOKEN` to a bearer token that provider accepts. Mastra forwards the value as an `Authorization: Bearer` credential. The configured auth provider validates the token. See [Worker authentication](https://mastra.ai/docs/server/auth/workers) for server configuration and other credential formats.
+The endpoint uses the server's normal auth pipeline. If the API has an auth provider, set `MASTRA_WORKER_AUTH_TOKEN` to a bearer token that provider accepts. Mastra forwards the value as an `Authorization: Bearer` credential. The configured auth provider validates the token. See [Worker authentication](https://mastra.ai/docs/auth/workers) for server configuration and other credential formats.
 
 ### Scale workers
 
@@ -365,18 +365,18 @@ A distributed PubSub backend persists unacknowledged events, which lets orchestr
 
 The scheduler calculates the next fire time from the current time after it restarts. It doesn't replay schedules that elapsed while it was unavailable.
 
-If the API crashes while a step is executing, that work can be lost and the workflow run can remain in a `running` state. See [known limitations](#known-limitations) and [durable agent crash recovery](https://mastra.ai/docs/long-running-agents/durable-agents).
+If the API crashes while a step is executing, that work can be lost and the workflow run can remain in a `running` state. See [known limitations](#known-limitations) and [durable agent crash recovery](https://mastra.ai/docs/harness/durable-agents).
 
 ## Known limitations
 
 - **No dead-letter queue**: Failed events are nacked and retried, but there's no DLQ for events that fail after all retries.
 - **No built-in health endpoint**: Workers don't expose an HTTP health check. Use container-level liveness probes or process monitoring.
 - **Scheduler is single-instance**: Running multiple scheduler processes causes duplicate schedule fires.
-- **Runs stuck in "running" after API crash**: If the API process crashes while executing a workflow step, the run remains in `running` status with no automatic retry. For [durable agents](https://mastra.ai/docs/long-running-agents/durable-agents), set `recovery.durableAgents` to `'auto'` in the Mastra config to automatically re-drive orphaned runs on server restart. See [Crash recovery](https://mastra.ai/docs/long-running-agents/durable-agents) for details.
+- **Runs stuck in "running" after API crash**: If the API process crashes while executing a workflow step, the run remains in `running` status with no automatic retry. For [durable agents](https://mastra.ai/docs/harness/durable-agents), set `recovery.durableAgents` to `'auto'` in the Mastra config to automatically re-drive orphaned runs on server restart. See [Crash recovery](https://mastra.ai/docs/harness/durable-agents) for details.
 
 ## Related
 
-- [Worker authentication](https://mastra.ai/docs/server/auth/workers): Secure worker-to-API communication
+- [Worker authentication](https://mastra.ai/docs/auth/workers): Secure worker-to-API communication
 - [Workers reference](https://mastra.ai/reference/workers/overview): Details about worker environment variables and types, with a list of supported storage backends
 - [CLI reference](https://mastra.ai/reference/cli/mastra): `mastra worker build` and `mastra worker start`
 - [PubSub](https://mastra.ai/docs/server/pubsub): Event delivery backends