@mastra/mcp-docs-server 1.3.7 → 1.3.8-alpha.10

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

@@ -165,6 +165,8 @@ new Agent({
 
 An `errorProcessors` list passed to a single `generate()` or `stream()` call works differently: it replaces the agent's resolved list for that call, defaults included.
 
+An agent's memory can contribute error processors of its own, for example to recover when a request exceeds the model's context window. They run after the processors above and stay in place when a call passes its own `errorProcessors` list.
+
 Each array also accepts a function that returns an array, so processors can be built per-request from `RequestContext`:
 
 ```typescript

package/.docs/docs/agents/tools.md

@@ -4,7 +4,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/connections/mcp) 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 services like Linear, Slack, and GitHub, [Connect](https://mastra.ai/docs/mastra-platform/connect/tools) on Mastra platform supplies ready-made tools with managed credentials, which you can combine with your own.
 
 **For AI agents:** `execute` has exactly one signature: `execute(inputData, context)`. The first parameter is validated against `inputSchema`. The runtime always provides the second parameter with `requestContext`, `tracingContext`, `abortSignal`, and other execution metadata. You may omit it when unused. Other shapes are outdated. 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.
 
@@ -328,7 +328,7 @@ Subagents can't run client tools. When a subagent calls a tool without `execute`
 
 Use `transform` when a tool returns raw data your application needs, but browser-facing streams or user-visible transcript messages should receive a smaller or safer shape. `transform` is separate from `toModelOutput`: `toModelOutput` shapes the payload sent back to the model, while `transform` shapes tool input, output, errors, approval payloads, and suspension payloads for `display` and `transcript` targets.
 
-If a transform is configured and it fails, Mastra doesn't fall back to the raw payload for display or transcript targets. Input deltas are suppressed when no safe `inputDelta` transform is available.
+A tool-level transform only changes the phases it defines. In the example below, only `output` is transformed, so the stored tool input stays unchanged. If a transform is configured and it fails, Mastra doesn't fall back to the raw payload for display or transcript targets. Input deltas are suppressed when no safe `inputDelta` transform is available.
 
 The following example redacts a secret from both targets:
 
@@ -698,6 +698,7 @@ The [AgentController](https://mastra.ai/docs/harness/agent-controller) automatic
 - [`Agent.generate()` reference](https://mastra.ai/reference/agents/generate): Runtime options for tool selection, steps, and callbacks
 - [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)
+- [Connect tools](https://mastra.ai/docs/mastra-platform/connect/tools): Ready-made tools for providers connected to a Mastra platform project
 - [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/human-in-the-loop)

package/.docs/docs/connections/mcp.md

@@ -8,6 +8,8 @@ Mastra supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.
 
 Use [`MCPClient`](https://mastra.ai/reference/tools/mcp-client) to connect to MCP servers. Use [`MCPServer`](https://mastra.ai/reference/tools/mcp-server) to expose Mastra agents, tools, workflows, prompts, and resources to other MCP-compatible systems. Both speak the MCP `2026-07-28` revision over stdio and Streamable HTTP.
 
+For hosted MCP servers such as Neon and Canva, [Connect](https://mastra.ai/docs/mastra-platform/connect/providers) on Mastra platform can manage the OAuth flow and credentials for you, so agents get the server's tools through [`tools()`](https://mastra.ai/docs/mastra-platform/connect/tools) without a hand-configured `MCPClient`.
+
 > **Note:** Upgrading from `@mastra/mcp` 1.x? See the [migration guide](https://mastra.ai/reference/migrations/mcp-v2).
 
 For credential choices and permission boundaries, see [Authentication and authorization with MCP](https://mastra.ai/docs/guides/mcp-authentication-authorization).

package/.docs/docs/guides/mcp-authentication-authorization.md

@@ -93,6 +93,14 @@ Configure validation appropriate to your issuer, including audience and expiry c
 
 Protecting Mastra routes with `server.auth` and providing interoperable OAuth discovery are different tasks. Don't assume configuring one supplies the other.
 
+### Routes Mastra registers for an MCP server
+
+Alongside the MCP transport, Mastra registers REST routes used by Studio to list servers, inspect tools, execute tools, and read resources. See the [MCP routes reference](https://mastra.ai/reference/server/routes) for the full list. These paths use the default `/api` prefix.
+
+The `POST /api/mcp/:serverId/tools/:toolId/execute` route calls `executeTool()` directly, without a protocol client. With a Mastra FGA provider configured, `MCPServer.executeTool()` enforces tool execution permission using the user in `requestContext`. The REST tool list also filters tools through FGA. These permission checks don't replace route authentication.
+
+Built-in authentication for these routes depends on `server.auth`. Without it, `requiresAuth: true` doesn't enforce authentication. Custom middleware that checks only the `/mcp` or `/sse` transport paths leaves the REST routes open. If you use custom middleware instead of `server.auth`, default-deny `/api/mcp/*` and allow access only after authentication.
+
 ### Pass verified identity to tools
 
 When a Mastra server handles an MCP request, its auth bridge preserves an existing `req.auth`. Otherwise, it uses `server.mcpOptions.setRequestAuth` when configured, or builds `authInfo` from the request context. With the default bridge, the authenticated user is available in `authInfo.extra.user`.
@@ -121,9 +129,10 @@ Keep access tokens, refresh tokens, and service credentials outside model-visibl
 
 - [ ] **Validate tokens:** Configure validation for your issuer, including audience and expiry checks, and confirm an unvalidated token is rejected.
 - [ ] **Challenge missing tokens:** Confirm every protected server path returns `401` without a bearer token.
+- [ ] **Protect MCP REST routes:** If you don't use `server.auth`, confirm `/api/mcp/:serverId/tools*`, `/api/mcp/:serverId/resources*`, and `/api/mcp/v0/servers*` aren't reachable without authentication. Use your configured API prefix if it differs from `/api`.
 - [ ] **Isolate users:** Confirm one user's provider, connection, and stored credentials aren't reused for another user.
 - [ ] **Bind credentials to the issuer:** Confirm registration and tokens aren't reused when the authorization server changes.
-- [ ] **Deny unauthorized operations:** Confirm a caller without permission is denied `tools/call`, including for a tool it never listed.
+- [ ] **Deny unauthorized operations:** Confirm a caller without permission is denied both `tools/call` and `POST /api/mcp/:serverId/tools/:toolId/execute`, including for a tool it never listed.
 - [ ] **Scope records to the caller:** Confirm record lookups resolve the tenant from trusted server context rather than tool arguments.
 - [ ] **Keep tokens at their audience:** Confirm upstream calls use separate credentials and never forward the MCP token.
 - [ ] **Keep secrets out of model data:** Confirm tokens and credentials stay out of instructions, tool arguments, and tool results.

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

@@ -431,6 +431,7 @@ channels: {
 
     return controller.createSession({
       resourceId: thread.resourceId,
+      threadId: thread.id,
       scope: install.id,
       ownerId: controller.id,
       requestContext,
@@ -439,7 +440,7 @@ channels: {
 }
 ```
 
-Create the session under `thread.resourceId`. Because a session can bind only threads it owns, use `resolveResourceId` to assign a different owner to the mapped thread. Sessions are get-or-create for each `resourceId` and `scope` combination. Pass `scope` when one thread needs separate sessions for each installation or principal.
+Create the session under `thread.resourceId`. Because a session can bind only threads it owns, use `resolveResourceId` to assign a different owner to the mapped thread. Pass `threadId: thread.id` so the session opens on the mapped thread. Without it, a session that has tags or a `projectPath` doesn't treat the mapped thread as its own, so it creates an extra empty thread before switching to the mapped one. Sessions are get-or-create for each `resourceId` and `scope` combination. Pass `scope` when one thread needs separate sessions for each installation or principal.
 
 Failures that aren't refusals (a storage outage, a bug in your resolver's dependencies) still post an error to the thread, so a broken bot doesn't look like a silent one. If you need to tell them apart in your own code, a refusal is a `ChannelSessionRejectedError` with the original error as its `cause`.
 

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

@@ -318,14 +318,14 @@ export const mastra = new Mastra({
 
 ### Subscribe to all task events
 
-Calling `stream()` with no filter returns a stream of every task event in the system. On connection, the stream emits a snapshot of all currently running tasks, then forwards live events as they happen.
+Pass `allResources: true` to receive every task event in the system, across all resources. On connection, the stream emits a snapshot of all currently running tasks, then forwards live events as they happen.
 
 ```typescript
 const bgManager = mastra.backgroundTaskManager;
 if (!bgManager) throw new Error('Background tasks are not enabled');
 
 const controller = new AbortController();
-const stream = bgManager.stream({ abortSignal: controller.signal });
+const stream = bgManager.stream({ allResources: true, abortSignal: controller.signal });
 
 for await (const chunk of stream) {
   switch (chunk.type) {
@@ -344,6 +344,8 @@ for await (const chunk of stream) {
 
 The stream stays open until the caller's `AbortSignal` fires. Always pass an `abortSignal` so you can disconnect cleanly.
 
+> **Warning:** `allResources: true` delivers task arguments and results for every user. Use it only in trusted server-side code, never to serve a single user's request. Without `resourceId` or `allResources`, `stream()` only delivers tasks that have no `resourceId`. Agent tasks dispatched with memory always have a `resourceId`, so they won't appear in that stream.
+
 ### Filter the stream
 
 Pass any combination of filter options to narrow the events you receive. Filters apply to both the initial snapshot and the live event subscription.
@@ -357,14 +359,15 @@ const stream = bgManager.stream({
 })
 ```
 
-| Filter        | Description                                         |
-| ------------- | --------------------------------------------------- |
-| `agentId`     | Only events from tasks dispatched by this agent     |
-| `runId`       | Only events from this specific agent run            |
-| `threadId`    | Only events from tasks scoped to this memory thread |
-| `resourceId`  | Only events from tasks scoped to this resource      |
-| `taskId`      | Only events for a single task                       |
-| `abortSignal` | Closes the stream when the signal aborts            |
+| Filter         | Description                                                                                   |
+| -------------- | --------------------------------------------------------------------------------------------- |
+| `agentId`      | Only events from tasks dispatched by this agent                                               |
+| `runId`        | Only events from this specific agent run                                                      |
+| `threadId`     | Only events from tasks scoped to this memory thread                                           |
+| `resourceId`   | Only events from tasks scoped to this resource                                                |
+| `taskId`       | Only events for a single task                                                                 |
+| `allResources` | Include tasks from every resource when `resourceId` is omitted. Trusted server-side code only |
+| `abortSignal`  | Closes the stream when the signal aborts                                                      |
 
 ### Look up task state directly
 

package/.docs/docs/harness/signals.md

@@ -100,6 +100,26 @@ agent.queueMessage('Also check whether the tests need updates.', {
 
 When the thread is idle, `queueMessage()` starts a run immediately. When the thread is active, it preserves turn order by starting a new run after the active run completes.
 
+### Queue a typed signal for the next turn
+
+Use `queueSignal()` when system-generated input needs the same turn ordering as `queueMessage()` but should keep its own signal type, tag, and attributes. For example, a skill invocation can render as a `<skill>` element instead of a plain user message:
+
+```typescript
+agent.queueSignal(
+  {
+    type: 'reactive',
+    tagName: 'skill',
+    attributes: { name: 'triage' },
+    contents: 'Triage the new issue.',
+  },
+  { resourceId: 'user_123', threadId: 'thread_456' },
+)
+```
+
+The model receives `<skill name="triage">Triage the new issue.</skill>`. Queued signals share the `queueMessage()` queue, so they count toward queue-count events and you can cancel them with `cancelQueuedMessages()`.
+
+When a signal starts a run, the run's `AGENT_RUN` span records the signal's `id`, `type`, `tagName`, and `attributes` under `attributes.signal`.
+
 ### Cancel pending input
 
 Use [`cancelQueuedMessages()`](https://mastra.ai/reference/agents/agent) to remove selected pending input without stopping the active run. Cancellation is scoped to the memory thread, including input submitted by other Agents sharing the same runtime and PubSub instance.
@@ -508,12 +528,14 @@ Use heartbeats together with client-side reconnect logic. Heartbeats reduce idle
 
 - [`Agent.sendMessage()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.queueMessage()`](https://mastra.ai/reference/agents/agent)
+- [`Agent.queueSignal()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.sendSignal()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.sendStateSignal()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.subscribeToThread()`](https://mastra.ai/reference/agents/agent)
 - [`createNotificationInboxTool()`](https://mastra.ai/reference/signals/create-notification-inbox-tool)
 - [`client.getAgent().sendMessage()`](https://mastra.ai/reference/client-js/agents)
 - [`client.getAgent().queueMessage()`](https://mastra.ai/reference/client-js/agents)
+- [`client.getAgent().queueSignal()`](https://mastra.ai/reference/client-js/agents)
 - [`client.getAgent().sendSignal()`](https://mastra.ai/reference/client-js/agents)
 - [Server agent routes](https://mastra.ai/reference/server/routes)
 - [`client.getAgent().subscribeToThread()`](https://mastra.ai/reference/client-js/agents)

package/.docs/docs/mastra-platform/connect/providers.md

@@ -10,31 +10,31 @@ A provider is a service you can connect to your project, identified by a provide
 
 This directory covers the generated toolsets and channel setup documented here, rather than every provider in the platform catalog. Run [`mastra connect list`](https://mastra.ai/reference/cli/mastra) to see providers available to your project and their connection status.
 
-| Provider ID       | Provider                                                                                                 | Gives you                                                                                                                   |
-| ----------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `clerk`           | ![](https://cdn.simpleicons.org/clerk?viewbox=auto\&size=28) Clerk                                       | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `discord`         | ![](https://cdn.simpleicons.org/discord?viewbox=auto\&size=28) Discord                                   | [Tools](https://mastra.ai/reference/connect/providers), [Channels](https://mastra.ai/docs/mastra-platform/connect/channels) |
-| `fireflies`       | ![](https://app.nango.dev/images/template-logos/fireflies.svg) Fireflies.ai                              | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `github`          | ![](https://cdn.simpleicons.org/github?viewbox=auto\&size=28) GitHub                                     | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `google-calendar` | ![](https://cdn.simpleicons.org/googlecalendar?viewbox=auto\&size=28) Google Calendar                    | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `google-docs`     | ![](https://cdn.simpleicons.org/googledocs?viewbox=auto\&size=28) Google Docs                            | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `google-drive`    | ![](https://cdn.simpleicons.org/googledrive?viewbox=auto\&size=28) Google Drive                          | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `google-mail`     | ![](https://cdn.simpleicons.org/gmail?viewbox=auto\&size=28) Gmail                                       | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `google-sheet`    | ![](https://cdn.simpleicons.org/googlesheets?viewbox=auto\&size=28) Google Sheets                        | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `hubspot`         | ![](https://cdn.simpleicons.org/hubspot?viewbox=auto\&size=28) HubSpot                                   | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `incident-io`     | ![](https://app.nango.dev/images/template-logos/incident-io.svg) [incident.io setup](#set-up-incidentio) | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `jira`            | ![](https://cdn.simpleicons.org/jira?viewbox=auto\&size=28) Jira                                         | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `linear`          | ![](https://cdn.simpleicons.org/linear?viewbox=auto\&size=28) Linear                                     | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `notion`          | ![](https://cdn.simpleicons.org/notion?viewbox=auto\&size=28) Notion                                     | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `openai`          | ![](https://svgl.app/library/openai.svg) OpenAI                                                          | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `posthog`         | ![](https://cdn.simpleicons.org/posthog?viewbox=auto\&size=28) [PostHog setup](#set-up-posthog)          | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `resend`          | ![](https://cdn.simpleicons.org/resend?viewbox=auto\&size=28) [Resend setup](#set-up-resend)             | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `slack`           | ![](https://svgl.app/library/slack.svg) Slack                                                            | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `slack-channels`  | ![](https://svgl.app/library/slack.svg) Slack channels                                                   | [Channels](https://mastra.ai/docs/mastra-platform/connect/channels)                                                         |
-| `snowflake`       | ![](https://cdn.simpleicons.org/snowflake?viewbox=auto\&size=28) Snowflake                               | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `supabase`        | ![](https://cdn.simpleicons.org/supabase?viewbox=auto\&size=28) Supabase                                 | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
-| `telegram`        | ![](https://cdn.simpleicons.org/telegram?viewbox=auto\&size=28) Telegram                                 | [Channels](https://mastra.ai/docs/mastra-platform/connect/channels)                                                         |
-| `workos`          | ![](https://svgl.app/library/workos.svg) WorkOS                                                          | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| Provider ID       | Provider                                                                              | Gives you                                                                                                                   |
+| ----------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `clerk`           | ![](https://cdn.simpleicons.org/clerk?viewbox=auto\&size=28) Clerk                    | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `discord`         | ![](https://cdn.simpleicons.org/discord?viewbox=auto\&size=28) Discord                | [Tools](https://mastra.ai/reference/connect/providers), [Channels](https://mastra.ai/docs/mastra-platform/connect/channels) |
+| `fireflies`       | ![](https://app.nango.dev/images/template-logos/fireflies.svg) Fireflies.ai           | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `github`          | ![](https://cdn.simpleicons.org/github?viewbox=auto\&size=28) GitHub                  | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `google-calendar` | ![](https://cdn.simpleicons.org/googlecalendar?viewbox=auto\&size=28) Google Calendar | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `google-docs`     | ![](https://cdn.simpleicons.org/googledocs?viewbox=auto\&size=28) Google Docs         | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `google-drive`    | ![](https://cdn.simpleicons.org/googledrive?viewbox=auto\&size=28) Google Drive       | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `google-mail`     | ![](https://cdn.simpleicons.org/gmail?viewbox=auto\&size=28) Gmail                    | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `google-sheet`    | ![](https://cdn.simpleicons.org/googlesheets?viewbox=auto\&size=28) Google Sheets     | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `hubspot`         | ![](https://cdn.simpleicons.org/hubspot?viewbox=auto\&size=28) HubSpot                | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `incident-io`     | ![](https://app.nango.dev/images/template-logos/incident-io.svg) incident.io          | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `jira`            | ![](https://cdn.simpleicons.org/jira?viewbox=auto\&size=28) Jira                      | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `linear`          | ![](https://cdn.simpleicons.org/linear?viewbox=auto\&size=28) Linear                  | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `notion`          | ![](https://cdn.simpleicons.org/notion?viewbox=auto\&size=28) Notion                  | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `openai`          | ![](https://svgl.app/library/openai.svg) OpenAI                                       | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `posthog`         | ![](https://cdn.simpleicons.org/posthog?viewbox=auto\&size=28) PostHog                | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `resend`          | ![](https://cdn.simpleicons.org/resend?viewbox=auto\&size=28) Resend                  | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `slack`           | ![](https://svgl.app/library/slack.svg) Slack                                         | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `slack-channels`  | ![](https://svgl.app/library/slack.svg) Slack channels                                | [Channels](https://mastra.ai/docs/mastra-platform/connect/channels)                                                         |
+| `snowflake`       | ![](https://cdn.simpleicons.org/snowflake?viewbox=auto\&size=28) Snowflake            | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `supabase`        | ![](https://cdn.simpleicons.org/supabase?viewbox=auto\&size=28) Supabase              | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
+| `telegram`        | ![](https://cdn.simpleicons.org/telegram?viewbox=auto\&size=28) Telegram              | [Channels](https://mastra.ai/docs/mastra-platform/connect/channels)                                                         |
+| `workos`          | ![](https://svgl.app/library/workos.svg) WorkOS                                       | [Tools](https://mastra.ai/reference/connect/providers)                                                                      |
 
 Generated toolsets are included in `@mastra/connect`. Upgrading the package gives you toolsets added in newer releases, but provider availability depends on the platform catalog. The [provider toolsets reference](https://mastra.ai/reference/connect/providers) lists the generated tools.
 
@@ -52,98 +52,13 @@ These providers serve their tools from a hosted Model Context Protocol (MCP) ser
 | `robinhood-mcp` | ![](https://cdn.simpleicons.org/robinhood?viewbox=auto\&size=28) Robinhood | [Agentic Trading](https://robinhood.com/us/en/support/agentic-trading) |
 | `sanity-mcp`    | ![](https://cdn.simpleicons.org/sanity?viewbox=auto\&size=28) Sanity       | [Sanity MCP server](https://www.sanity.io/docs/ai/mcp-server)          |
 
-## Provider-specific setup
+## Troubleshoot a connection
 
-Start with the [Connect setup](https://mastra.ai/docs/mastra-platform/connect/overview), then add a provider with `mastra connect add <provider>`. The sections below cover providers whose API keys need permissions or regional settings. For Slack, Discord, and Telegram, follow the [channel setup guide](https://mastra.ai/docs/mastra-platform/connect/channels).
-
-### Set up Resend
-
-The `resend` toolset sends and reads email and manages domains, contacts, segments, broadcasts, templates, and webhooks. To send from your own domain, [verify it in Resend](https://resend.com/docs/dashboard/domains/introduction).
-
-1. In Resend, open [**API Keys**](https://resend.com/api-keys) and select **Create API Key**.
-2. Enter a name, such as `mastra-agents`, and set **Permission** to **Full access**.
-3. Select **Add** and copy the key. It starts with `re_`, and Resend shows it only once.
-4. Run `mastra connect add resend` and paste the key when it asks for **API Key**.
-
-A **Sending access** key fails to connect. Mastra checks a new key by listing your domains, which sending access keys can't do. To expose only the sending tool to an agent, use `allowTools`:
-
-```typescript
-tools({
-  providers: {
-    resend: { allowTools: ['resend_send_email'] },
-  },
-})
-```
-
-This filter controls which tools the agent receives. It doesn't reduce the Resend key's **Full access** permissions.
-
-#### Sending safely
-
-`resend_send_email` retries a failed send up to three times only when the call includes an `idempotency_key`. Without one it doesn't retry automatically, but a retry elsewhere in your app can still duplicate an email that failed after Resend accepted it. When duplicates matter, tell the agent to set a stable key per logical email, such as `confirmation/order-1234`. Resend answers a reused key with the original response, and rejects a reused key with a different payload with a `409`.
-
-If a send fails with a `proxy_error` and status `403`, check that the `from` address uses a domain verified in Resend.
-
-### Set up PostHog
-
-The `posthog` toolset runs HogQL queries and reads and edits insights, dashboards, feature flags, experiments, surveys, cohorts, and persons. It works with PostHog Cloud in either region. Self-hosted PostHog isn't supported.
-
-1. Check your region in PostHog's address bar: `us.posthog.com` or `eu.posthog.com`.
-2. Open [**Settings** > **Personal API keys**](https://us.posthog.com/settings/user-api-keys) on your region's host and select **Create personal API key**.
-3. Limit the key to the organization or projects the agent should see, and choose scopes from the following table.
-4. Create the key and copy it. It starts with `phx_`, and PostHog shows it only once.
-5. Run `mastra connect add posthog`. Choose `us` or `eu` for **Subdomain** and paste the key when it asks for **API Key**.
-
-| Scope               | Read gives the agent                                            | Write also allows                    |
-| ------------------- | --------------------------------------------------------------- | ------------------------------------ |
-| `project`           | `posthog_list_projects`, `posthog_get_project`                  |                                      |
-| `query`             | `posthog_run_query`, `posthog_list_events`, `posthog_get_event` |                                      |
-| `insight`           | List and get insights                                           | Create, update, delete insights      |
-| `dashboard`         | List and get dashboards                                         | Create, update, delete dashboards    |
-| `feature_flag`      | List and get feature flags                                      | Create, update, delete feature flags |
-| `experiment`        | List and get experiments                                        | Create and update experiments        |
-| `survey`            | List and get surveys                                            | Create, update, delete surveys       |
-| `cohort`            | List and get cohorts                                            | Create, update, delete cohorts       |
-| `person`            | List and get persons                                            | Update and delete persons            |
-| `session_recording` | `posthog_list_session_recordings`                               |                                      |
-
-Most PostHog tools take a `project_id`, so give every key `project:read`. Agents call `posthog_list_projects` to find the ID. A read-only analytics agent needs `project:read`, `query:read`, `insight:read`, and `dashboard:read`.
-
-Avoid the `us.i` and `eu.i` subdomains. Those hosts only serve PostHog's event ingestion endpoints, so most tools fail with them. The form also rejects project API keys (`phc_`) and project secret API keys (`phs_`).
-
-#### Query limits
-
-`posthog_run_query` queries count against PostHog's hourly query budget for personal API keys. Prefer aggregated results over raw event exports.
-
-### Set up incident.io
-
-The `incident-io` toolset reads and updates incidents, posts incident updates, manages actions and follow-ups, and reads alerts, schedules, the catalog, and postmortems. Tool keys start with `incident_io_`, with an underscore where the provider ID has a hyphen.
-
-1. In incident.io, open [**Settings** > **API keys**](https://app.incident.io/~/settings/api-keys) and create a key named `mastra-agents` or similar.
-2. Select permissions from the following table. You can only grant permissions you already have.
-3. Create the key and copy it. It starts with `inc_`, and incident.io shows it only once.
-4. Run `mastra connect add incident-io` and paste the key when it asks for **API Key**.
-
-| Agent task                                                                | Permission                 |
-| ------------------------------------------------------------------------- | -------------------------- |
-| Read incidents, updates, timelines, actions, follow-ups, users, and teams | **View data**              |
-| Read private incidents too                                                | **View all incident data** |
-| Read the catalog                                                          | **View catalog**           |
-| Read alerts, schedules, and overrides                                     | **View on-call resources** |
-| Open incidents                                                            | **Create incidents**       |
-| Update incidents, post updates, and manage actions and follow-ups         | **Edit incidents**         |
-
-A triage agent that reads incidents and posts updates needs **View data** and **Edit incidents**, and the incident.io [permissions reference](https://docs.incident.io/admin/api-keys#permissions-reference) describes each permission.
-
-#### Creation and rate limits
-
-`incident_io_create_incident` requires an `idempotency_key`, and incident.io rejects a second incident with the same key. An API key can open 10 incidents an hour that create a chat channel. Listing incidents is limited to 60 requests a minute. If the agent hits `429` errors, tell it to filter incidents instead of paging through all of them.
-
-## Fix a failing provider
-
-A `proxy_error` carries the provider's response in its `status` and `detail` properties.
+Most provider call failures come from the connection's credential or configuration. A `proxy_error` carries the provider's response in its `status` and `detail` properties.
 
 - **Status `401`:** Check whether the credential has expired, been revoked, or been rotated. If it needs replacing, [reauthorize the connection](https://mastra.ai/reference/cli/mastra).
 - **Status `403`:** Check the provider's response for missing scopes, resource-access restrictions, or account requirements. Grant only the access the agent needs. You can exclude unsupported operations with `allowTools`, but filtering tools doesn't change the credential's permissions.
 - **No tools from a provider:** Run `mastra connect list` to check the project and connection status. Check provider selection and tool filters, and confirm that your installed `@mastra/connect` version includes the toolset. Connection changes follow the resolver's [caching behavior](https://mastra.ai/reference/connect/tools). Check app logs for `[@mastra/connect] Skipping` warnings when a connection can't be resolved.
+- **Resend won't connect:** Use an API key with **Full access** permission. A **Sending access** key fails to connect because Mastra checks a new key by listing your domains, which sending access keys can't do.
 
 See [errors](https://mastra.ai/reference/connect/tools) for every error code.

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

@@ -138,7 +138,7 @@ Use a consistent `serviceName` to filter data from a specific application or dep
 
 ## Query observability data
 
-Query hosted observability data from the terminal with the Mastra CLI:
+Browse hosted traces from the terminal with the Mastra CLI:
 
 **npm**:
 
@@ -164,7 +164,28 @@ yarn dlx mastra api trace list
 bun x mastra api trace list
 ```
 
-The CLI can infer platform credentials from your project environment. See the [`mastra api` CLI reference](https://mastra.ai/reference/cli/mastra) for available commands, filtering, pagination, credential resolution, and `curl` examples.
+The CLI reads `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` from your project environment and targets the US observability endpoint by default. See [CLI target resolution](https://mastra.ai/reference/cli/mastra) for other authentication options and regional endpoints.
+
+Use `mastra api trace query` to find completed traces by their fields or related spans. For example, find traces whose root span took more than five seconds:
+
+```bash
+npx mastra api trace query '{
+  "timeRange": {
+    "from": "2026-08-01T00:00:00.000Z",
+    "to": "2026-08-08T00:00:00.000Z"
+  },
+  "where": {
+    "op": "gt",
+    "left": { "path": "durationMs" },
+    "right": { "literal": 5000 }
+  },
+  "page": { "limit": 25 }
+}'
+```
+
+Choose a time range containing your exported traces, up to 31 days. Results appear in `data.traces`.
+
+Mastra Platform uses the same trace-query endpoints and request format as Mastra Server. Use the [Trace queries API reference](https://mastra.ai/reference/observability/tracing/trace-query) for HTTP requests, supported filters, pagination, polling, and field discovery.
 
 You can query exported feedback over HTTP. See the [Feedback API](https://mastra.ai/docs/mastra-platform/api) for its current status, regional endpoints, authentication, project scoping, and supported query parameters such as `traceId` and `environment`.
 

package/.docs/docs/memory/overview.md

@@ -151,6 +151,37 @@ const response = await memoryAgent.generate("What's my favorite color?", {
 
 To list all threads for a resource, or retrieve a specific thread, [use the memory API directly](https://mastra.ai/docs/memory/message-history).
 
+### Identify memory with scopes
+
+Instead of a `memory` object, you can pass `scopes`: the addresses a run acts as, written as `<type>:<value>`. Memory reads the resource from a `resource:` scope and the thread from a `thread:` scope. Other scopes, such as `org:acme`, are passed to tools and processors.
+
+```typescript
+const response = await memoryAgent.generate('Remember my favorite color is blue.', {
+  scopes: ['org:acme', 'resource:user-123', 'thread:conversation-123'],
+})
+```
+
+Scopes can also come from the agent and from the request context. Mastra combines all three sources:
+
+```typescript
+export const memoryAgent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  scopes: ({ requestContext }) => {
+    // Set by your auth middleware. Request bodies can fill unreserved keys.
+    const orgId = requestContext.get('org-id')
+    return orgId ? [`org:${orgId}`] : []
+  },
+  memory: new Memory(),
+})
+```
+
+The resolver's inputs must come from the server, not the client: a request body can set any request context key that isn't reserved. Trusted server middleware can also set scopes directly with the `MASTRA_SCOPES_KEY` request context key. Visit [Request Context](https://mastra.ai/docs/server/request-context) for details. Clients can't send scopes in a request body.
+
+You can mix scopes with `memory.resource`, `memory.thread`, or the resource and thread request context keys, as long as they agree. If a `resource:` or `thread:` scope names a different value than another source, the call throws an error.
+
+Tools, processors, and subagents receive the run's other scopes, but not its `resource:` and `thread:` scopes. Each nested agent call picks its own resource and thread.
+
 ## Observational Memory
 
 Long conversations can fill the context window with raw message history and reduce agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) uses background agents to compress older messages into observations. This reduces the context used by message history while retaining information for later turns.

package/.docs/docs/server/middleware.md

@@ -86,6 +86,10 @@ Generated servers pass `server.apiPrefix` to the Hono adapter's [`prefix` constr
 
 This approach can't block routes declared public with `requiresAuth: false`, because Mastra skips user middleware for those routes. With a non-Hono server adapter, register equivalent middleware through the server framework instead.
 
+During `mastra dev`, inspect the full built-in route list, including MCP routes, in the [OpenAPI specification](http://localhost:4111/api/openapi.json). See the [server overview](https://mastra.ai/docs/server/overview) for API exploration and production settings.
+
+If you use middleware for authentication without `server.auth`, prefer default-deny middleware that authenticates requests before allowing access, rather than enumerating protected paths. Include the full API prefix so REST routes alongside MCP transports are covered.
+
 ### Using `RequestContext`
 
 You can populate `RequestContext` in a runtime server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.

package/.docs/docs/server/request-context.md

@@ -284,11 +284,35 @@ requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id)
 requestContext.set(MASTRA_THREAD_ID_KEY, threadId)
 ```
 
-| Key                         | Purpose                                                                                                                                                                                                                                                                   |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MASTRA_RESOURCE_ID_KEY`    | Forces all memory operations to use this resource ID. The server validates that accessed threads belong to this resource and returns 403 if not.                                                                                                                          |
-| `MASTRA_THREAD_ID_KEY`      | Forces thread operations to use this thread ID, overriding client-provided values                                                                                                                                                                                         |
-| `MASTRA_MESSAGE_AUTHOR_KEY` | Names who sent a user message as `{ id, name?, avatarUrl? }`. Agent-controller sessions persist it at `content.metadata.signal.author` and mirror it to `providerMetadata.mastra.author` for compatibility, so a thread shared by several people can show who wrote what. |
+| Key                         | Purpose                                                                                                                                                                                                                                                                                        |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MASTRA_RESOURCE_ID_KEY`    | Forces all memory operations to use this resource ID. The server validates that accessed threads belong to this resource and returns 403 if not.                                                                                                                                               |
+| `MASTRA_THREAD_ID_KEY`      | Forces thread operations to use this thread ID, overriding client-provided values                                                                                                                                                                                                              |
+| `MASTRA_SCOPES_KEY`         | Sets the [scopes](https://mastra.ai/docs/memory/overview) the agent run acts as, as an array of `<type>:<value>` strings. Combined with the agent's `scopes` and per-call `scopes`. A `resource:` or `thread:` scope that conflicts with another resource or thread value returns a 400 error. |
+| `MASTRA_MESSAGE_AUTHOR_KEY` | Names who sent a user message as `{ id, name?, avatarUrl? }`. Agent-controller sessions persist it at `content.metadata.signal.author` and mirror it to `providerMetadata.mastra.author` for compatibility, so a thread shared by several people can show who wrote what.                      |
+
+Server ownership checks read only `MASTRA_RESOURCE_ID_KEY` and `MASTRA_THREAD_ID_KEY`. If your middleware sets identity through `MASTRA_SCOPES_KEY` and you want those checks, set `MASTRA_RESOURCE_ID_KEY` too:
+
+```typescript
+import {
+  MASTRA_RESOURCE_ID_KEY,
+  MASTRA_THREAD_ID_KEY,
+  MASTRA_SCOPES_KEY,
+} from '@mastra/core/request-context'
+
+requestContext.set(MASTRA_SCOPES_KEY, [`org:${user.orgId}`, `resource:${user.id}`])
+requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id)
+```
+
+The same applies to a `thread:` scope: it sets the run's thread identity, but only `MASTRA_THREAD_ID_KEY` drives the server's thread checks, so set both when middleware pins the thread:
+
+```typescript
+requestContext.set(MASTRA_SCOPES_KEY, [`resource:${user.id}`, `thread:${threadId}`])
+requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id)
+requestContext.set(MASTRA_THREAD_ID_KEY, threadId)
+```
+
+Scopes from the request context and per-call `scopes` need a `@mastra/server` release that reserves them. Older servers pass these values from request bodies through to the agent, so while one is registered, agents throw an `AGENT_SCOPES_SERVER_OUTDATED` error instead of using them. The agent's own `scopes` option still applies.
 
 These keys are used to implement user isolation in multi-tenant applications. See [Authorization middleware](https://mastra.ai/docs/server/middleware) for usage examples.
 

package/.docs/integrations/databases/clickhouse.md

@@ -290,7 +290,7 @@ Don't set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `Shar
 
 ### Observability domain options
 
-`ObservabilityStorageClickhouse` and `ObservabilityStorageClickhouseVNext` accept the same connection options as `ClickhouseStore` (`url`, `username`, `password`, or a pre-configured `client`). `ObservabilityStorageClickhouseVNext` also accepts `retention`, the per-signal TTL in days described in [ClickHouse native TTL](https://mastra.ai/reference/storage/retention), and `traceQuery`, the execution limits for [advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query).
+`ObservabilityStorageClickhouse` and `ObservabilityStorageClickhouseVNext` accept the same connection options as `ClickhouseStore` (`url`, `username`, `password`, or a pre-configured `client`). `ObservabilityStorageClickhouseVNext` also accepts `retention`, the per-signal TTL in days described in [ClickHouse native TTL](https://mastra.ai/reference/storage/retention), and `traceQuery`, the execution limits for [trace queries](https://mastra.ai/reference/observability/tracing/trace-query).
 
 ## Hosting options
 

package/.docs/models/environment-variables.md

@@ -40,6 +40,7 @@ List of required environment variables for each model provider and gateway suppo
 | [Berget.AI](https://mastra.ai/models/providers/berget)                                       | `berget/*`                 | `BERGET_API_KEY`                                                                                      |
 | [Blue Claw](https://mastra.ai/models/providers/blueclaw)                                     | `blueclaw/*`               | `BLUECLAW_API_KEY`                                                                                    |
 | [Bothub](https://mastra.ai/models/providers/bothub)                                          | `bothub/*`                 | `BOTHUB_API_KEY`                                                                                      |
+| [Boundless](https://mastra.ai/models/providers/boundless)                                    | `boundless/*`              | `BOUNDLESS_API_KEY`                                                                                   |
 | [Cerebras](https://mastra.ai/models/providers/cerebras)                                      | `cerebras/*`               | `CEREBRAS_API_KEY`                                                                                    |
 | [Charm Hyper](https://mastra.ai/models/providers/hyper)                                      | `hyper/*`                  | `HYPER_API_KEY`                                                                                       |
 | [Chutes](https://mastra.ai/models/providers/chutes)                                          | `chutes/*`                 | `CHUTES_API_KEY`                                                                                      |
@@ -163,6 +164,7 @@ List of required environment variables for each model provider and gateway suppo
 | [routing.run](https://mastra.ai/models/providers/routing-run)                                | `routing-run/*`            | `ROUTING_RUN_API_KEY`                                                                                 |
 | [RunInfra](https://mastra.ai/models/providers/runinfra)                                      | `runinfra/*`               | `RUNINFRA_GATEWAY_KEY`                                                                                |
 | [Sakana AI](https://mastra.ai/models/providers/sakana)                                       | `sakana/*`                 | `SAKANA_API_KEY`                                                                                      |
+| [SambaNova](https://mastra.ai/models/providers/sambanova)                                    | `sambanova/*`              | `SAMBANOVA_API_KEY`                                                                                   |
 | [Sarvam AI](https://mastra.ai/models/providers/sarvam)                                       | `sarvam/*`                 | `SARVAM_API_KEY`                                                                                      |
 | [Scaleway](https://mastra.ai/models/providers/scaleway)                                      | `scaleway/*`               | `SCALEWAY_API_KEY`                                                                                    |
 | [SCNet Token Plan](https://mastra.ai/models/providers/scnet-token-plan)                      | `scnet-token-plan/*`       | `SCNET_API_KEY`                                                                                       |

package/.docs/models/gateways/neon.md

@@ -4,7 +4,7 @@
 
 # ![Neon logo](https://models.dev/logos/neon.svg)Neon
 
-Neon aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 47 models through Mastra's model router.
+Neon aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 57 models through Mastra's model router.
 
 Learn more in the [Neon documentation](https://neon.com/docs).
 
@@ -38,6 +38,7 @@ NEON_AI_GATEWAY_TOKEN=your-gateway-key
 | `claude-fable-5`              |
 | `claude-fable-5-1`            |
 | `claude-haiku-4-5`            |
+| `claude-haiku-5-5`            |
 | `claude-opus-4-1`             |
 | `claude-opus-4-5`             |
 | `claude-opus-4-6`             |
@@ -48,14 +49,19 @@ NEON_AI_GATEWAY_TOKEN=your-gateway-key
 | `claude-sonnet-4-5`           |
 | `claude-sonnet-4-6`           |
 | `claude-sonnet-5`             |
+| `claude-sonnet-5-5`           |
+| `deepseek-v4-1-flash`         |
 | `gemini-3-1-flash-lite`       |
 | `gemini-3-1-pro`              |
 | `gemini-3-5-flash`            |
 | `gemini-3-5-flash-lite`       |
 | `gemini-3-6-flash`            |
+| `gemini-3-7-flash`            |
+| `gemini-3-8-flash`            |
 | `gemini-3-flash`              |
 | `gemma-3-12b`                 |
 | `glm-5-2`                     |
+| `glm-5-3`                     |
 | `glm-5-3-flash`               |
 | `gpt-5`                       |
 | `gpt-5-1`                     |
@@ -71,10 +77,14 @@ NEON_AI_GATEWAY_TOKEN=your-gateway-key
 | `gpt-5-6-terra`               |
 | `gpt-5-mini`                  |
 | `gpt-5-nano`                  |
+| `gpt-6-1-sol`                 |
 | `gpt-6-astra`                 |
+| `gpt-6-luna`                  |
+| `gpt-6-sol`                   |
 | `gpt-oss-120b`                |
 | `gpt-oss-20b`                 |
 | `grok-4-6`                    |
+| `grok-4-7`                    |
 | `inkling`                     |
 | `kimi-k3`                     |
 | `llama-4-maverick`            |