@mastra/mcp-docs-server 1.1.39-alpha.4 → 1.1.39-alpha.8

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

@@ -1,64 +1,126 @@
 # A2A (Agent-to-Agent)
 
-Mastra supports the Agent-to-Agent (A2A) protocol for exposing agents as remote agents that other agents and services can discover, call, and track over time. A2A is useful when an agent needs to cross a network boundary without exposing the remote agent's internal tools, memory, prompts, or implementation.
+Mastra supports the [Agent-to-Agent (A2A) protocol](https://a2a-protocol.org/latest/) for cross-platform multi-agent systems. Use A2A to expose Mastra agents as remote agents, consume remote A2A agents as Mastra subagents, or call A2A endpoints with the JavaScript client SDK.
+
+A2A is an open protocol for delegating work to agents across network, framework, vendor, and language boundaries. A remote agent keeps its own tools, prompts, memory, workflows, and infrastructure private while exposing a protocol endpoint that other systems can discover and call.
 
 ## When to use A2A
 
-- A parent agent should delegate work to a specialized agent owned by another service or team.
-- A remote agent should keep its tools, prompts, memory, workflows, and infrastructure private.
+- A parent agent should delegate work to a specialized remote agent.
+- A remote agent is owned by another service, team, vendor, or runtime.
 - A backend, browser app, or another A2A-compatible system needs programmatic access to a Mastra agent.
 - Long-running remote work needs task IDs, status updates, artifacts, cancellation, resubscription, or push notifications.
 
 ## How A2A works
 
-A2A maps to the roles described in the [A2A core concepts](https://a2a-protocol.org/latest/topics/key-concepts/):
+A2A uses an agent card for discovery. The card is a JSON document served from a well-known URL. It describes the remote agent and includes the execution URL that accepts A2A JSON-RPC requests.
 
-- **User**: The human, service, or process that asks for work.
-- **Client agent**: The caller that discovers a remote agent, sends messages, and listens for task updates.
-- **Remote agent**: The Mastra agent running behind an A2A endpoint.
+When using the default Mastra Server `apiPrefix` of `/api`, an agent registered as `weather-agent` exposes:
 
-Any registered Mastra agent can be called as an A2A remote agent. It keeps using its own instructions, tools, memory, workflows, and server configuration; A2A changes how the agent is reached, not how it's authored.
+- Agent card: `/api/.well-known/weather-agent/agent-card.json`
+- Execution endpoint: `/api/a2a/weather-agent`
 
-The flow is:
+An agent card includes fields like the agent name, description, endpoint URL, provider, capabilities, security metadata, and skills:
 
-1. Register a standard Mastra agent in your `Mastra` instance.
-2. Start Mastra Server or mount Mastra routes into your own server.
-3. Mastra exposes the agent through an agent card at `/.well-known/:agentId/agent-card.json` and an execution endpoint at `/a2a/:agentId`.
-4. A client reads the card, sends A2A JSON-RPC methods such as `message/send`, `message/stream`, `tasks/get`, `tasks/cancel`, or `tasks/resubscribe`, then receives task, artifact, and status events.
+```json
+{
+  "protocolVersion": "0.3.0",
+  "name": "Weather Agent",
+  "description": "Provides weather information.",
+  "url": "https://agent.example.com/api/a2a/weather-agent",
+  "version": "1.0",
+  "provider": {
+    "organization": "Acme",
+    "url": "https://acme.example.com"
+  },
+  "capabilities": {
+    "streaming": true,
+    "pushNotifications": true,
+    "stateTransitionHistory": false
+  },
+  "defaultInputModes": ["text/plain"],
+  "defaultOutputModes": ["text/plain"],
+  "skills": [
+    {
+      "id": "weather",
+      "name": "weather",
+      "description": "Gets weather conditions for a location.",
+      "tags": ["tool"]
+    }
+  ]
+}
+```
 
-Agent cards describe the remote agent's name, description, provider, endpoint URL, capabilities, security metadata, and skills. Capabilities advertise features such as streaming and push notifications. Skills describe what the remote agent can do so callers can decide whether it fits the task.
+A2A represents work as messages and tasks. Messages carry text, file, or structured data parts. Tasks are stateful units of work with IDs and lifecycle states, so clients can follow long-running work, send follow-up turns, cancel work, or resubscribe after a disconnect.
 
-A2A represents work as messages and tasks. Messages carry text, file, or structured data parts. Tasks are stateful units of work with IDs and lifecycle states, so clients can follow long-running work, send follow-up turns, cancel work, or resubscribe after a disconnect. Remote agents can also return artifacts, such as text, files, or structured data, during or after a task.
+## Get started
 
-## Quickstart
+A2A has two common paths in Mastra:
 
-Start with any agent registered in your `Mastra` instance. When Mastra Server runs, the agent is available as a remote A2A agent through its registered ID.
+- Consume a remote A2A agent as a Mastra subagent with `A2AAgent`.
+- Send requests to a Mastra A2A endpoint with `MastraClient.getA2A()`.
 
-For an agent registered as `research-agent`, Mastra exposes:
+Use `A2AAgent` when another Mastra agent should delegate work to a remote agent. Use the client SDK when application code needs to call an A2A-enabled Mastra endpoint directly.
 
-- Agent card: `/.well-known/research-agent/agent-card.json`
-- Execution endpoint: `/a2a/research-agent`
+## Consume A2A agents as subagents
 
-Use `MastraClient.getA2A()` to fetch the agent card and call the remote agent:
+Use `A2AAgent` to wrap a remote A2A agent, then add it to a parent agent with the [supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) 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'
+import { A2AAgent } from '@mastra/core/a2a'
+
+const remoteWeatherAgent = new A2AAgent({
+  url: 'https://weather.example.com/api/.well-known/weather-agent/agent-card.json',
+  headers: {
+    Authorization: `Bearer ${process.env.WEATHER_AGENT_TOKEN}`,
+  },
+})
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: 'Answer user questions and delegate weather questions when needed.',
+  model: 'openai/gpt-5.4',
+  agents: {
+    remoteWeatherAgent,
+  },
+})
+```
+
+If `url` points to a domain, `A2AAgent` fetches the agent card from `/.well-known/agent-card.json`. Use a domain URL for single-agent servers that follow that discovery path. For multi-agent servers, pass the full card URL, such as `https://agent.example.com/api/.well-known/weather-agent/agent-card.json`.
+
+During execution, `A2AAgent`:
+
+- Fetches and caches the remote agent card.
+- Reads the execution URL and capabilities from the card.
+- Calls `message/send` for non-streaming runs or `message/stream` when streaming is supported.
+- Converts remote messages, tasks, artifacts, and status updates into Mastra subagent results.
+- Supports `resumeGenerate()` and `resumeStream()` when the remote task requires follow-up input or resubscription.
+
+If the remote card doesn't advertise streaming support, `A2AAgent.stream()` falls back to the non-streaming generate path and returns a buffered stream result.
+
+## Send requests with the client SDK
+
+Use `MastraClient.getA2A()` when you want application code to call an A2A-enabled Mastra agent. Configure `baseUrl` for the server origin and `apiPrefix` when the server doesn't use the default `/api` prefix.
 
 ```typescript
 import { MastraClient } from '@mastra/client-js'
 
 const client = new MastraClient({
   baseUrl: 'https://agent.example.com',
+  headers: {
+    Authorization: `Bearer ${process.env.AGENT_API_TOKEN}`,
+  },
 })
 
-const a2a = client.getA2A('research-agent')
+const a2a = client.getA2A('weather-agent')
 const card = await a2a.getAgentCard()
 
 console.log(card.name, card.capabilities)
 ```
 
