@mastra/mcp-docs-server 1.2.8-alpha.2 → 1.2.8-alpha.5

package/.docs/docs/agents/structured-output.md

@@ -197,9 +197,9 @@ If your tools aren't being called when structured output is enabled, or you rece
 
 When your model doesn't support tools and structured output together, you have three options:
 
-1. **Use `jsonPromptInjection: true`** - Injects the schema into the prompt instead of using the API's `response_format` parameter
-2. **Use a separate structuring model** - Pass a `model` to `structuredOutput` to use a second LLM for structuring
-3. **Use `prepareStep`** - Handle tools and structured output in separate steps
+1. **Use `jsonPromptInjection`**: Set it to `'auto'` to select native structured output when supported and inline prompt injection otherwise, or choose an explicit injection mode
+2. **Use a separate structuring model**: Pass a `model` to `structuredOutput` to use a second LLM for structuring
+3. **Use `prepareStep`**: Handle tools and structured output in separate steps
 
 Each approach is detailed in the sections below.
 
@@ -209,9 +209,7 @@ Structured output support varies across LLMs due to differences in their APIs. T
 
 ### `jsonPromptInjection`
 
-By default, Mastra passes the schema to the model provider using the `response_format` API parameter. Most model providers have built-in support for this, which reliably enforces the schema.
-
-If your model provider doesn't support `response_format`, you'll get an error from the API. When this happens, set `jsonPromptInjection: true`. This adds the schema to the system prompt instead, instructing the model to output JSON. This is less reliable than the API parameter approach.
+By default, Mastra passes the schema to the model provider using the `response_format` API parameter. Set `jsonPromptInjection: 'auto'` to let Mastra choose the mode from its model capability data. Mastra uses native structured output for supported models and inline prompt injection for unsupported models or models without capability data.
 
 ```typescript
 import { z } from 'zod'
@@ -224,13 +222,20 @@ const response = await testAgent.generate('Help me plan my day.', {
         activities: z.array(z.string()),
       }),
     ),
-    jsonPromptInjection: true,
+    jsonPromptInjection: 'auto',
   },
 })
 
 console.log(response.object)
 ```
 
