@mastra/mcp-docs-server 1.1.15 → 1.1.16-alpha.10

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

@@ -137,6 +137,42 @@ const memory = new Memory({
 
 See [model configuration](https://mastra.ai/reference/memory/observational-memory) for using different models per agent.
 
+### Token-tiered model selection
+
+You can use `ModelByInputTokens` to specify different Observer or Reflector models based on input token count. OM selects the matching model tier at runtime from the configured `upTo` thresholds.
+
+```typescript
+import { Memory, ModelByInputTokens } from '@mastra/memory'
+
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      observation: {
+        model: new ModelByInputTokens({
+          upTo: {
+            10_000: 'google/gemini-2.5-flash', // Fast and cheap for small inputs
+            40_000: 'openai/gpt-4o', // Stronger for medium inputs
+            1_000_000: 'openai/gpt-4.5', // Most capable for very large inputs
+          },
+        }),
+      },
+      reflection: {
+        model: new ModelByInputTokens({
+          upTo: {
+            20_000: 'google/gemini-2.5-flash',
+            80_000: 'openai/gpt-4o',
+          },
+        }),
+      },
+    },
+  },
+})
+```
+
+The `upTo` keys are inclusive upper bounds. OM computes the actual input token count for the Observer or Reflector call, resolves the matching tier directly, and uses that concrete model for the run.
+
+If the input exceeds the largest configured threshold, an error is thrown — ensure your thresholds cover the full range of possible input sizes, or use a model with a sufficiently large context window at the highest tier.
+
 ## Scopes
 
 ### Thread scope (default)

package/.docs/docs/observability/tracing/exporters/datadog.md

@@ -145,6 +145,135 @@ Mastra span types are automatically mapped to Datadog LLMObs span kinds:
 
 Other/future Mastra span types will default to 'task' when mapped unless specified.
 
+## Application Performance Monitoring
+
+The sections above cover Mastra's [LLM Observability](https://docs.datadoghq.com/llm_observability/) integration. To trace your Mastra HTTP server routes (request latency, error tracking, service maps), use `dd-trace` directly for Datadog Application Performance Monitoring (APM).
+
+### Prerequisites
+
+1. **Datadog Agent**: Install a [Datadog Agent](https://docs.datadoghq.com/agent/) on the same host or accessible via network. The agent receives traces from `dd-trace` on `localhost:8126` and forwards them to Datadog. Follow the [agent installation guide](https://docs.datadoghq.com/agent/) to set it up.
+
+2. **dd-trace package**: Install the tracing library in your project:
+
+   **npm**:
+
+   ```bash
+   npm install dd-trace
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add dd-trace
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn add dd-trace
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add dd-trace
+   ```
+
+> **Note:** APM traces always route through the Datadog Agent. This is different from LLM Observability, which supports agentless mode (direct HTTPS to Datadog).
+
+### APM only
+
+Import and initialize `dd-trace` at the top of your entry file, before any other imports:
+
+```typescript
+import tracer from 'dd-trace'
+
+tracer.init({
+  service: process.env.DD_SERVICE || 'my-mastra-app',
+  env: process.env.DD_ENV || 'production',
+  version: process.env.DD_VERSION,
+})
+
+import { Mastra } from '@mastra/core'
+
+export const mastra = new Mastra({
+  bundler: {
+    externals: [
+      'dd-trace',
+      '@datadog/native-metrics',
+      '@datadog/native-appsec',
+      '@datadog/native-iast-taint-tracking',
+      '@datadog/pprof',
+    ],
+  },
+})
+```
+
+Set the tracer metadata environment variables:
+
+```bash
+DD_SERVICE=my-mastra-app
+DD_ENV=production
+DD_VERSION=1.0.0
+```
+
+`dd-trace` auto-instruments popular HTTP frameworks, including those supported by Mastra's [server adapters](https://mastra.ai/docs/server/server-adapters). Inbound requests, outbound HTTP calls, and database queries appear as APM traces in Datadog.
+
+### APM and LLM Observability
+
+Import and initialize `dd-trace` before creating the Mastra instance. The `DatadogExporter` detects the existing tracer and skips re-initialization, adding LLM Observability on top of your APM setup:
+
+```typescript
+import tracer from 'dd-trace'
+
+tracer.init({
+  service: process.env.DD_SERVICE || 'my-mastra-app',
+  env: process.env.DD_ENV || 'production',
+  version: process.env.DD_VERSION,
+})
+
+import { Mastra } from '@mastra/core'
+import { Observability } from '@mastra/observability'
+import { DatadogExporter } from '@mastra/datadog'
+
+export const mastra = new Mastra({
+  observability: new Observability({
+    configs: {
+      datadog: {
+        serviceName: 'my-mastra-app',
+        exporters: [
+          new DatadogExporter({
+            mlApp: process.env.DD_LLMOBS_ML_APP!,
+            apiKey: process.env.DD_API_KEY!,
+          }),
+        ],
+      },
+    },
+  }),
+  bundler: {
+    externals: [
+      'dd-trace',
+      '@datadog/native-metrics',
+      '@datadog/native-appsec',
+      '@datadog/native-iast-taint-tracking',
+      '@datadog/pprof',
+    ],
+  },
+})
+```
+
+```bash
+DD_SERVICE=my-mastra-app
+DD_ENV=production
+DD_VERSION=1.0.0
+DD_API_KEY=your-datadog-api-key
+DD_LLMOBS_ML_APP=my-llm-app
+```
+
+Server routes appear as APM traces and LLM calls appear as LLM Observability spans, all under the same service in Datadog.
+
+> **Note:** Import and initialize `dd-trace` before all other modules. This allows its auto-instrumentation to patch HTTP, database, and framework libraries at load time.
+
 ## Troubleshooting
 
 ### Native module ABI mismatch
@@ -183,5 +312,6 @@ export const mastra = new Mastra({
 
 ## Related
 
-- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [Datadog LLM Observability Documentation](https://docs.datadoghq.com/llm_observability/)
+- [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)
+- [Datadog LLM Observability documentation](https://docs.datadoghq.com/llm_observability/)
+- [Datadog APM documentation](https://docs.datadoghq.com/tracing/)

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

@@ -104,6 +104,7 @@ Mastra provides reserved context keys that, when set by middleware, take precede
 ```typescript
 import { Mastra } from '@mastra/core'
 import { MASTRA_RESOURCE_ID_KEY } from '@mastra/core/request-context'
+import { getAuthenticatedUser } from '@mastra/server/auth'
 
 export const mastra = new Mastra({
   server: {
@@ -117,8 +118,17 @@ export const mastra = new Mastra({
       {
         path: '/api/*',
         handler: async (c, next) => {
+          const token = c.req.header('Authorization')
+          if (!token) {
+            return c.json({ error: 'Unauthorized' }, 401)
+          }
+
+          const user = await getAuthenticatedUser<{ id: string }>({
+            mastra: c.get('mastra'),
+            token,
+            request: c.req.raw,
+          })
           const requestContext = c.get('requestContext')
-          const user = requestContext.get('user')
 
           if (!user) {
             return c.json({ error: 'Unauthorized' }, 401)
@@ -136,6 +146,8 @@ export const mastra = new Mastra({
 })
 ```
 
+`server.middleware` runs before Mastra's per-route auth checks. When middleware needs the authenticated user, call `getAuthenticatedUser()` to resolve it from the configured auth provider without changing the default route auth flow.
+
 With this middleware, the server automatically:
 
 - **Filters thread listing** to only return threads owned by the user

package/.docs/docs/server/server-adapters.md

@@ -341,7 +341,7 @@ app.listen(port, () => {
 Calling `init()` runs three steps in order. Understanding this flow helps when you need to insert your own middleware at specific points.
 
 1. `registerContextMiddleware()`: Attaches the Mastra instance, request context, tools, and abort signal to every request. This makes Mastra available to all subsequent middleware and route handlers.
-2. `registerAuthMiddleware()`: Adds authentication and authorization middleware, but only if `server.auth` is configured in your Mastra instance. Skipped entirely if no auth is configured.
+2. `registerAuthMiddleware()`: Runs the adapter auth hook during initialization. Official adapters enforce auth inline when Mastra registers built-in routes and `registerApiRoute()` routes, so raw framework routes should use the adapter's exported `createAuthMiddleware()` helper when they need Mastra auth.
 3. `registerRoutes()`: Registers all Mastra API routes for agents, workflows, and other features. Also registers MCP routes if MCP servers are configured.
 
 ### Manual initialization
@@ -359,7 +359,6 @@ server.registerContextMiddleware();
 // Middleware that needs Mastra context
 app.use(customMiddleware);
 
-server.registerAuthMiddleware();
 await server.registerRoutes();
 
 // Routes after Mastra
@@ -374,6 +373,8 @@ You can add your own routes to the app alongside Mastra's routes.
 
 - Routes added **before** `init()` won't have Mastra context available.
 - Routes added **after** `init()` have access to the Mastra context (the Mastra instance, request context, authenticated user, etc.).
+- When you want Mastra-managed auth and route metadata such as `requiresAuth`, prefer `registerApiRoute()`.
+- When you mount routes directly on the framework app, use the adapter's exported `createAuthMiddleware()` helper if those routes need Mastra auth.
 
 > **Info:** Visit "Adding custom routes" for [Express](https://mastra.ai/reference/server/express-adapter) and [Hono](https://mastra.ai/reference/server/hono-adapter) for more information.
 

package/.docs/docs/workspace/skills.md

@@ -127,6 +127,29 @@ The agent has three skill tools:
 
 This design is stateless — there is no activation state to track. If the skill instructions leave the conversation context (due to context window limits or compaction), the agent can call `skill` again to reload them.
 
+## Same-named skills
+
+When multiple skill directories contain a skill with the same name, all of them are discovered and listed. The agent sees every skill in its system message, along with each skill's path and source type, so it can tell them apart.
+
+When the agent activates a skill by name, tie-breaking determines which one is returned:
+
+1. **Source-type priority**: local skills take precedence over managed (`.mastra/`) skills, which take precedence over external (`node_modules/`) skills.
+2. **Unresolvable conflicts throw**: if two skills share the same name _and_ the same source type (for example, two local skills both named `brand-guidelines`), `get()` throws an error. Rename one or move it to a different source type to resolve the conflict.
+3. **Path escape hatch**: the agent can pass a skill's full path instead of its name to activate a specific skill, bypassing tie-breaking entirely.
+
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({ basePath: './workspace' }),
+  skills: [
+    'node_modules/@myorg/skills', // external: provides "brand-guidelines"
+    '/skills', // local: also provides "brand-guidelines"
+  ],
+})
+
+// get('brand-guidelines') returns the local copy (local > external)
+// get('node_modules/@myorg/skills/brand-guidelines') returns the external copy
+```
+
 ## Skill search
 
 If BM25 or vector search is enabled on the workspace, skills are automatically indexed. Agents can search across skill content to find relevant instructions.

package/.docs/guides/migrations/upgrade-to-v1/agent.md

@@ -140,6 +140,29 @@ To migrate, update processor method names.
 > npx @mastra/codemod@latest v1/agent-processor-methods .
 > ```
 
+### Zod v3 and v4 structured output schemas remain supported
+
+Mastra v1 continues to accept both Zod v3 and Zod v4 schemas in public agent APIs that take structured output schemas. This includes methods such as `agent.generateLegacy()` and `agent.streamLegacy()` and the related option types.
+
+If you already pass Zod schemas to agent APIs, no migration is required for Zod version compatibility. Keep your existing schema imports:
+
+```ts
+import { z as z3 } from 'zod/v3'
+import { z as z4 } from 'zod/v4'
+
+await agent.generateLegacy({
+  prompt: 'Summarize this ticket',
+  output: z3.object({ summary: z3.string() }),
+})
+
+await agent.streamLegacy({
+  prompt: 'Extract contact info',
+  output: z4.object({ email: z4.string().email() }),
+})
+```
+
+Only update your imports if you want to standardize on one Zod version across your application.
+
 ### Default options method renames for AI SDK versions
 
 Default options methods have been renamed to clarify legacy (AI SDK v4) vs new (AI SDK v5+) APIs. This change helps developers understand which AI SDK version they're targeting.

package/.docs/models/gateways/openrouter.md

@@ -1,6 +1,6 @@
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 203 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 164 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -13,7 +13,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "openrouter/allenai/molmo-2-8b:free"
+  model: "openrouter/anthropic/claude-3.5-haiku"
 });
 ```
 
@@ -34,7 +34,6 @@ ANTHROPIC_API_KEY=ant-...
 
 | Model                                                           |
 | --------------------------------------------------------------- |
-| `allenai/molmo-2-8b:free`                                       |
 | `anthropic/claude-3.5-haiku`                                    |
 | `anthropic/claude-3.7-sonnet`                                   |
 | `anthropic/claude-haiku-4.5`                                    |
@@ -53,23 +52,14 @@ ANTHROPIC_API_KEY=ant-...
 | `black-forest-labs/flux.2-pro`                                  |
 | `bytedance-seed/seedream-4.5`                                   |
 | `cognitivecomputations/dolphin-mistral-24b-venice-edition:free` |
-| `cognitivecomputations/dolphin3.0-mistral-24b`                  |
-| `cognitivecomputations/dolphin3.0-r1-mistral-24b`               |
 | `deepseek/deepseek-chat-v3-0324`                                |
 | `deepseek/deepseek-chat-v3.1`                                   |
-| `deepseek/deepseek-r1-0528-qwen3-8b:free`                       |
-| `deepseek/deepseek-r1-0528:free`                                |
 | `deepseek/deepseek-r1-distill-llama-70b`                        |
-| `deepseek/deepseek-r1-distill-qwen-14b`                         |
-| `deepseek/deepseek-r1:free`                                     |
-| `deepseek/deepseek-v3-base:free`                                |
 | `deepseek/deepseek-v3.1-terminus`                               |
 | `deepseek/deepseek-v3.1-terminus:exacto`                        |
 | `deepseek/deepseek-v3.2`                                        |
 | `deepseek/deepseek-v3.2-speciale`                               |
-| `featherless/qwerky-72b`                                        |
 | `google/gemini-2.0-flash-001`                                   |
-| `google/gemini-2.0-flash-exp:free`                              |
 | `google/gemini-2.5-flash`                                       |
 | `google/gemini-2.5-flash-lite`                                  |
 | `google/gemini-2.5-flash-lite-preview-09-2025`                  |
@@ -95,15 +85,11 @@ ANTHROPIC_API_KEY=ant-...
 | `inception/mercury`                                             |
 | `inception/mercury-2`                                           |
 | `inception/mercury-coder`                                       |
-| `kwaipilot/kat-coder-pro:free`                                  |
 | `liquid/lfm-2.5-1.2b-instruct:free`                             |
 | `liquid/lfm-2.5-1.2b-thinking:free`                             |
-| `meta-llama/llama-3.1-405b-instruct:free`                       |
 | `meta-llama/llama-3.2-11b-vision-instruct`                      |
 | `meta-llama/llama-3.2-3b-instruct:free`                         |
 | `meta-llama/llama-3.3-70b-instruct:free`                        |
-| `meta-llama/llama-4-scout:free`                                 |
-| `microsoft/mai-ds-r1:free`                                      |
 | `minimax/minimax-01`                                            |
 | `minimax/minimax-m1`                                            |
 | `minimax/minimax-m2`                                            |
@@ -112,30 +98,25 @@ ANTHROPIC_API_KEY=ant-...
 | `minimax/minimax-m2.7`                                          |
 | `mistralai/codestral-2508`                                      |
 | `mistralai/devstral-2512`                                       |
-| `mistralai/devstral-2512:free`                                  |
 | `mistralai/devstral-medium-2507`                                |
 | `mistralai/devstral-small-2505`                                 |
-| `mistralai/devstral-small-2505:free`                            |
 | `mistralai/devstral-small-2507`                                 |
-| `mistralai/mistral-7b-instruct:free`                            |
 | `mistralai/mistral-medium-3`                                    |
 | `mistralai/mistral-medium-3.1`                                  |
-| `mistralai/mistral-nemo:free`                                   |
 | `mistralai/mistral-small-3.1-24b-instruct`                      |
 | `mistralai/mistral-small-3.2-24b-instruct`                      |
-| `mistralai/mistral-small-3.2-24b-instruct:free`                 |
-| `moonshotai/kimi-dev-72b:free`                                  |
 | `moonshotai/kimi-k2`                                            |
 | `moonshotai/kimi-k2-0905`                                       |
 | `moonshotai/kimi-k2-0905:exacto`                                |
 | `moonshotai/kimi-k2-thinking`                                   |
 | `moonshotai/kimi-k2:free`                                       |
 | `moonshotai/kimi-k2.5`                                          |
-| `nousresearch/deephermes-3-llama-3-8b-preview`                  |
 | `nousresearch/hermes-3-llama-3.1-405b:free`                     |
 | `nousresearch/hermes-4-405b`                                    |
 | `nousresearch/hermes-4-70b`                                     |
 | `nvidia/nemotron-3-nano-30b-a3b:free`                           |
+| `nvidia/nemotron-3-super-120b-a12b`                             |
+| `nvidia/nemotron-3-super-120b-a12b-free`                        |
 | `nvidia/nemotron-nano-12b-v2-vl:free`                           |
 | `nvidia/nemotron-nano-9b-v2`                                    |
 | `nvidia/nemotron-nano-9b-v2:free`                               |
@@ -170,29 +151,15 @@ ANTHROPIC_API_KEY=ant-...
 | `openai/gpt-oss-20b:free`                                       |
 | `openai/gpt-oss-safeguard-20b`                                  |
 | `openai/o4-mini`                                                |
-| `openrouter/aurora-alpha`                                       |
 | `openrouter/free`                                               |
-| `openrouter/healer-alpha`                                       |
-| `openrouter/hunter-alpha`                                       |
-| `openrouter/sherlock-dash-alpha`                                |
-| `openrouter/sherlock-think-alpha`                               |
 | `prime-intellect/intellect-3`                                   |
 | `qwen/qwen-2.5-coder-32b-instruct`                              |
-| `qwen/qwen-2.5-vl-7b-instruct:free`                             |
-| `qwen/qwen2.5-vl-32b-instruct:free`                             |
 | `qwen/qwen2.5-vl-72b-instruct`                                  |
-| `qwen/qwen2.5-vl-72b-instruct:free`                             |
-| `qwen/qwen3-14b:free`                                           |
 | `qwen/qwen3-235b-a22b-07-25`                                    |
-| `qwen/qwen3-235b-a22b-07-25:free`                               |
 | `qwen/qwen3-235b-a22b-thinking-2507`                            |
-| `qwen/qwen3-235b-a22b:free`                                     |
 | `qwen/qwen3-30b-a3b-instruct-2507`                              |
 | `qwen/qwen3-30b-a3b-thinking-2507`                              |
-| `qwen/qwen3-30b-a3b:free`                                       |
-| `qwen/qwen3-32b:free`                                           |
 | `qwen/qwen3-4b:free`                                            |
-| `qwen/qwen3-8b:free`                                            |
 | `qwen/qwen3-coder`                                              |
 | `qwen/qwen3-coder-30b-a3b-instruct`                             |
 | `qwen/qwen3-coder-flash`                                        |
@@ -204,17 +171,11 @@ ANTHROPIC_API_KEY=ant-...
 | `qwen/qwen3-next-80b-a3b-thinking`                              |
 | `qwen/qwen3.5-397b-a17b`                                        |
 | `qwen/qwen3.5-plus-02-15`                                       |
-| `qwen/qwq-32b:free`                                             |
-| `rekaai/reka-flash-3`                                           |
-| `sarvamai/sarvam-m:free`                                        |
 | `sourceful/riverflow-v2-fast-preview`                           |
 | `sourceful/riverflow-v2-max-preview`                            |
 | `sourceful/riverflow-v2-standard-preview`                       |
 | `stepfun/step-3.5-flash`                                        |
 | `stepfun/step-3.5-flash:free`                                   |
-| `thudm/glm-z1-32b:free`                                         |
-| `tngtech/deepseek-r1t2-chimera:free`                            |
-| `tngtech/tng-r1t-chimera:free`                                  |
 | `x-ai/grok-3`                                                   |
 | `x-ai/grok-3-beta`                                              |
 | `x-ai/grok-3-mini`                                              |

package/.docs/models/gateways/vercel.md

@@ -1,6 +1,6 @@
 # ![Vercel logo](https://models.dev/logos/vercel.svg)Vercel
 
-Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 219 models through Mastra's model router.
+Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 224 models through Mastra's model router.
 
 Learn more in the [Vercel documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
 
@@ -108,6 +108,7 @@ ANTHROPIC_API_KEY=ant-...
 | `google/gemini-3.1-flash-lite-preview`         |
 | `google/gemini-3.1-pro-preview`                |
 | `google/gemini-embedding-001`                  |
+| `google/gemini-embedding-2`                    |
 | `google/imagen-4.0-fast-generate-001`          |
 | `google/imagen-4.0-generate-001`               |
 | `google/imagen-4.0-ultra-generate-001`         |
@@ -235,13 +236,17 @@ ANTHROPIC_API_KEY=ant-...
 | `xai/grok-4-fast-reasoning`                    |
 | `xai/grok-4.1-fast-non-reasoning`              |
 | `xai/grok-4.1-fast-reasoning`                  |
+| `xai/grok-4.20-multi-agent`                    |
 | `xai/grok-4.20-multi-agent-beta`               |
+| `xai/grok-4.20-non-reasoning`                  |
 | `xai/grok-4.20-non-reasoning-beta`             |
+| `xai/grok-4.20-reasoning`                      |
 | `xai/grok-4.20-reasoning-beta`                 |
 | `xai/grok-code-fast-1`                         |
 | `xai/grok-imagine-image`                       |
 | `xai/grok-imagine-image-pro`                   |
 | `xiaomi/mimo-v2-flash`                         |
+| `xiaomi/mimo-v2-pro`                           |
 | `zai/glm-4.5`                                  |
 | `zai/glm-4.5-air`                              |
 | `zai/glm-4.5v`                                 |

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 3396 models from 94 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3388 models from 94 providers through a single API.
 
 ## Features
 
@@ -232,7 +232,11 @@ Your users never experience the disruption - the response comes back with the sa
 
 Mastra also supports local models like `gpt-oss`, `Qwen3`, `DeepSeek` and many more that you run on your own hardware. The application running your local model needs to provide an OpenAI-compatible API server for Mastra to connect to. We recommend using [LMStudio](https://lmstudio.ai/) (see [Running the LMStudio server](https://lmstudio.ai/docs/developer/core/server)).
 
-For a custom provider the `id` (`${providerId}/${modelId}`) is required but it will only be used for display purposes. The `modelId` needs to be the actual model you want to use. An example would be: `custom/my-qwen3-model`.
+For custom OpenAI-compatible endpoints, `id` is the routing form that Mastra sends through the model router.
+
+Use `provider/model` when the remote behaves like a direct provider and expects a bare model name such as `llama3.2`.
+
+Use `gateway/provider/model` when the remote behaves like a model gateway and the upstream model namespace includes the provider, such as `mastra/google/gemini-2.5-flash` or `openrouter/google/gemini-2.5-flash`.
 
 For the `url` it's **important** that you use the base URL of the OpenAI-compatible endpoint with Mastra's `model` setting and not the individual chat endpoints.
 
@@ -250,6 +254,22 @@ const agent = new Agent({
 })
 ```
 
+If the remote behaves like a model gateway, include the gateway prefix in `id`:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: {
+    id: "mastra/google/gemini-2.5-flash",
+    url: "http://your-custom-openai-compatible-endpoint.com/v1"
+  }
+})
+```
+
 ### Example: LMStudio
 
 After starting the LMStudio server, the local server is available at `http://localhost:1234` and it provides endpoints like `/v1/models`, `/v1/chat/completions`, etc. The `url` will be `http://localhost:1234/v1`. For the `id` you can use (`lmstudio/${modelId}`) which will be displayed in the LMStudio interface.

package/.docs/models/providers/baseten.md

@@ -38,7 +38,7 @@ for await (const chunk of stream) {
 | `baseten/deepseek-ai/DeepSeek-V3.1`    | 164K    |       |           |       |       |       | $0.50      | $2          |
 | `baseten/MiniMaxAI/MiniMax-M2.5`       | 204K    |       |           |       |       |       | $0.30      | $1          |
 | `baseten/moonshotai/Kimi-K2.5`         | 262K    |       |           |       |       |       | $0.60      | $3          |
-| `baseten/nvidia/Nemotron-3-Super`      | 262K    |       |           |       |       |       | $0.30      | $0.75       |
+| `baseten/nvidia/Nemotron-120B-A12B`    | 262K    |       |           |       |       |       | $0.30      | $0.75       |
 | `baseten/openai/gpt-oss-120b`          | 128K    |       |           |       |       |       | $0.10      | $0.50       |
 | `baseten/zai-org/GLM-4.6`              | 200K    |       |           |       |       |       | $0.60      | $2          |
 | `baseten/zai-org/GLM-4.7`              | 205K    |       |           |       |       |       | $0.60      | $2          |

package/.docs/models/providers/cortecs.md

@@ -1,6 +1,6 @@
 # ![Cortecs logo](https://models.dev/logos/cortecs.svg)Cortecs
 
-Access 23 Cortecs models through Mastra's model router. Authentication is handled automatically using the `CORTECS_API_KEY` environment variable.
+Access 28 Cortecs models through Mastra's model router. Authentication is handled automatically using the `CORTECS_API_KEY` environment variable.
 
 Learn more in the [Cortecs documentation](https://cortecs.ai).
 
@@ -35,6 +35,10 @@ for await (const chunk of stream) {
 | Model                                    | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | ---------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
 | `cortecs/claude-4-5-sonnet`              | 200K    |       |           |       |       |       | $3         | $16         |
+| `cortecs/claude-4-6-sonnet`              | 1.0M    |       |           |       |       |       | $4         | $18         |
+| `cortecs/claude-haiku-4-5`               | 200K    |       |           |       |       |       | $1         | $5          |
+| `cortecs/claude-opus4-5`                 | 200K    |       |           |       |       |       | $6         | $30         |
+| `cortecs/claude-opus4-6`                 | 1.0M    |       |           |       |       |       | $6         | $30         |
 | `cortecs/claude-sonnet-4`                | 200K    |       |           |       |       |       | $3         | $17         |
 | `cortecs/deepseek-v3-0324`               | 128K    |       |           |       |       |       | $0.55      | $2          |
 | `cortecs/devstral-2512`                  | 262K    |       |           |       |       |       | —          | —           |
@@ -53,6 +57,7 @@ for await (const chunk of stream) {
 | `cortecs/llama-3.1-405b-instruct`        | 128K    |       |           |       |       |       | —          | —           |
 | `cortecs/minimax-m2`                     | 400K    |       |           |       |       |       | $0.39      | $2          |
 | `cortecs/minimax-m2.1`                   | 196K    |       |           |       |       |       | $0.34      | $1          |
+| `cortecs/minimax-m2.5`                   | 197K    |       |           |       |       |       | $0.32      | $1          |
 | `cortecs/nova-pro-v1`                    | 300K    |       |           |       |       |       | $1         | $4          |
 | `cortecs/qwen3-32b`                      | 16K     |       |           |       |       |       | $0.10      | $0.33       |
 | `cortecs/qwen3-coder-480b-a35b-instruct` | 262K    |       |           |       |       |       | $0.44      | $2          |

package/.docs/models/providers/fastrouter.md

@@ -1,6 +1,6 @@
 # ![FastRouter logo](https://models.dev/logos/fastrouter.svg)FastRouter
 
-Access 14 FastRouter models through Mastra's model router. Authentication is handled automatically using the `FASTROUTER_API_KEY` environment variable.
+Access 15 FastRouter models through Mastra's model router. Authentication is handled automatically using the `FASTROUTER_API_KEY` environment variable.
 
 Learn more in the [FastRouter documentation](https://fastrouter.ai/models).
 
@@ -48,6 +48,7 @@ for await (const chunk of stream) {
 | `fastrouter/openai/gpt-oss-20b`                        | 131K    |       |           |       |       |       | $0.05      | $0.20       |
 | `fastrouter/qwen/qwen3-coder`                          | 262K    |       |           |       |       |       | $0.30      | $1          |
 | `fastrouter/x-ai/grok-4`                               | 256K    |       |           |       |       |       | $3         | $15         |
+| `fastrouter/z-ai/glm-5`                                | 205K    |       |           |       |       |       | $0.95      | $3          |
 
 ## Advanced configuration
 
@@ -77,7 +78,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "fastrouter/x-ai/grok-4"
+      ? "fastrouter/z-ai/glm-5"
       : "fastrouter/anthropic/claude-opus-4.1";
   }
 });

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

@@ -1,6 +1,6 @@
 # ![Fireworks AI logo](https://models.dev/logos/fireworks-ai.svg)Fireworks AI
 
-Access 13 Fireworks AI models through Mastra's model router. Authentication is handled automatically using the `FIREWORKS_API_KEY` environment variable.
+Access 14 Fireworks AI models through Mastra's model router. Authentication is handled automatically using the `FIREWORKS_API_KEY` environment variable.
 
 Learn more in the [Fireworks AI documentation](https://fireworks.ai/docs/).
 
@@ -47,6 +47,7 @@ for await (const chunk of stream) {
 | `fireworks-ai/accounts/fireworks/models/kimi-k2p5`        | 256K    |       |           |       |       |       | $0.60      | $3          |
 | `fireworks-ai/accounts/fireworks/models/minimax-m2p1`     | 200K    |       |           |       |       |       | $0.30      | $1          |
 | `fireworks-ai/accounts/fireworks/models/minimax-m2p5`     | 197K    |       |           |       |       |       | $0.30      | $1          |
+| `fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo` | 256K    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -76,7 +77,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "fireworks-ai/accounts/fireworks/models/minimax-m2p5"
+      ? "fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo"
       : "fireworks-ai/accounts/fireworks/models/deepseek-v3p1";
   }
 });

package/.docs/models/providers/nano-gpt.md

@@ -1,6 +1,6 @@
 # ![NanoGPT logo](https://models.dev/logos/nano-gpt.svg)NanoGPT
 
-Access 516 NanoGPT models through Mastra's model router. Authentication is handled automatically using the `NANO_GPT_API_KEY` environment variable.
+Access 517 NanoGPT models through Mastra's model router. Authentication is handled automatically using the `NANO_GPT_API_KEY` environment variable.
 
 Learn more in the [NanoGPT documentation](https://docs.nano-gpt.com).
 
@@ -335,6 +335,7 @@ for await (const chunk of stream) {
 | `nano-gpt/minimax/minimax-m2-her`                                   | 66K     |       |           |       |       |       | $0.30      | $1          |
 | `nano-gpt/minimax/minimax-m2.1`                                     | 200K    |       |           |       |       |       | $0.33      | $1          |
 | `nano-gpt/minimax/minimax-m2.5`                                     | 205K    |       |           |       |       |       | $0.30      | $1          |
+| `nano-gpt/minimax/minimax-m2.7`                                     | 205K    |       |           |       |       |       | $0.30      | $1          |
 | `nano-gpt/MiniMaxAI/MiniMax-M1-80k`                                 | 1.0M    |       |           |       |       |       | $0.61      | $2          |
 | `nano-gpt/miromind-ai/mirothinker-v1.5-235b`                        | 33K     |       |           |       |       |       | $0.30      | $1          |
 | `nano-gpt/Mistral-Nemo-12B-Instruct-2407`                           | 16K     |       |           |       |       |       | $0.01      | $0.01       |