-## Discover and call remote agents
-
-A2A discovery starts with the agent card. The [A2A discovery guide](https://a2a-protocol.org/latest/topics/agent-discovery/) describes well-known URI discovery, registries, and direct configuration. Mastra supports the well-known route for registered agents at `/.well-known/:agentId/agent-card.json`.
-
-Use `sendMessageStream()` to receive task status and artifact updates over Server-Sent Events (SSE):
+Use `sendMessageStream()` to send a message and receive task status and artifact updates over Server-Sent Events (SSE):
 
 ```typescript
 const stream = a2a.sendMessageStream({
@@ -66,7 +128,7 @@ const stream = a2a.sendMessageStream({
     kind: 'message',
     role: 'user',
     messageId: crypto.randomUUID(),
-    parts: [{ kind: 'text', text: 'Summarize this incident report.' }],
+    parts: [{ kind: 'text', text: "What's the weather in Prague?" }],
   },
 })
 
@@ -89,7 +151,26 @@ for await (const event of updates) {
 }
 ```
 
-Agent cards can contain sensitive information, such as internal URLs or private skill descriptions. Protect restricted cards with access controls, and use agent card verification when a client needs to validate that a card came from a trusted source.
+## Configure subagent calls
+
+`A2AAgent` accepts request options for authenticated or constrained environments:
+
+```typescript
+import { A2AAgent } from '@mastra/core/a2a'
+
+const remoteWeatherAgent = new A2AAgent({
+  url: 'https://weather.example.com/api/.well-known/weather-agent/agent-card.json',
+  headers: {
+    Authorization: `Bearer ${process.env.WEATHER_AGENT_TOKEN}`,
+  },
+  retries: 2,
+  backoffMs: 250,
+  maxBackoffMs: 1000,
+  timeoutMs: 30_000,
+})
+```
+
+You can also pass `credentials`, `fetch`, and `abortSignal` when the runtime needs custom fetch behavior or request cancellation.
 
 ## Push notifications
 
@@ -144,67 +225,13 @@ const card = await a2a.getAgentCard({
     },
   },
 })