+Use an explicit mode when you need to override the capability-based choice:
+
+- `false` or omitted: Use the provider's native structured output.
+- `'inline'`: Add the schema instructions to the latest user message.
+- `true` or `'system'`: Add the schema instructions to the system message.
+- `'auto'`: Use native structured output when the model supports it. Otherwise, use inline prompt injection.
+
 > **Gemini 2.5 with tools:** Gemini 2.5 models don't support combining `response_format` (structured output) with function calling (tools) in the same API call. If your agent has tools and you're using `structuredOutput` with a Gemini 2.5 model, you must set `jsonPromptInjection: true` to avoid the error `Function calling with a response mime type: 'application/json' is unsupported`.
 >
 > ```typescript

package/.docs/docs/evals/multi-turn.md

@@ -0,0 +1,178 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Multi-turn evals
+
+Multi-turn evals test agent behavior across a conversation. Instead of a single `input`, you provide an `inputs` array. Each entry is sent sequentially to the agent on the same thread, and scorers see the accumulated output from all turns.
+
+## When to use multi-turn evals
+
+- The agent uses memory and must recall context from earlier turns
+- The agent handles follow-up questions that depend on prior responses
+- You need to verify tool-call sequences across a conversation
+- The agent runs a multi-step workflow (search, confirm, execute)
+
+## Quickstart
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { checks } from '@mastra/evals/checks'
+import { weatherAgent } from '../agents'
+
+const result = await runEvals({
+  data: [
+    {
+      inputs: [
+        'What is the weather in Brooklyn?',
+        'What about tomorrow?',
+        'Compare the two forecasts.',
+      ],
+    },
+  ],
+  target: weatherAgent,
+  scorers: [checks.calledTool('get_weather', { times: 2 }), checks.includes('Brooklyn')],
+})
+```
+
+Each turn runs `agent.generate()` with the same thread ID, so the agent sees the full conversation history. Scorers receive the accumulated output messages from all turns.
+
+## Memory is required for cross-turn recall
+
+Multi-turn recall depends on the agent having a **memory store configured**. The shared thread ID is what lets each turn see the earlier ones — but a thread only persists history when the agent has memory. If the agent has no memory configured, the turns still run sequentially and their outputs still accumulate for scoring, but the agent will not recall earlier turns (each input runs in isolation). `runEvals` logs a warning when you use `inputs` on an agent without memory.
+
+`runEvals` manages the conversation identity for you: it generates the shared `threadId` and injects a `resourceId` (Mastra memory scopes messages by resource + thread, so both are required for recall to work). By default the resource is derived from the generated thread so each conversation is isolated. To pin a specific resource — for example to reuse an existing user's memory — pass `targetOptions.memory.resource`; `runEvals` still owns the thread, so you don't provide one:
+
+```typescript
+await runEvals({
+  target: weatherAgent,
+  data: [{ inputs: ['What is the weather in Brooklyn?', 'What about tomorrow?'] }],
+  scorers: [checks.similarity('weather forecast')],
+  targetOptions: { memory: { resource: 'user-42' } },
+})
+```
+
+See [Memory](https://mastra.ai/docs/memory/overview) for how to configure a memory store.
+
+## How it works
+
+When a data item has an `inputs` array, `runEvals`:
+
+1. Creates a fresh thread (unique `threadId`) and resource for the conversation (a caller-provided `targetOptions.memory.resource` is preserved)
+2. Sends each input sequentially via `agent.generate()` on that thread
+3. Accumulates all output messages across turns
+4. Passes the full accumulated output to scorers for evaluation
+
+Scorers see the complete conversation output, not just the last turn.
+
+## Scoring semantics
+
+Two details matter when writing scorers for multi-turn items:
+
+- **`run.output` is the accumulated output from every turn.** Output-based scorers — `checks.includes`, `checks.calledTool`, `checks.similarity`, and similar — evaluate the whole conversation. For example, `checks.calledTool('get_weather', { times: 2 })` counts calls across all turns.
+- **`run.input` is only the first turn's input.** Scorers that compare input against output (faithfulness, answer relevancy, and other input-relative LLM scorers) only see the first user message, not the full conversation. Prefer output-based checks for multi-turn, or build scorers that read the accumulated `run.output` directly.
+
+## Per-turn assertions with `turns`
+
+The `inputs` form scores the **accumulated** output holistically — a single score over every turn's output. That can hide per-turn failures: an output-based check like `checks.includes('Brooklyn')` passes if _any_ turn mentions Brooklyn, even when the follow-up turn is broken.
+
+When you need to assert that a **specific turn** behaved correctly, use `turns` instead. Each turn is an object with its own `input` and optional `gates`/`scorers` that evaluate **only that turn's** input and output:
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { checks } from '@mastra/evals/checks'
+import { weatherAgent } from '../agents'
+
+const result = await runEvals({
+  data: [
+    {
+      turns: [
+        {
+          input: 'What is the weather in Brooklyn?',
+          gates: [checks.calledTool('get_weather')],
+        },
+        {
+          // The follow-up must call the tool again — it can't be satisfied
+          // by the first turn's tool call.
+          input: 'What about tomorrow?',
+          gates: [checks.calledTool('get_weather')],
+          scorers: [{ scorer: checks.similarity('tomorrow forecast'), threshold: 0.5 }],
+        },
+      ],
+    },
+  ],
+  target: weatherAgent,
+})
+
+result.verdict // 'passed' | 'scored' | 'failed'
+result.turnResults // per-turn gate/threshold/scorer outcomes
+```
+
+Semantics:
+
+- A per-turn gate or scorer sees **only that turn's** `run.input` and `run.output` — never the accumulated conversation. This fixes both blind spots of `inputs`: the wrong turn can't satisfy a check, and `run.input` is correct for each turn.
+- Per-turn outcomes fold into the overall [verdict](https://mastra.ai/docs/evals/gates-and-verdicts): a failing turn gate makes the verdict `failed`; a missed turn threshold (with gates passing) makes it `scored`.
+- `result.turnResults[i]` reports each turn's `gateResults`, `thresholdResults`, and `scores`, so a failure points at the exact turn. Across multiple conversations, turn results are averaged by turn index.
+- A turn with no `gates`/`scorers` just advances the conversation.
+- Top-level `scorers`/`gates` still run holistically over the accumulated output, so you can combine "this turn must call the tool" with "the overall answer mentions Brooklyn."
+- When the agent has storage configured, each per-turn scorer/gate result is persisted like top-level scores, so per-turn outcomes appear in your scores store.
+
+Use `inputs` when a single holistic score over the whole conversation is enough; use `turns` when correctness depends on individual turns. `turns` cannot be combined with `input` or `inputs` in the same data item.
+
+## Combining with gates and thresholds
+
+Multi-turn data items work with [gates and verdicts](https://mastra.ai/docs/evals/gates-and-verdicts). Use output-based scorers so gating reflects the full conversation:
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { checks } from '@mastra/evals/checks'
+
+const result = await runEvals({
+  data: [
+    {
+      inputs: ['My favorite city is Brooklyn.', 'What is the weather in my favorite city?'],
+    },
+  ],
+  target: weatherAgent,
+  gates: [checks.calledTool('get_weather')],
+  scorers: [{ scorer: checks.similarity('Brooklyn weather forecast'), threshold: 0.5 }],
+})
+
+result.verdict // 'passed' | 'scored' | 'failed'
+```
+
+## Mixing single-turn and multi-turn
+
+A single `runEvals` call can include both single-turn and multi-turn data items:
+
+```typescript
+const result = await runEvals({
+  data: [
+    { input: 'What is the weather in Brooklyn?' },
+    {
+      inputs: ['My favorite city is Brooklyn.', 'What is the weather in my favorite city?'],
+    },
+  ],
+  target: weatherAgent,
+  scorers: [checks.includes('Brooklyn')],
+})
+```
+
+Single-turn items use `input` as usual. Multi-turn items use `inputs` — `input` can be omitted entirely.
+
+## Validation
+
+`runEvals` throws a `MastraError` if `inputs` is present but empty:
+
+```typescript
+// Throws: 'inputs' must be a non-empty array
+await runEvals({
+  data: [{ inputs: [] }],
+  target: myAgent,
+  scorers: [myScorer],
+})
+```
+
+## Related
+
+- [`runEvals()` reference](https://mastra.ai/reference/evals/run-evals): Full API for `runEvals` parameters and returns
+- [Gates and verdicts](https://mastra.ai/docs/evals/gates-and-verdicts): Enforce hard requirements and quality thresholds
+- [Quick Checks](https://mastra.ai/docs/evals/quick-checks): Zero-LLM composable micro-scorers

package/.docs/docs/evals/overview.md

@@ -142,6 +142,7 @@ Once registered, you can score traces interactively within Studio under the **Ob
 
 - Use [Quick Checks](https://mastra.ai/docs/evals/quick-checks) for fast, deterministic assertions on text and tool usage
 - Add [gates and verdicts](https://mastra.ai/docs/evals/gates-and-verdicts) to enforce hard requirements and quality thresholds
+- Test [multi-turn conversations](https://mastra.ai/docs/evals/multi-turn) where behavior emerges across sequential turns
 - Learn how to create your own scorers in the [Creating Custom Scorers](https://mastra.ai/docs/evals/custom-scorers) guide
 - Explore built-in scorers in the [Built-in Scorers](https://mastra.ai/docs/evals/built-in-scorers) section
 - Test scorers with [Studio](https://mastra.ai/docs/studio/overview)

package/.docs/docs/mcp/overview.md

@@ -64,7 +64,7 @@ export const testMcpClient = new MCPClient({
 
 Visit [MCPClient](https://mastra.ai/reference/tools/mcp-client) for a full list of configuration options.
 
-> **Authentication:** For connecting to OAuth-protected MCP servers, see the [OAuth Authentication](https://mastra.ai/reference/tools/mcp-client) section.
+> **Authentication:** For connecting to OAuth-protected MCP servers — including completing the browser-based authorization flow with `authenticate()` — see the [OAuth Authentication](https://mastra.ai/reference/tools/mcp-client) section.
 
 ## Using `MCPClient` with an agent
 

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

@@ -247,6 +247,8 @@ auth: {
 }
 ```
 
+When the resource ID is derived this way, clients can omit `memory.resource` from agent generate and stream request bodies — the server-derived value is used instead (and always takes precedence over any client-provided value). If a request uses memory and neither the body nor the request context provides a resource ID, the server responds with a 400 error.
+
 You can also set these keys manually in middleware:
 
 ```typescript

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

@@ -2,7 +2,7 @@
 
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 342 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 341 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -73,7 +73,6 @@ ANTHROPIC_API_KEY=ant-...
 | `anthropic/claude-sonnet-4.5`                                   |
 | `anthropic/claude-sonnet-4.6`                                   |
 | `anthropic/claude-sonnet-5`                                     |
-| `arcee-ai/coder-large`                                          |
 | `arcee-ai/trinity-large-thinking`                               |
 | `arcee-ai/virtuoso-large`                                       |
 | `baidu/ernie-4.5-vl-424b-a47b`                                  |

package/.docs/models/index.md

@@ -2,7 +2,7 @@
 
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4867 models from 155 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4844 models from 155 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/google.md

@@ -49,8 +49,8 @@ for await (const chunk of stream) {
 | `google/gemini-3.1-pro-preview-customtools` | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `google/gemini-3.5-flash`                   | 1.0M    |       |           |       |       |       | $2         | $9          |
 | `google/gemini-embedding-001`               | 2K      |       |           |       |       |       | $0.15      | —           |
-| `google/gemini-flash-latest`                | 1.0M    |       |           |       |       |       | $0.30      | $3          |
-| `google/gemini-flash-lite-latest`           | 1.0M    |       |           |       |       |       | $0.10      | $0.40       |
+| `google/gemini-flash-latest`                | 1.0M    |       |           |       |       |       | $2         | $9          |
+| `google/gemini-flash-lite-latest`           | 1.0M    |       |           |       |       |       | $0.25      | $2          |
 | `google/gemini-omni-flash-preview`          | 131K    |       |           |       |       |       | $2         | $18         |
 | `google/gemma-4-26b-a4b-it`                 | 262K    |       |           |       |       |       | —          | —           |
 | `google/gemma-4-31b-it`                     | 262K    |       |           |       |       |       | —          | —           |

package/.docs/models/providers/kilo.md

@@ -39,7 +39,7 @@ for await (const chunk of stream) {
 | `kilo/~anthropic/claude-haiku-latest`                     | 200K    |       |           |       |       |       | $1         | $5          |
 | `kilo/~anthropic/claude-opus-latest`                      | 1.0M    |       |           |       |       |       | $5         | $25         |
 | `kilo/~anthropic/claude-sonnet-latest`                    | 1.0M    |       |           |       |       |       | $3         | $15         |
-| `kilo/~google/gemini-flash-latest`                        | 1.0M    |       |           |       |       |       | $0.50      | $3          |
+| `kilo/~google/gemini-flash-latest`                        | 1.0M    |       |           |       |       |       | $2         | $9          |
 | `kilo/~google/gemini-pro-latest`                          | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `kilo/~moonshotai/kimi-latest`                            | 262K    |       |           |       |       |       | $0.74      | $3          |
 | `kilo/~openai/gpt-latest`                                 | 1.1M    |       |           |       |       |       | $5         | $30         |

package/.docs/models/providers/kimi-for-coding.md

@@ -2,7 +2,7 @@
 
 # ![Kimi For Coding logo](https://models.dev/logos/kimi-for-coding.svg)Kimi For Coding
 
-Access 4 Kimi For Coding models through Mastra's model router. Authentication is handled automatically using the `KIMI_API_KEY` environment variable.
+Access 5 Kimi For Coding models through Mastra's model router. Authentication is handled automatically using the `KIMI_API_KEY` environment variable.
 
 Learn more in the [Kimi For Coding documentation](https://www.kimi.com/code/docs/en/third-party-tools/other-coding-agents.html).
 
@@ -34,12 +34,13 @@ for await (const chunk of stream) {
 
 ## Models
 
-| Model                              | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
-| ---------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `kimi-for-coding/k2p5`             | 262K    |       |           |       |       |       | —          | —           |
-| `kimi-for-coding/k2p6`             | 262K    |       |           |       |       |       | —          | —           |
-| `kimi-for-coding/k2p7`             | 262K    |       |           |       |       |       | —          | —           |
-| `kimi-for-coding/kimi-k2-thinking` | 262K    |       |           |       |       |       | —          | —           |
+| Model                                       | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `kimi-for-coding/k2p5`                      | 262K    |       |           |       |       |       | —          | —           |
+| `kimi-for-coding/k2p6`                      | 262K    |       |           |       |       |       | —          | —           |
+| `kimi-for-coding/k2p7`                      | 262K    |       |           |       |       |       | —          | —           |
+| `kimi-for-coding/kimi-for-coding-highspeed` | 262K    |       |           |       |       |       | —          | —           |
+| `kimi-for-coding/kimi-k2-thinking`          | 262K    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 

package/.docs/models/providers/llmgateway.md

@@ -2,7 +2,7 @@
 
 # ![LLM Gateway logo](https://models.dev/logos/llmgateway.svg)LLM Gateway
 
-Access 176 LLM Gateway models through Mastra's model router. Authentication is handled automatically using the `LLMGATEWAY_API_KEY` environment variable.
+Access 170 LLM Gateway models through Mastra's model router. Authentication is handled automatically using the `LLMGATEWAY_API_KEY` environment variable.
 
 Learn more in the [LLM Gateway documentation](https://llmgateway.io/docs).
 
@@ -53,7 +53,6 @@ for await (const chunk of stream) {
 | `llmgateway/claude-sonnet-5`                   | 1.0M    |       |           |       |       |       | $2         | $10         |
 | `llmgateway/codestral-2508`                    | 256K    |       |           |       |       |       | $0.30      | $0.90       |
 | `llmgateway/custom`                            | 128K    |       |           |       |       |       | —          | —           |
-| `llmgateway/deepseek-v3.1`                     | 128K    |       |           |       |       |       | $0.56      | $2          |
 | `llmgateway/deepseek-v3.2`                     | 164K    |       |           |       |       |       | $0.26      | $0.38       |
 | `llmgateway/deepseek-v4-flash`                 | 1.1M    |       |           |       |       |       | $0.14      | $0.28       |
 | `llmgateway/deepseek-v4-pro`                   | 1.1M    |       |           |       |       |       | $0.43      | $0.87       |
@@ -135,7 +134,6 @@ for await (const chunk of stream) {
 | `llmgateway/kimi-k2.7-code`                    | 262K    |       |           |       |       |       | $0.95      | $4          |
 | `llmgateway/kimi-k2.7-code-highspeed`          | 262K    |       |           |       |       |       | $2         | $8          |
 | `llmgateway/llama-3-70b-instruct`              | 8K      |       |           |       |       |       | $0.51      | $0.74       |
-| `llmgateway/llama-3-8b-instruct`               | 8K      |       |           |       |       |       | $0.04      | $0.04       |
 | `llmgateway/llama-3.1-70b-instruct`            | 128K    |       |           |       |       |       | $0.72      | $0.72       |
 | `llmgateway/llama-3.1-nemotron-ultra-253b`     | 128K    |       |           |       |       |       | $0.60      | $2          |
 | `llmgateway/llama-3.2-11b-instruct`            | 128K    |       |           |       |       |       | $0.07      | $0.33       |
@@ -152,7 +150,7 @@ for await (const chunk of stream) {
 | `llmgateway/minimax-m2.5-highspeed`            | 205K    |       |           |       |       |       | $0.60      | $2          |
 | `llmgateway/minimax-m2.7`                      | 205K    |       |           |       |       |       | $0.30      | $1          |
 | `llmgateway/minimax-m2.7-highspeed`            | 205K    |       |           |       |       |       | $0.60      | $2          |
-| `llmgateway/minimax-m3`                        | 512K    |       |           |       |       |       | $0.60      | $2          |
+| `llmgateway/minimax-m3`                        | 524K    |       |           |       |       |       | $0.30      | $1          |
 | `llmgateway/minimax-text-01`                   | 1.0M    |       |           |       |       |       | $0.20      | $1          |
 | `llmgateway/ministral-14b-2512`                | 262K    |       |           |       |       |       | $0.20      | $0.20       |
 | `llmgateway/ministral-3b-2512`                 | 131K    |       |           |       |       |       | $0.10      | $0.10       |
@@ -166,7 +164,6 @@ for await (const chunk of stream) {
 | `llmgateway/o3`                                | 200K    |       |           |       |       |       | $2         | $8          |
 | `llmgateway/o3-mini`                           | 200K    |       |           |       |       |       | $1         | $4          |
 | `llmgateway/o4-mini`                           | 200K    |       |           |       |       |       | $1         | $4          |
-| `llmgateway/pixtral-large-latest`              | 128K    |       |           |       |       |       | $4         | $12         |
 | `llmgateway/qwen-coder-plus`                   | 131K    |       |           |       |       |       | $0.50      | $1          |
 | `llmgateway/qwen-flash`                        | 1.0M    |       |           |       |       |       | $0.05      | $0.40       |
 | `llmgateway/qwen-max`                          | 33K     |       |           |       |       |       | $2         | $6          |
@@ -181,7 +178,6 @@ for await (const chunk of stream) {
 | `llmgateway/qwen3-235b-a22b-thinking-2507`     | 262K    |       |           |       |       |       | $0.20      | $0.60       |
 | `llmgateway/qwen3-30b-a3b-instruct-2507`       | 262K    |       |           |       |       |       | $0.10      | $0.30       |
 | `llmgateway/qwen3-32b`                         | 33K     |       |           |       |       |       | $0.10      | $0.30       |
-| `llmgateway/qwen3-4b-fp8`                      | 128K    |       |           |       |       |       | $0.03      | $0.03       |
 | `llmgateway/qwen3-coder-30b-a3b-instruct`      | 262K    |       |           |       |       |       | $0.07      | $0.27       |
 | `llmgateway/qwen3-coder-480b-a35b-instruct`    | 262K    |       |           |       |       |       | $0.30      | $1          |
 | `llmgateway/qwen3-coder-flash`                 | 1.0M    |       |           |       |       |       | $0.30      | $2          |
@@ -193,8 +189,6 @@ for await (const chunk of stream) {
 | `llmgateway/qwen3-vl-235b-a22b-instruct`       | 131K    |       |           |       |       |       | $0.30      | $2          |
 | `llmgateway/qwen3-vl-235b-a22b-thinking`       | 131K    |       |           |       |       |       | $0.98      | $4          |
 | `llmgateway/qwen3-vl-30b-a3b-instruct`         | 131K    |       |           |       |       |       | $0.20      | $0.70       |
-| `llmgateway/qwen3-vl-30b-a3b-thinking`         | 131K    |       |           |       |       |       | $0.20      | $1          |
-| `llmgateway/qwen3-vl-8b-instruct`              | 131K    |       |           |       |       |       | $0.08      | $0.50       |
 | `llmgateway/qwen3-vl-flash`                    | 262K    |       |           |       |       |       | $0.05      | $0.40       |
 | `llmgateway/qwen3-vl-plus`                     | 262K    |       |           |       |       |       | $0.20      | $2          |
 | `llmgateway/qwen3.5-9b`                        | 262K    |       |           |       |       |       | $0.10      | $0.15       |

package/.docs/models/providers/ollama-cloud.md

@@ -2,7 +2,7 @@
 
 # ![Ollama Cloud logo](https://models.dev/logos/ollama-cloud.svg)Ollama Cloud
 
-Access 35 Ollama Cloud models through Mastra's model router. Authentication is handled automatically using the `OLLAMA_API_KEY` environment variable.
+Access 18 Ollama Cloud models through Mastra's model router. Authentication is handled automatically using the `OLLAMA_API_KEY` environment variable.
 
 Learn more in the [Ollama Cloud documentation](https://docs.ollama.com/cloud).
 
@@ -17,7 +17,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "ollama-cloud/deepseek-v3.1:671b"
+  model: "ollama-cloud/deepseek-v4-flash"
 });
 
 // Generate a response
@@ -34,43 +34,26 @@ for await (const chunk of stream) {
 
 ## Models
 
-| Model                                 | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
-| ------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `ollama-cloud/deepseek-v3.1:671b`     | 164K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/deepseek-v3.2`          | 164K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/deepseek-v4-flash`      | 1.0M    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/deepseek-v4-pro`        | 1.0M    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/devstral-2:123b`        | 262K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/devstral-small-2:24b`   | 262K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/gemini-3-flash-preview` | 1.0M    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/gemma3:12b`             | 131K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/gemma3:27b`             | 131K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/gemma3:4b`              | 131K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/gemma4:31b`             | 262K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/glm-4.7`                | 203K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/glm-5`                  | 203K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/glm-5.1`                | 203K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/glm-5.2`                | 976K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/gpt-oss:120b`           | 131K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/gpt-oss:20b`            | 131K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/kimi-k2.5`              | 262K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/kimi-k2.6`              | 262K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/kimi-k2.7-code`         | 262K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/minimax-m2.1`           | 205K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/minimax-m2.5`           | 205K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/minimax-m2.7`           | 197K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/minimax-m3`             | 512K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/ministral-3:14b`        | 262K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/ministral-3:3b`         | 262K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/ministral-3:8b`         | 262K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/mistral-large-3:675b`   | 262K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/nemotron-3-nano:30b`    | 1.0M    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/nemotron-3-super`       | 262K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/nemotron-3-ultra`       | 262K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/qwen3-coder-next`       | 262K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/qwen3-coder:480b`       | 262K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/qwen3.5:397b`           | 262K    |       |           |       |       |       | —          | —           |
-| `ollama-cloud/rnj-1:8b`               | 33K     |       |           |       |       |       | —          | —           |
+| Model                               | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ----------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `ollama-cloud/deepseek-v4-flash`    | 1.0M    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/deepseek-v4-pro`      | 1.0M    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/gemma4:31b`           | 262K    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/glm-5.1`              | 203K    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/glm-5.2`              | 976K    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/gpt-oss:120b`         | 131K    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/gpt-oss:20b`          | 131K    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/kimi-k2.5`            | 262K    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/kimi-k2.6`            | 262K    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/kimi-k2.7-code`       | 262K    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/minimax-m2.5`         | 205K    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/minimax-m2.7`         | 197K    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/minimax-m3`           | 512K    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/mistral-large-3:675b` | 262K    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/nemotron-3-nano:30b`  | 1.0M    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/nemotron-3-super`     | 262K    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/nemotron-3-ultra`     | 262K    |       |           |       |       |       | —          | —           |
+| `ollama-cloud/qwen3.5:397b`         | 262K    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -82,7 +65,7 @@ const agent = new Agent({
   name: "custom-agent",
   model: {
     url: "https://ollama.com/v1",
-    id: "ollama-cloud/deepseek-v3.1:671b",
+    id: "ollama-cloud/deepseek-v4-flash",
     apiKey: process.env.OLLAMA_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -100,8 +83,8 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "ollama-cloud/rnj-1:8b"
-      : "ollama-cloud/deepseek-v3.1:671b";
+      ? "ollama-cloud/qwen3.5:397b"
+      : "ollama-cloud/deepseek-v4-flash";
   }
 });
 ```

package/.docs/models/providers/orcarouter.md

@@ -57,7 +57,7 @@ for await (const chunk of stream) {
 | `orcarouter/google/gemini-3.1-flash-lite-preview`      | 1.0M    |       |           |       |       |       | $0.25      | $2          |
 | `orcarouter/google/gemini-3.1-pro-preview`             | 1.0M    |       |           |       |       |       | $4         | $18         |
 | `orcarouter/google/gemini-3.1-pro-preview-customtools` | 1.0M    |       |           |       |       |       | $4         | $18         |
-| `orcarouter/google/gemini-flash-latest`                | 1.0M    |       |           |       |       |       | $0.50      | $3          |
+| `orcarouter/google/gemini-flash-latest`                | 1.0M    |       |           |       |       |       | $2         | $9          |
 | `orcarouter/google/gemini-flash-lite-latest`           | 1.0M    |       |           |       |       |       | $0.25      | $2          |
 | `orcarouter/google/gemma-4-26b-a4b-it`                 | 262K    |       |           |       |       |       | $0.06      | $0.33       |
 | `orcarouter/google/gemma-4-31b-it`                     | 262K    |       |           |       |       |       | $0.13      | $0.38       |

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

@@ -17,7 +17,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "privatemode-ai/gemma-3-27b"
+  model: "privatemode-ai/gpt-oss-120b"
 });
 
 // Generate a response
@@ -34,13 +34,13 @@ for await (const chunk of stream) {
 
 ## Models
 
-| Model                                | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
-| ------------------------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `privatemode-ai/gemma-3-27b`         | 128K    |       |           |       |       |       | —          | —           |
-| `privatemode-ai/gpt-oss-120b`        | 128K    |       |           |       |       |       | —          | —           |
-| `privatemode-ai/qwen3-coder-30b-a3b` | 128K    |       |           |       |       |       | —          | —           |
-| `privatemode-ai/qwen3-embedding-4b`  | 32K     |       |           |       |       |       | —          | —           |
-| `privatemode-ai/whisper-large-v3`    | —       |       |           |       |       |       | —          | —           |
+| Model                               | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ----------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `privatemode-ai/gpt-oss-120b`       | 128K    |       |           |       |       |       | —          | —           |
+| `privatemode-ai/kimi-k2.6`          | 262K    |       |           |       |       |       | —          | —           |
+| `privatemode-ai/qwen3-embedding-4b` | 32K     |       |           |       |       |       | —          | —           |
+| `privatemode-ai/voxtral-mini-3b`    | 32K     |       |           |       |       |       | —          | —           |
+| `privatemode-ai/whisper-large-v3`   | —       |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -52,7 +52,7 @@ const agent = new Agent({
   name: "custom-agent",
   model: {
     url: "http://localhost:8080/v1",
-    id: "privatemode-ai/gemma-3-27b",
+    id: "privatemode-ai/gpt-oss-120b",
     apiKey: process.env.PRIVATEMODE_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -71,7 +71,7 @@ const agent = new Agent({
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
       ? "privatemode-ai/whisper-large-v3"
-      : "privatemode-ai/gemma-3-27b";
+      : "privatemode-ai/gpt-oss-120b";
   }
 });
 ```

package/.docs/reference/agents/generate.md

@@ -106,7 +106,7 @@ const result = await agent.generate('message for agent')
 
 **options.structuredOutput.instructions** (`string`): Additional instructions for the structured output model.
 
-**options.structuredOutput.jsonPromptInjection** (`boolean`): Injects system prompt into the main agent instructing it to return structured output, useful for when a model does not natively support structured outputs.
+**options.structuredOutput.jsonPromptInjection** (`boolean | 'system' | 'inline' | 'auto'`): Controls how the JSON schema reaches the model. Set to 'auto' to use native structured output when supported and inline prompt injection otherwise.
 
 **options.structuredOutput.logger** (`IMastraLogger`): Optional logger instance for structured logging during output generation.
 

package/.docs/reference/evals/create-scorer.md

@@ -51,7 +51,7 @@ const scorer = createScorer({
 
 **judge.instructions** (`string`): System prompt/instructions for the LLM.
 
-**judge.jsonPromptInjection** (`boolean`): When true, inject the JSON schema into the prompt instead of using the provider's native response\_format API. Set this for models that don't support native structured output (e.g. some Groq Llama models) to avoid a wasted 400 call.
+**judge.jsonPromptInjection** (`boolean | 'system' | 'inline' | 'auto'`): Controls how the judge's structured output schema reaches the model. Defaults to 'auto', which uses native structured output when supported and inline prompt injection otherwise. Explicit values override automatic routing.
 
 **judge.inputProcessors** (`Processor[]`): Input processors applied to the internal judge agent before its messages reach the model (e.g. redaction, validation).
 

package/.docs/reference/evals/run-evals.md

@@ -31,6 +31,28 @@ console.log(`Average scores:`, result.scores)
 console.log(`Processed ${result.summary.totalItems} items`)
 ```
 
+### Multi-turn evaluation
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { checks } from '@mastra/evals/checks'
+import { weatherAgent } from './agents/weather-agent'
+
+const result = await runEvals({
+  target: weatherAgent,
+  data: [
+    {
+      inputs: [
+        'What is the weather in Brooklyn?',
+        'What about tomorrow?',
+        'Compare the two forecasts.',
+      ],
+    },
+  ],
+  scorers: [checks.calledTool('get_weather', { times: 2 }), checks.includes('Brooklyn')],
+})
+```
+
 ### With gates and thresholds
 
 ```typescript
@@ -60,7 +82,7 @@ result.thresholdResults // [{ id, passed, averageScore, threshold }]
 
 **gates** (`MastraScorer[]`): Scorers that must score 1.0 for the run to pass. If any gate averages below 1.0 across data items, the verdict is failed. Gates run before regular scorers on each data item. When provided, scorers may be omitted.
 
-**targetOptions** (`AgentExecutionOptions | WorkflowRunOptions`): Options forwarded to the target during execution. For agents: options passed to agent.generate() (e.g. maxSteps, modelSettings, instructions). For workflows: options passed to run.start() (e.g. perStep, outputOptions, initialState).
+**targetOptions** (`AgentExecutionOptions | WorkflowRunOptions`): Options forwarded to the target during execution. For agents: options passed to agent.generate() (e.g. maxSteps, modelSettings, instructions). For workflows: options passed to run.start() (e.g. perStep, outputOptions, initialState). For multi-turn agent runs (inputs/turns), runEvals generates and injects the shared thread and a resource, so memory.thread is optional; provide memory.resource to reuse a specific resource.
 
 **concurrency** (`number`): Number of test cases to run concurrently. (Default: `1`)
 
@@ -68,7 +90,11 @@ result.thresholdResults // [{ id, passed, averageScore, threshold }]
 
 ## Data item structure
 
-**input** (`string | string[] | CoreMessage[] | any`): Input data for the target. For agents: messages or strings. For workflows: workflow input data.
+**input** (`string | string[] | CoreMessage[] | any`): Input data for the target. For agents: messages or strings. For workflows: workflow input data. Optional when inputs is provided.
+
+**inputs** (`(string | string[] | CoreMessage[] | any)[]`): Multi-turn inputs. Each entry is one turn (same shape as input) sent sequentially to the agent on the same thread. Scorers see the accumulated output from all turns. Only supported for Agent targets. When provided, input can be omitted. Mutually exclusive with turns.
+
+**turns** (`EvalTurn[]`): Multi-turn conversation with per-turn assertions. Each turn is an object { input, gates?, scorers? } sent sequentially on the same thread; its gates/scorers evaluate only that turn's input and output. Per-turn outcomes are reported in turnResults and folded into the overall verdict. Only supported for Agent targets. Mutually exclusive with input and inputs.
 
 **groundTruth** (`any`): Expected or reference output for comparison during scoring.
 
@@ -112,6 +138,18 @@ For workflows, use `WorkflowScorerConfig` to specify scorers at different levels
 
 **thresholdResults** (`ThresholdResult[]`): Per-threshold-scorer results averaged across all data items. Each entry has id, passed, averageScore, and threshold.
 
+**turnResults** (`TurnResult[]`): Present when any data item uses turns. Each entry has index (zero-based turn), optional gateResults, thresholdResults, and scores (bare-scorer averages keyed by scorer id), aggregated by turn index across data items.
+
+## EvalTurn
+
+A single turn in a `turns` array. Its `gates`/`scorers` evaluate only that turn's input and output:
+
+**input** (`string | string[] | CoreMessage[] | any`): The input sent to the agent for this turn.
+
+**gates** (`MastraScorer[]`): Gates that must score 1.0 for this turn. A failing turn gate makes the overall verdict failed.
+
+**scorers** (`ScorerEntry[]`): Scorers (optionally with thresholds) evaluated against this turn only. A missed per-turn threshold (with gates passing) makes the verdict scored.
+
 ## ScorerEntry
 
 A scorer entry in the `scorers` array can be either a bare scorer or a scorer with a threshold:
@@ -314,8 +352,62 @@ const result = await runEvals({
 })
 ```
 
+### Multi-turn conversation evaluation
+
+Use `inputs` to send sequential turns on a shared thread. Scorers see the accumulated output from all turns:
+
+```typescript
+const result = await runEvals({
+  target: chatAgent,
+  data: [
+    {
+      inputs: ['My favorite city is Brooklyn.', 'What is the weather in my favorite city?'],
+    },
+  ],
+  gates: [checks.calledTool('get_weather')],
+  scorers: [{ scorer: checks.similarity('Brooklyn weather forecast'), threshold: 0.5 }],
+})
+
+// result.verdict: 'passed' | 'scored' | 'failed'
+```
+
+Each turn runs `agent.generate()` with the same `threadId`, so the agent sees the full conversation history. `runEvals` also injects a `resourceId` (Mastra memory scopes messages by resource + thread), defaulting it to the generated thread; pass `targetOptions.memory.resource` to pin a specific one. Cross-turn recall requires the agent to have a memory store configured; otherwise turns run in isolation. Mix single-turn (`input`) and multi-turn (`inputs`) items in the same `data` array. When using `inputs`, `input` can be omitted.
+
+Scoring uses the accumulated output from all turns as `run.output`, but only the first turn as `run.input`. Prefer output-based scorers (`checks.includes`, `checks.calledTool`, `checks.similarity`) for multi-turn; input-relative scorers (e.g. faithfulness) only see the first turn's input. Trajectory scorers that read from the trace (`AgentScorerConfig.trajectory`) resolve against the last turn's span; tool-call checks that read `run.output` (like `checks.calledTool`) still see every turn.
+
+### Per-turn assertions
+
+Use `turns` to attach `gates`/`scorers` to individual turns. Each per-turn assertion sees only that turn's input and output, so a later-turn regression can't be hidden by an earlier turn:
+
+```typescript
+const result = await runEvals({
+  target: chatAgent,
+  data: [
+    {
+      turns: [
+        {
+          input: 'What is the weather in Brooklyn?',
+          gates: [checks.calledTool('get_weather')],
+        },
+        {
+          input: 'What about tomorrow?',
+          gates: [checks.calledTool('get_weather')], // must call again this turn
+          scorers: [{ scorer: checks.similarity('tomorrow forecast'), threshold: 0.5 }],
+        },
+      ],
+    },
+  ],
+})
+
+result.verdict // folds in per-turn gate/threshold outcomes
+result.turnResults // [{ index, gateResults, thresholdResults, scores }]
+```
+
+Per-turn gates/scorers evaluate only that turn (`run.input`/`run.output` are that turn's). A failing turn gate makes the verdict `failed`; a missed turn threshold (gates passing) makes it `scored`. Top-level `scorers`/`gates` still score the accumulated conversation holistically. `turns` is Agent-only and cannot be combined with `input` or `inputs`.
+
 ## Related
 
+- [Multi-turn evals](https://mastra.ai/docs/evals/multi-turn): Conceptual guide to multi-turn evaluation
 - [Gates and Verdicts](https://mastra.ai/docs/evals/gates-and-verdicts): Conceptual guide to severity semantics
 - [Quick Checks](https://mastra.ai/reference/evals/checks): Zero-LLM composable micro-scorers
 - [createScorer()](https://mastra.ai/reference/evals/create-scorer): Create custom scorers for experiments

package/.docs/reference/streaming/agents/stream.md

@@ -100,7 +100,7 @@ const stream = await agent.stream('message for agent')
 
 **options.structuredOutput.instructions** (`string`): Additional instructions for the structured output model.
 
-**options.structuredOutput.jsonPromptInjection** (`boolean`): Injects system prompt into the main agent instructing it to return structured output, useful for when a model does not natively support structured outputs.
+**options.structuredOutput.jsonPromptInjection** (`boolean | 'system' | 'inline' | 'auto'`): Controls how the JSON schema reaches the model. Set to 'auto' to use native structured output when supported and inline prompt injection otherwise.
 
 **options.structuredOutput.providerOptions** (`ProviderOptions`): Provider-specific options passed to the internal structuring agent. Use this to control model behavior like reasoning effort for thinking models (e.g., { openai: { reasoningEffort: 'low' } }).
 

package/.docs/reference/tools/mcp-client.md

@@ -207,6 +207,34 @@ const instructionsByServer = mcp.getServerInstructions()
 console.log(instructionsByServer.db)
 ```
 
+### `authenticate()`
+
+Runs the interactive OAuth authorization-code flow for a server configured with an `MCPOAuthClientProvider` whose redirect URL points at a loopback address. Starts a local callback server, delivers the authorization URL through the provider's `onRedirectToAuthorization` callback, waits for the browser to return the authorization code, exchanges it for tokens, and reconnects. See [Interactive browser authentication](#interactive-browser-authentication).
+
+The optional `timeoutMs` bounds how long the flow waits for the browser to return the authorization code before rejecting, and defaults to 5 minutes.
+
+```typescript
+async authenticate(serverName: string, options?: { timeoutMs?: number }): Promise<void>
+```
+
+### `getServerAuthState()`
+
+Returns the OAuth authorization state of a configured server: `'needs-auth'` after a connection attempt was rejected with an authorization error, `'authorized'` once the server accepted the provider's credentials, or `undefined` for servers without an `authProvider` or that haven't attempted a connection yet.
+
+```typescript
+getServerAuthState(serverName: string): 'needs-auth' | 'authorized' | undefined
+```
+
+### `cancelAuthentication()`
+
+Cancels an in-progress `authenticate()` flow for a server, so an abandoned browser authorization does not leave the client waiting indefinitely. It aborts the flow (including its setup phase, before the callback server binds), closes the local callback server if one is listening, and the pending `authenticate()` call rejects. Returns `true` if a flow was cancelled, or `false` when no flow was in progress.
+
+The resulting `getServerAuthState()` depends on how far the flow had progressed: a flow cancelled after the server rejected the connection with `401` stays at `'needs-auth'` and can be retried immediately, while a flow cancelled during the setup phase — before any connection was attempted — leaves the state unchanged (typically `undefined`).
+
+```typescript
+async cancelAuthentication(serverName: string): Promise<boolean>
+```
+
 ### `disconnect()`
 
 Disconnects from all MCP servers and cleans up resources.
@@ -821,6 +849,74 @@ const client = new MCPClient({
 })
 ```
 
+Give each server its own `MCPOAuthClientProvider` instance. A provider holds per-server session and credential state during authorization, so sharing one instance across multiple servers lets their flows overwrite each other. When configuring several protected servers, construct a separate provider for each.
+
+### Interactive browser authentication
+
+When a server rejects a connection because authorization is required, the client records a `'needs-auth'` state instead of failing outright. Calling `authenticate()` then completes the flow end to end: it starts a one-shot callback server on the provider's loopback redirect URL (falling back to the next sequential ports when it is in use), lets the SDK run discovery and dynamic client registration, delivers the authorization URL through `onRedirectToAuthorization` — open it in the user's browser — and finishes the token exchange once the browser returns the authorization code:
+
+```typescript
+import { MCPClient, MCPOAuthClientProvider } from '@mastra/mcp'
+
+const oauthProvider = new MCPOAuthClientProvider({
+  redirectUrl: 'http://127.0.0.1:5533/oauth/callback',
+  clientMetadata: {
+    redirect_uris: ['http://127.0.0.1:5533/oauth/callback'],
+    client_name: 'My MCP Client',
+    grant_types: ['authorization_code', 'refresh_token'],
+    response_types: ['code'],
+  },
+  onRedirectToAuthorization: url => {
+    // Open the user's browser at the consent page
+    console.log(`Please visit: ${url}`)
+  },
+})
+
+const mcp = new MCPClient({
+  servers: {
+    protectedServer: {
+      url: new URL('https://mcp.example.com/mcp'),
+      authProvider: oauthProvider,
+    },
+  },
+})
+
+try {
+  await mcp.listTools()
+} catch {
+  if (mcp.getServerAuthState('protectedServer') === 'needs-auth') {
+    await mcp.authenticate('protectedServer')
+  }
+}
+```
+
+Concurrent `authenticate()` calls for the same server join the pending flow; different servers authenticate independently. With valid stored tokens the call simply reconnects without opening a browser.
+
+Hosts that drive the flow themselves can capture the authorization code with the exported `createOAuthCallbackServer` helper, which binds a one-shot loopback server, validates the OAuth `state` parameter, and resolves with the code. It creates a plain HTTP server, so it is only for local loopback redirects. Web applications that use an HTTPS redirect URL must host their own callback endpoint and drive the provider directly rather than using this helper:
+
+```typescript
+import { createOAuthCallbackServer, getCallbackUrlCandidates } from '@mastra/mcp'
+
+// getCallbackUrlCandidates() lists every URL the helper may bind, so register
+// all of them as redirect_uris during client registration to cover port fallback.
+const redirectUris = getCallbackUrlCandidates('http://127.0.0.1:5533/oauth/callback').map(url =>
+  url.toString(),
+)
+
+const server = await createOAuthCallbackServer({
+  redirectUrl: 'http://127.0.0.1:5533/oauth/callback',
+  state: expectedState,
+})
+
+// server.url reflects the port actually bound — use it as the redirect_uri.
+try {
+  const { code } = await server.waitForCode()
+  // Exchange the code here.
+} finally {
+  await server.close()
+}
+```
+
 ### Quick Token Provider
 
 For testing or when you already have a valid access token:

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @mastra/mcp-docs-server
 
+## 1.2.8-alpha.4
+
+### Patch Changes
+
+- Updated dependencies [[`8b20926`](https://github.com/mastra-ai/mastra/commit/8b20926cd59e2ba3d66458e062fa0e6e2ada3e68), [`74faf8b`](https://github.com/mastra-ai/mastra/commit/74faf8bd9c1018f2492653c06b1e25fc8300e9e6), [`1fadac4`](https://github.com/mastra-ai/mastra/commit/1fadac44537caeefe81f9f775ae2f2f3d94e9069), [`970c032`](https://github.com/mastra-ai/mastra/commit/970c032502751ee5dd4d0b603331d9838cb538fc), [`792ec9a`](https://github.com/mastra-ai/mastra/commit/792ec9a0869bab8274cf5e0ed2840738737a1607), [`712b864`](https://github.com/mastra-ai/mastra/commit/712b864aa1ed12b14c54390ec17b69de163c37f7), [`8f7a5de`](https://github.com/mastra-ai/mastra/commit/8f7a5dedc246cdc938bb65516703cf9b27b03756), [`c0bec73`](https://github.com/mastra-ai/mastra/commit/c0bec732c93d1a22ae5e51ed66cf8cacca8bd6a6)]:
+  - @mastra/core@1.52.0-alpha.2
+  - @mastra/mcp@1.15.0-alpha.0
+
+## 1.2.8-alpha.3
+
+### Patch Changes
+
+- Updated dependencies:
+  - @mastra/core@1.51.1-alpha.1
+
 ## 1.2.8-alpha.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.8-alpha.2",
+  "version": "1.2.8-alpha.5",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.51.1-alpha.0",
-    "@mastra/mcp": "^1.14.0"
+    "@mastra/core": "1.52.0-alpha.2",
+    "@mastra/mcp": "^1.15.0-alpha.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -47,7 +47,7 @@
     "vitest": "4.1.10",
     "@internal/lint": "0.0.114",
     "@internal/types-builder": "0.0.89",
-    "@mastra/core": "1.51.1-alpha.0"
+    "@mastra/core": "1.52.0-alpha.2"
   },
   "homepage": "https://mastra.ai",
   "repository": {