-```
-
-Use client-side signature verification to enforce trusted keys before calling the remote agent.
-
-## Use remote agents as subagents
-
-Use `A2AAgent` when a Mastra parent agent should call a remote A2A agent as a subagent. Create an `A2AAgent` with a remote agent card URL or single-agent domain, then register it in the parent agent's `agents` map.
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { A2AAgent } from '@mastra/core/a2a'
-
-const remoteWeatherAgent = new A2AAgent({
-  url: 'https://weather.example.com',
-})
-
-export const supportAgent = new Agent({
-  id: 'support-agent',
-  name: 'Support Agent',
-  instructions: 'Answer user questions and delegate weather questions when needed.',
-  model: 'openai/gpt-5.4',
-  agents: {
-    remoteWeatherAgent,
-  },
-})
-```
-
-> **Tip:** If `url` points to a domain, `A2AAgent` fetches the agent card from `/.well-known/agent-card.json`. Use this for single-agent servers. For multi-agent servers, pass the explicit card URL, such as `https://agent.example.com/.well-known/:agentId/agent-card.json`. If `url` already ends with `/agent-card.json`, Mastra uses that URL directly. `A2AAgent` doesn't discover agent IDs beyond the URL you provide.
-
-`A2AAgent` implements Mastra's subagent interface. The parent agent can call it like any other subagent, while `A2AAgent` handles the protocol details.
 
-During execution, `A2AAgent`:
-
-- Fetches and caches the remote agent card.
-- Reads the execution URL and capabilities from the card.
-- Calls `message/send` for non-streaming runs or `message/stream` when streaming is supported.
-- Converts remote messages, tasks, artifacts, and status updates into Mastra subagent results.
-- Supports `resumeGenerate()` and `resumeStream()` when the remote task requires follow-up input or resubscription.
-
-If the remote card doesn't advertise streaming support, `A2AAgent.stream()` falls back to the non-streaming generate path and returns a buffered stream result.
-
-## Configure subagent calls
-
-`A2AAgent` accepts request options for authenticated or constrained environments:
-
-```typescript
-import { A2AAgent } from '@mastra/core/a2a'
-
-const remoteWeatherAgent = new A2AAgent({
-  url: 'https://weather.example.com',
-  headers: {
-    Authorization: `Bearer ${process.env.WEATHER_AGENT_TOKEN}`,
-  },
-  retries: 2,
-  backoffMs: 250,
-  maxBackoffMs: 1000,
-  timeoutMs: 30_000,
-})
+if (!card.signatures?.length) {
+  throw new Error('Expected a signed A2A agent card.')
+}
 ```
 
-You can also pass `credentials`, `fetch`, and `abortSignal` when the runtime needs custom fetch behavior or request cancellation.
+Use client-side signature verification when a client must enforce trusted keys before calling the remote agent.
 
 ## Verify subagent cards
 
@@ -214,7 +241,7 @@ Use `verifyAgentCard` when a parent agent should validate a remote agent before
 import { A2AAgent } from '@mastra/core/a2a'
 
 const remoteWeatherAgent = new A2AAgent({
-  url: 'https://weather.example.com/.well-known/agent-card.json',
+  url: 'https://weather.example.com/api/.well-known/weather-agent/agent-card.json',
   verifyAgentCard: {
     verify: async (card, context) => {
       if (card.provider?.organization !== 'Weather Inc') {

package/.docs/docs/build-with-ai/skills.md

@@ -32,4 +32,32 @@ bun x skills add mastra-ai/skills
 
 Mastra skills work with any coding agent that supports the [Skills standard](https://agentskills.io/), including Claude Code, Cursor, Codex, OpenCode, and others.
 
+## Update skill
+
+To update to the latest version of the Mastra skill, run:
+
+**npm**:
+
+```bash
+npx skills update mastra
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx skills update mastra
+```
+
+**Yarn**:
+
+```bash
+yarn dlx skills update mastra
+```
+
+**Bun**:
+
+```bash
+bun x skills update mastra
+```
+
 They're also available on [GitHub](https://github.com/mastra-ai/skills).

package/.docs/docs/server/auth/fga.md

@@ -25,6 +25,7 @@ const mastra = new Mastra({
     auth: new MastraAuthWorkos({
       /* ... */
       fetchMemberships: true,
+      mapUserToResourceId: user => user.teamId,
     }),
     fga: new MastraFGAWorkos({
       resourceMapping: {
@@ -39,6 +40,9 @@ const mastra = new Mastra({
         [MastraFGAPermissions.MEMORY_WRITE]: 'update',
       },
     }),
+    storedResources: {
+      scope: true,
+    },
   },
 });
 ```
@@ -47,6 +51,8 @@ When using `MastraFGAWorkos`, set `fetchMemberships: true` on `MastraAuthWorkos`
 
 Use `thread` as the resource-mapping key for memory authorization. `MastraFGAWorkos` still accepts the legacy alias `memory`, but new configs should prefer `thread`.
 
+When `server.fga` is configured, Mastra enforces FGA on protected actions. If a protected action has no authenticated user, Mastra denies it. If `server.fga` is not configured, these FGA checks are skipped and Mastra keeps the previous behavior.
+
 ### Resource mapping
 
 The `resourceMapping` tells Mastra how to resolve FGA resource types and IDs from request context. Keys are Mastra resource types, values define the FGA resource type and how to derive the ID:
@@ -67,6 +73,7 @@ resourceMapping: {
 - `user` — the authenticated user
 - `resourceId` — the owning Mastra resource ID when available (for example, a thread's `resourceId`)
 - `requestContext` — the current request context for advanced tenant resolution
+- `metadata` — provider-specific metadata for the attempted action
 
 Return `undefined` from `deriveId()` to fall back to the original Mastra resource ID.
 
@@ -89,9 +96,43 @@ If no mapping exists for a permission, the original string is passed through.
 
 Use `validatePermissions()` to validate the full set of permissions Mastra may emit at startup. Use this when a provider requires every Mastra permission to have an explicit provider permission slug.
 
+### Stored resource scoping
+
+FGA authorizes access to a resource. It does not automatically filter stored records that live in shared storage. Enable stored resource scoping when the built-in stored resource APIs are used in a multi-tenant app.
+
+```typescript
+const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthWorkos({
+      /* ... */
+      mapUserToResourceId: user => user.teamId,
+    }),
+    storedResources: {
+      scope: true,
+    },
+  },
+});
+```
+
+With `scope: true`, Mastra reads `MASTRA_RESOURCE_ID_KEY` from the request context. `mapUserToResourceId()` sets this value after authentication. Stored resource handlers persist the scope in record metadata and filter list, read, update, publish, and delete operations by that scope.
+
+Use an object when the scope needs custom request logic:
+
+```typescript
+storedResources: {
+  scope: {
+    metadataKey: 'teamId',
+    resolve: ({ user }) => user.teamId,
+    requireScope: true,
+  },
+},
+```
+
+If `requireScope` is `true` or omitted, scoped stored resource routes fail when no scope can be resolved.
+
 ### Route policy coverage
 
-Mastra includes route-level FGA metadata for built-in resource routes, including agents, workflows, tools, MCP tools, memory threads, responses, and conversations. A route is checked when it has route-level `fga` metadata, when Mastra can derive built-in metadata for that route, or when the provider supplies metadata with `resolveRouteFGA()`.
+Mastra includes route-level FGA metadata for built-in resource routes, including agents, workflows, tools, MCP tools, memory threads, responses, conversations, and stored resources. Stored resource route coverage includes `/stored/agents`, `/stored/mcp-clients`, `/stored/prompt-blocks`, `/stored/scorers`, `/stored/skills`, and `/stored/workspaces`. A route is checked when it has route-level `fga` metadata, when Mastra can derive built-in metadata for that route, or when the provider supplies metadata with `resolveRouteFGA()`.
 
 To deny protected routes that do not resolve FGA metadata, configure route policy coverage on the FGA provider:
 
@@ -159,16 +200,20 @@ const fga = new MastraFGAWorkos({
 
 When an FGA provider is configured, Mastra automatically checks authorization at these lifecycle points:
 
-| Lifecycle point                        | Permission checked                             | Resource                               |
-| -------------------------------------- | ---------------------------------------------- | -------------------------------------- |
-| Agent execution (`generate`, `stream`) | `agents:execute`                               | `{ type: 'agent', id: agentId }`       |
-| Workflow execution                     | `workflows:execute`                            | `{ type: 'workflow', id: workflowId }` |
-| Tool execution                         | `tools:execute`                                | `{ type: 'tool', id: toolName }`       |
-| Thread/memory access                   | `memory:read`, `memory:write`, `memory:delete` | `{ type: 'thread', id: threadId }`     |
-| MCP tool execution                     | `tools:execute`                                | `{ type: 'tool', id: toolName }`       |
-| HTTP resource routes                   | Configured per route                           | Configured per route                   |
+| Lifecycle point                                                  | Permission checked                              | Resource type        | Resource ID                                                         |
+| ---------------------------------------------------------------- | ----------------------------------------------- | -------------------- | ------------------------------------------------------------------- |
+| Agent execution (`generate`, `stream`)                           | `agents:execute`                                | `agent`              | `agentId`                                                           |
+| Built-in workflow HTTP execution routes and `Workflow.execute()` | `workflows:execute`                             | `workflow`           | `workflowId`                                                        |
+| Standalone tool execution                                        | `tools:execute`                                 | `tool`               | `toolName`                                                          |
+| Agent tool execution                                             | `tools:execute`                                 | `tool`               | `${agentId}:${toolName}`                                            |
+| MCP tool execution                                               | `tools:execute`                                 | `tool`               | `JSON.stringify([serverName, toolName])`                            |
+| Thread and memory access                                         | `memory:read`, `memory:write`, `memory:delete`  | `thread`             | `threadId`                                                          |
+| Stored resource routes                                           | Stored resource permission for the route action | Stored resource type | Route record ID, or the stored-resource scope for collection routes |
+| HTTP resource routes                                             | Configured per route                            | Configured per route | Configured per route                                                |
+
+Direct SDK calls to `createRun().start()`, `resume()`, or `restart()` are not independently checked by core FGA in this release. Make those calls from a protected route or guard them in application code. Pass a `requestContext` with an authenticated user when invoking protected entry points directly.
 
-All checks are **no-ops when FGA is not configured**, maintaining backward compatibility.
+Core agent, internal workflow, tool, and memory checks also pass `requestContext` and action metadata to the FGA provider. Route checks pass `requestContext`. Thread checks pass the owning `resourceId` when available.
 
 ## Custom FGA provider
 

package/.docs/models/index.md

@@ -1,6 +1,6 @@
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4182 models from 120 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4219 models from 121 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/novita-ai.md

@@ -15,7 +15,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "novita-ai/Sao10K/L3-8B-Stheno-v3.2"
+  model: "novita-ai/baichuan/baichuan-m2-32b"
 });
 
 // Generate a response
@@ -118,10 +118,10 @@ for await (const chunk of stream) {
 | `novita-ai/qwen/qwen3.5-27b`                                  | 262K    |       |           |       |       |       | $0.30      | $2          |
 | `novita-ai/qwen/qwen3.5-35b-a3b`                              | 262K    |       |           |       |       |       | $0.25      | $2          |
 | `novita-ai/qwen/qwen3.5-397b-a17b`                            | 262K    |       |           |       |       |       | $0.60      | $4          |
-| `novita-ai/sao10k/l3-70b-euryale-v2.1`                        | 8K      |       |           |       |       |       | $1         | $1          |
-| `novita-ai/sao10k/l3-8b-lunaris`                              | 8K      |       |           |       |       |       | $0.05      | $0.05       |
-| `novita-ai/Sao10K/L3-8B-Stheno-v3.2`                          | 8K      |       |           |       |       |       | $0.05      | $0.05       |
-| `novita-ai/sao10k/l31-70b-euryale-v2.2`                       | 8K      |       |           |       |       |       | $1         | $1          |
+| `novita-ai/sao10K/l3-70b-euryale-v2.1`                        | 8K      |       |           |       |       |       | $1         | $1          |
+| `novita-ai/sao10K/l3-8b-lunaris`                              | 8K      |       |           |       |       |       | $0.05      | $0.05       |
+| `novita-ai/sao10K/L3-8B-stheno-v3.2`                          | 8K      |       |           |       |       |       | $0.05      | $0.05       |
+| `novita-ai/sao10K/l31-70b-euryale-v2.2`                       | 8K      |       |           |       |       |       | $1         | $1          |
 | `novita-ai/xiaomimimo/mimo-v2-flash`                          | 262K    |       |           |       |       |       | $0.10      | $0.30       |
 | `novita-ai/zai-org/autoglm-phone-9b-multilingual`             | 66K     |       |           |       |       |       | $0.04      | $0.14       |
 | `novita-ai/zai-org/glm-4.5`                                   | 131K    |       |           |       |       |       | $0.60      | $2          |
@@ -144,7 +144,7 @@ const agent = new Agent({
   name: "custom-agent",
   model: {
     url: "https://api.novita.ai/openai",
-    id: "novita-ai/Sao10K/L3-8B-Stheno-v3.2",
+    id: "novita-ai/baichuan/baichuan-m2-32b",
     apiKey: process.env.NOVITA_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -163,7 +163,7 @@ const agent = new Agent({
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
       ? "novita-ai/zai-org/glm-5.1"
-      : "novita-ai/Sao10K/L3-8B-Stheno-v3.2";
+      : "novita-ai/baichuan/baichuan-m2-32b";
   }
 });
 ```

package/.docs/models/providers/routing-run.md

@@ -0,0 +1,107 @@
+# ![routing.run logo](https://models.dev/logos/routing-run.svg)routing.run
+
+Access 37 routing.run models through Mastra's model router. Authentication is handled automatically using the `ROUTING_RUN_API_KEY` environment variable.
+
+Learn more in the [routing.run documentation](https://docs.routing.run).
+
+```bash
+ROUTING_RUN_API_KEY=your-api-key
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "routing-run/route/deepseek-v3.2"
+});
+
+// Generate a response
+const response = await agent.generate("Hello!");
+
+// Stream a response
+const stream = await agent.stream("Tell me a story");
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [routing.run documentation](https://docs.routing.run) for details.
+
+## Models
+
+| Model                                         | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| --------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `routing-run/route/deepseek-v3.2`             | 164K    |       |           |       |       |       | $0.49      | $0.74       |
+| `routing-run/route/deepseek-v4-flash`         | 1.0M    |       |           |       |       |       | $0.49      | $0.74       |
+| `routing-run/route/deepseek-v4-flash-full`    | 1.0M    |       |           |       |       |       | $0.49      | $0.74       |
+| `routing-run/route/deepseek-v4-pro`           | 1.0M    |       |           |       |       |       | $0.49      | $0.74       |
+| `routing-run/route/deepseek-v4-pro-precision` | 1.0M    |       |           |       |       |       | $0.74      | $1          |
+| `routing-run/route/gemma-4-31b-it`            | 131K    |       |           |       |       |       | $0.10      | $0.30       |
+| `routing-run/route/glm-4.7`                   | 128K    |       |           |       |       |       | $1         | $4          |
+| `routing-run/route/glm-4.7-flash`             | 128K    |       |           |       |       |       | $1         | $4          |
+| `routing-run/route/glm-5`                     | 203K    |       |           |       |       |       | $0.79      | $3          |
+| `routing-run/route/glm-5-highspeed`           | 203K    |       |           |       |       |       | $1         | $4          |
+| `routing-run/route/glm-5.1`                   | 203K    |       |           |       |       |       | $1         | $3          |
+| `routing-run/route/glm-5.1-fp16`              | 203K    |       |           |       |       |       | $1         | $4          |
+| `routing-run/route/glm-5.1-full`              | 203K    |       |           |       |       |       | $1         | $4          |
+| `routing-run/route/glm-5.1-precision`         | 203K    |       |           |       |       |       | $1         | $4          |
+| `routing-run/route/kimi-k2.5`                 | 262K    |       |           |       |       |       | $0.46      | $2          |
+| `routing-run/route/kimi-k2.5-highspeed`       | 131K    |       |           |       |       |       | $0.65      | $3          |
+| `routing-run/route/kimi-k2.6`                 | 262K    |       |           |       |       |       | $0.46      | $2          |
+| `routing-run/route/kimi-k2.6-full`            | 262K    |       |           |       |       |       | $0.46      | $2          |
+| `routing-run/route/kimi-k2.6-precision`       | 262K    |       |           |       |       |       | $0.65      | $3          |
+| `routing-run/route/mimo-v2.5`                 | 256K    |       |           |       |       |       | $0.40      | $2          |
+| `routing-run/route/mimo-v2.5-pro`             | 1.0M    |       |           |       |       |       | $0.45      | $1          |
+| `routing-run/route/mimo-v2.5-pro-precision`   | 1.0M    |       |           |       |       |       | $0.45      | $1          |
+| `routing-run/route/minimax-m2.5`              | 100K    |       |           |       |       |       | $0.19      | $1          |
+| `routing-run/route/minimax-m2.5-highspeed`    | 100K    |       |           |       |       |       | $0.19      | $1          |
+| `routing-run/route/minimax-m2.7`              | 100K    |       |           |       |       |       | $0.33      | $1          |
+| `routing-run/route/minimax-m2.7-highspeed`    | 100K    |       |           |       |       |       | $0.33      | $1          |
+| `routing-run/route/mistral-large-3`           | 128K    |       |           |       |       |       | $0.50      | $2          |
+| `routing-run/route/mistral-medium-2505`       | 128K    |       |           |       |       |       | $0.40      | $2          |
+| `routing-run/route/mistral-small-2503`        | 128K    |       |           |       |       |       | $0.15      | $0.60       |
+| `routing-run/route/qwen3.5-397b-a17b`         | 262K    |       |           |       |       |       | $1         | $3          |
+| `routing-run/route/qwen3.5-9b`                | 262K    |       |           |       |       |       | $0.20      | $0.60       |
+| `routing-run/route/qwen3.5-9b-chat`           | 262K    |       |           |       |       |       | $0.20      | $0.60       |
+| `routing-run/route/qwen3.6-27b`               | 262K    |       |           |       |       |       | $1         | $3          |
+| `routing-run/route/step-3.5-flash`            | 262K    |       |           |       |       |       | $0.10      | $0.29       |
+| `routing-run/route/step-3.5-flash-2603`       | 262K    |       |           |       |       |       | $0.10      | $0.30       |
+| `routing-run/route/step-3.5-flash-full`       | 262K    |       |           |       |       |       | $0.10      | $0.29       |
+| `routing-run/route/stepfun-3.5-flash`         | 262K    |       |           |       |       |       | $0.10      | $0.29       |
+
+## Advanced configuration
+
+### Custom headers
+
+```typescript
+const agent = new Agent({
+  id: "custom-agent",
+  name: "custom-agent",
+  model: {
+    url: "https://api.routing.run/v1",
+    id: "routing-run/route/deepseek-v3.2",
+    apiKey: process.env.ROUTING_RUN_API_KEY,
+    headers: {
+      "X-Custom-Header": "value"
+    }
+  }
+});
+```
+
+### Dynamic model selection
+
+```typescript
+const agent = new Agent({
+  id: "dynamic-agent",
+  name: "Dynamic Agent",
+  model: ({ requestContext }) => {
+    const useAdvanced = requestContext.task === "complex";
+    return useAdvanced
+      ? "routing-run/route/stepfun-3.5-flash"
+      : "routing-run/route/deepseek-v3.2";
+  }
+});
+```

package/.docs/models/providers.md

@@ -89,6 +89,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Qiniu](https://mastra.ai/models/providers/qiniu-ai)
 - [Regolo AI](https://mastra.ai/models/providers/regolo-ai)
 - [Requesty](https://mastra.ai/models/providers/requesty)
+- [routing.run](https://mastra.ai/models/providers/routing-run)
 - [Sarvam AI](https://mastra.ai/models/providers/sarvam)
 - [Scaleway](https://mastra.ai/models/providers/scaleway)
 - [SiliconFlow](https://mastra.ai/models/providers/siliconflow)

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

@@ -63,6 +63,10 @@ const agent = new Agent({
       discord: {
         adapter: createDiscordAdapter(),
         cards: false,
+        cors: {
+          origin: ['https://customer-saas.example'],
+          credentials: true,
+        },
         gateway: false,
       },
       slack: createSlackAdapter(), // Plain adapter uses defaults
@@ -77,6 +81,8 @@ const agent = new Agent({
 
 **cards** (`boolean`): Render tool calls as interactive rich cards with buttons. Set to \`false\` to use plain text formatting instead. When disabled and a tool requires approval, the agent uses \`autoResumeSuspendedTools\` to let the LLM decide based on conversation context. (Default: `true`)
 
+**cors** (`CorsOptions`): CORS configuration for this adapter webhook route. Use this for browser-based channel adapters that need cross-origin credentials.
+
 **formatToolCall** (`(info: { toolName, args, result, isError? }) => PostableMessage | null`): Override how tool calls are rendered in the chat. Called once per tool invocation after the result is available. Return \`null\` to suppress the message entirely.
 
 **formatError** (`(error: Error) => PostableMessage`): Override how errors are rendered in the chat. Return a user-friendly message instead of exposing the raw error. (Default: `"❌ Error: <error.message>"`)

package/.docs/reference/configuration.md

@@ -684,16 +684,16 @@ export const mastra = new Mastra({
 
 **Type:** `CorsOptions | false`
 
-CORS (Cross-Origin Resource Sharing) configuration for the server. Set to `false` to disable CORS entirely.
-
-| Property        | Type                 | Default                                                     | Description                                  |
-| --------------- | -------------------- | ----------------------------------------------------------- | -------------------------------------------- |
-| `origin`        | `string \| string[]` | `'*'`                                                       | Origins for CORS requests                    |
-| `allowMethods`  | `string[]`           | `['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']`      | HTTP methods                                 |
-| `allowHeaders`  | `string[]`           | `['Content-Type', 'Authorization', 'x-mastra-client-type']` | Request headers                              |
-| `exposeHeaders` | `string[]`           | `['Content-Length', 'X-Requested-With']`                    | Browser headers                              |
-| `credentials`   | `boolean`            | `false`                                                     | Credentials (cookies, authorization headers) |
-| `maxAge`        | `number`             | `3600`                                                      | Preflight request cache duration in seconds  |
+CORS (Cross-Origin Resource Sharing) configuration for the server. Set to `false` to disable CORS entirely. Use this for one policy across all routes. For a custom route-specific policy, use the `cors` option in [`registerApiRoute()`](https://mastra.ai/reference/server/register-api-route).
+
+| Property        | Type                 | Default                                                                                | Description                                  |
+| --------------- | -------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `origin`        | `string \| string[]` | `'*'`                                                                                  | Origins for CORS requests                    |
+| `allowMethods`  | `string[]`           | `['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']`                                 | HTTP methods                                 |
+| `allowHeaders`  | `string[]`           | `['Content-Type', 'Authorization', 'x-mastra-client-type', 'x-mastra-dev-playground']` | Request headers                              |
+| `exposeHeaders` | `string[]`           | `['Content-Length', 'X-Requested-With']`                                               | Browser headers                              |
+| `credentials`   | `boolean`            | `false`                                                                                | Credentials (cookies, authorization headers) |
+| `maxAge`        | `number`             | `3600`                                                                                 | Preflight request cache duration in seconds  |
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/reference/server/register-api-route.md

@@ -30,6 +30,8 @@ registerApiRoute("/items/:itemId", { ... })
 
 **middleware** (`MiddlewareHandler | MiddlewareHandler[]`): Route-specific middleware functions
 
+**cors** (`CorsOptions`): Route-specific CORS configuration. Use this when one custom route needs a different cross-origin policy from \`server.cors\`.
+
 **openapi** (`DescribeRouteOptions`): OpenAPI metadata for Swagger UI documentation
 
 ## OpenAPI options
@@ -154,6 +156,23 @@ registerApiRoute('/protected', {
 })
 ```
 
+### Route with CORS
+
+Use route-specific CORS when one custom route needs cross-origin credentials, but the rest of the server should keep the global CORS policy.
+
+```typescript
+registerApiRoute('/customer-webhook', {
+  method: 'POST',
+  cors: {
+    origin: ['https://customer-saas.example'],
+    credentials: true,
+  },
+  handler: async c => {
+    return c.json({ ok: true })
+  },
+})
+```
+
 ### Route with OpenAPI Documentation
 
 ```typescript

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.1.39-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [[`5ba7253`](https://github.com/mastra-ai/mastra/commit/5ba7253745c85e8df8012a76d954c640ffa336f7), [`f73980d`](https://github.com/mastra-ai/mastra/commit/f73980d651eb5f7f1ab20582de4615a1b6f10fce), [`9c88701`](https://github.com/mastra-ai/mastra/commit/9c8870195b41a38dc40b6ba2aa55eda04df8fa69), [`4e88dc6`](https://github.com/mastra-ai/mastra/commit/4e88dc6b89f154c0eae37221c8126be0c23c569f), [`19018f0`](https://github.com/mastra-ai/mastra/commit/19018f05722af74a5978781a7731a654b26f7f2a)]:
+  - @mastra/core@1.36.0-alpha.2
+
+## 1.1.39-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`8cdb86c`](https://github.com/mastra-ai/mastra/commit/8cdb86ceed1137bc2768e147dce85a0692b9fb26), [`eda90c5`](https://github.com/mastra-ai/mastra/commit/eda90c5bfd7de11805ecc9f4552716c895fbaf78), [`afc004f`](https://github.com/mastra-ai/mastra/commit/afc004f5cc7e30697809e7021820b9f5881e6719), [`408be73`](https://github.com/mastra-ai/mastra/commit/408be73449dfab92b51eab8c6623b6c443debc25)]:
+  - @mastra/core@1.36.0-alpha.1
+
 ## 1.1.39-alpha.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.39-alpha.4",
+  "version": "1.1.39-alpha.8",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.36.0-alpha.0",
+    "@mastra/core": "1.36.0-alpha.2",
     "@mastra/mcp": "^1.7.1-alpha.0"
   },
   "devDependencies": {
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "vitest": "4.1.5",
+    "@internal/types-builder": "0.0.71",
     "@internal/lint": "0.0.96",
-    "@mastra/core": "1.36.0-alpha.0",
-    "@internal/types-builder": "0.0.71"
+    "@mastra/core": "1.36.0-alpha.2"
   },
   "homepage": "https://mastra.ai",
   "repository": {