@mastra/mcp-docs-server 1.2.0 → 1.2.1-alpha.1

package/.docs/docs/agents/goals.md

@@ -2,12 +2,12 @@
 
 **Added in:** `@mastra/core@1.42.0`
 
+> **Alpha:** The Goals feature is in alpha stage and subject to breaking changes in minor versions until it graduates from its alpha status.
+
 A goal is a durable, thread-scoped objective: a standing instruction the agent keeps working toward across loop iterations until a judge model decides it is satisfied or a run budget is exhausted. The objective is persisted in thread state, so it survives reloads and is evaluated in-loop — even when a new message arrives in the middle of an already-running turn.
 
 Goals build on the same machinery as [`isTaskComplete`](https://mastra.ai/docs/agents/supervisor-agents): an LLM-as-judge scores the agent's output each iteration and gates the loop. The difference is that a goal is **durable** (stored in thread state, not passed per call) and is set and updated through `Agent` methods rather than per-`stream()` options.
 
-> **Note:** Goals are experimental and may change in a future release.
-
 ## When to use goals
 
 Use a goal when you want an agent to keep working toward a single objective across many iterations and messages, without re-supplying the success criteria on every call:

package/.docs/docs/harness/modes.md

@@ -96,10 +96,10 @@ On plan approval, the Harness automatically switches to `build` mode. On rejecti
 
 ## Switching modes
 
-Call `switchMode()` to change the active mode. The Harness aborts any in-progress generation, saves the current model to the outgoing mode, loads the incoming mode's model, and emits `mode_changed` and `model_changed` events:
+The active mode lives on the Session, so call `harness.session.mode.switch()` to change it. The switch aborts any in-progress generation, saves the current model to the outgoing mode, and emits a `mode_changed` event. It then resolves the incoming mode's model and, when one resolves, applies it and emits a `model_changed` event:
 
 ```typescript
-await harness.switchMode({ modeId: 'build' })
+await harness.session.mode.switch({ modeId: 'build' })
 ```
 
 ## Querying modes

package/.docs/docs/harness/overview.md

@@ -92,33 +92,31 @@ await harness.sendMessage({ content: 'Hello!' })
 The Harness sits between your application layer and the underlying agent loop:
 
 ```text
-┌──────────────────────────┐
-│   Your App (TUI/Web/API) │
-└────────────┬─────────────┘
-             │ commands (sendMessage, switchMode, approve)
-             │ events (message_update, tool_approval_required)
-┌────────────▼─────────────┐
-│  Harness (shared host)   │
-│  Config · Storage        │
-│  Thread lifecycle        │
-│  Permission policy        │
-│  Subagent spawning        │
-│  Event bus               │
-│  ┌─────────────────────┐ │
-│  │ harness.session      │ │
-│  │ identity · thread    │ │
-│  │ mode · model · run   │ │
-│  │ grants · follow-ups  │ │
-│  │ display state        │ │
-│  └─────────────────────┘ │
-└────────────┬─────────────┘
-             │
-┌────────────▼──────────────┐
-│  Agent + Memory + Tools   │
-└───────────────────────────┘
+┌───────────────────────────────────────┐
+│         Your App (TUI/Web/API)        │
+└───────────────────────────────────────┘
+      │  commands              ▲  events
+      ▼                        │
+┌───────────────────────────────────────┐
+│                Harness                │
+│ Config · storage · threads            │
+│ permissions · subagents · events      │
+│                                       │
+│  ┌─────────────────────────────────┐  │
+│  │         harness.session         │  │
+│  │ identity · thread · mode        │  │
+│  │ model · run · grants            │  │
+│  │ display state                   │  │
+│  └─────────────────────────────────┘  │
+└───────────────────────────────────────┘
+                   │
+                   ▼
+┌───────────────────────────────────────┐
+│         Agent + Memory + Tools        │
+└───────────────────────────────────────┘
 ```
 
-Your app sends commands (send a message, switch mode, approve a tool call) and receives typed events. The Harness manages the lifecycle internally: persisting threads, routing to the correct mode agent, enforcing permissions, and emitting events as state changes.
+Your app sends commands — send a message, switch mode, approve a tool call — and receives typed events such as `message_update` and `tool_approval_required`. The Harness manages the lifecycle internally: persisting threads, routing to the correct mode agent, enforcing permissions, and emitting events as state changes.
 
 ## Next steps
 

package/.docs/docs/harness/session.md

@@ -48,8 +48,8 @@ See [Threads and state](https://mastra.ai/docs/harness/threads-and-state) for th
 The Harness defines the available modes in `config.modes`. The Session tracks which mode and model are _currently_ selected:
 
 ```typescript
-// Switch mode (Harness orchestration — aborts the run, emits events)
-await harness.switchMode({ modeId: 'build' })
+// Switch mode (aborts the run, emits events)
+await harness.session.mode.switch({ modeId: 'build' })
 
 // Read the current selection (Session state)
 const modeId = harness.session.mode.get()

package/.docs/docs/harness/subagents.md

@@ -85,16 +85,16 @@ Set a global or per-type subagent model at runtime:
 
 ```typescript
 // Global subagent model
-await harness.setSubagentModelId({ modelId: 'anthropic/claude-sonnet-4-6' })
+await harness.session.subagents.model.set({ modelId: 'anthropic/claude-sonnet-4-6' })
 
 // Per-type override
-await harness.setSubagentModelId({
+await harness.session.subagents.model.set({
   modelId: 'anthropic/claude-haiku-4-5',
   agentType: 'explore',
 })
 
 // Read current model
-const modelId = harness.getSubagentModelId({ agentType: 'explore' })
+const modelId = harness.session.subagents.model.get({ agentType: 'explore' })
 ```
 
 ## Related

package/.docs/docs/harness/tool-approvals.md

@@ -16,10 +16,10 @@ Set policies per-category or per-tool. Per-tool policies take precedence over ca
 
 ```typescript
 // Category-level: all execute tools require approval
-harness.setPermissionForCategory({ category: 'execute', policy: 'ask' })
+await harness.session.permissions.setForCategory({ category: 'execute', policy: 'ask' })
 
 // Tool-level: this specific tool is always blocked
-harness.setPermissionForTool({ toolName: 'dangerous_tool', policy: 'deny' })
+await harness.session.permissions.setForTool({ toolName: 'dangerous_tool', policy: 'deny' })
 ```
 
 ### Tool categories

package/.docs/guides/build-your-ui/openui.md

@@ -0,0 +1,297 @@
+# Using OpenUI
+
+[OpenUI](https://openui.com) is an open standard for generative UI. It pairs a compact streaming-first language (OpenUI Lang) with a React runtime and built-in component libraries, so model output can render as structured UI as it streams.
+
+OpenUI connects to Mastra through the [AG-UI protocol](https://docs.ag-ui.com). The `@ag-ui/mastra` adapter wraps a Mastra `Agent` and emits AG-UI events, which OpenUI's `agUIAdapter()` parses on the client.
+
+> **Tip:** For a complete working example, see the [`mastra-chat`](https://github.com/thesysdev/openui/tree/main/examples/mastra-chat) example in the OpenUI repository.
+
+## Integration guide
+
+Embed Mastra in your Next.js API route and connect an OpenUI `<FullScreen />` chat surface to it through the AG-UI protocol.
+
+1. Scaffold a new OpenUI app:
+
+   **npm**:
+
+   ```bash
+   npx @openuidev/cli@latest create --name openui-mastra-chat
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm dlx @openuidev/cli@latest create --name openui-mastra-chat
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn dlx @openuidev/cli@latest create --name openui-mastra-chat
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun x @openuidev/cli@latest create --name openui-mastra-chat
+   ```
+
+   Navigate to your newly created project directory:
+
+   ```bash
+   cd openui-mastra-chat
+   ```
+
+   The scaffolded app is a Next.js project with the following structure:
+
+   ```bash
+   openui-mastra-chat
+   └── src
+       ├── app
+       │   ├── api
+       │   │   └── chat
+       │   │       └── route.ts
+       │   ├── globals.css
+       │   ├── layout.tsx
+       │   └── page.tsx
+       ├── generated
+       │   └── system-prompt.txt
+       └── library.ts
+   ```
+
+   The chat route lives in `src/app/api/chat/route.ts`, the chat surface in `src/app/page.tsx`, and the component library in `src/library.ts`. The OpenUI CLI writes `src/generated/system-prompt.txt` from your library; regenerate it whenever the library changes.
+
+   Add your OpenAI key to `.env.local`:
+
+   ```bash
+   OPENAI_API_KEY=sk-...
+   ```
+
+   > **Note:** OpenUI requires a model provider key. Use any provider supported by Mastra and adjust the agent configuration in the next step.
+
+2. Install the Mastra packages and the AG-UI adapter for Mastra:
+
+   **npm**:
+
+   ```bash
+   npm install @mastra/core @ag-ui/mastra @ag-ui/core zod
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add @mastra/core @ag-ui/mastra @ag-ui/core zod
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn add @mastra/core @ag-ui/mastra @ag-ui/core zod
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add @mastra/core @ag-ui/mastra @ag-ui/core zod
+   ```
+
+   `@ag-ui/mastra` wraps a Mastra `Agent` in a `MastraAgent` that emits [AG-UI protocol](https://docs.ag-ui.com) events. OpenUI's `agUIAdapter()` consumes those events on the client.
+
+3. Open `src/app/api/chat/route.ts`. Define any tools your agent needs with `createTool` from `@mastra/core/tools`:
+
+   ```typescript
+   import { createTool } from '@mastra/core/tools'
+   import { z } from 'zod'
+
+   const getWeather = createTool({
+     id: 'get_weather',
+     description: 'Get current weather for a city.',
+     inputSchema: z.object({ location: z.string().describe('City name') }),
+     execute: async ({ location }) => {
+       return { location, temperature_celsius: 22, condition: 'Clear' }
+     },
+   })
+   ```
+
+   Wrap a Mastra `Agent` in `MastraAgent`. Inject the generated system prompt so the agent knows how to use the OpenUI component library:
+
+   ```typescript
+   import { MastraAgent } from '@ag-ui/mastra'
+   import { Agent } from '@mastra/core/agent'
+   import { readFileSync } from 'fs'
+   import { join } from 'path'
+
+   const systemPrompt = readFileSync(join(process.cwd(), 'src/generated/system-prompt.txt'), 'utf-8')
+
+   const agent = new MastraAgent({
+     agent: new Agent({
+       id: 'openui-agent',
+       name: 'OpenUI Agent',
+       instructions: `You are a helpful assistant. Use tools when relevant.\n\n${systemPrompt}`,
+       model: {
+         id: 'openai/gpt-5.5',
+         apiKey: process.env.OPENAI_API_KEY,
+       },
+       tools: { getWeather },
+     }),
+     resourceId: 'chat-user',
+   })
+   ```
+
+   Export a `POST` handler that streams the agent's AG-UI events as Server-Sent Events (SSE):
+
+   ```typescript
+   import type { Message } from '@ag-ui/core'
+   import { NextRequest } from 'next/server'
+
+   export async function POST(req: NextRequest) {
+     const { messages, threadId }: { messages: Message[]; threadId: string } = await req.json()
+     const encoder = new TextEncoder()
+
+     const stream = new ReadableStream({
+       start(controller) {
+         const subscription = agent
+           .run({ messages, threadId, runId: crypto.randomUUID(), tools: [], context: [] })
+           .subscribe({
+             next: event => {
+               controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`))
+             },
+             complete: () => {
+               controller.enqueue(encoder.encode('data: [DONE]\n\n'))
+               controller.close()
+             },
+             error: error => {
+               controller.enqueue(
+                 encoder.encode(`data: ${JSON.stringify({ error: error.message })}\n\n`),
+               )
+               controller.close()
+             },
+           })
+
+         req.signal.addEventListener('abort', () => subscription.unsubscribe())
+       },
+     })
+
+     return new Response(stream, {
+       headers: {
+         'Content-Type': 'text/event-stream',
+         'Cache-Control': 'no-cache, no-transform',
+         Connection: 'keep-alive',
+       },
+     })
+   }
+   ```
+
+4. Wire the OpenUI `<FullScreen />` chat surface to the route. Set `streamProtocol` to `agUIAdapter()` so OpenUI knows to parse AG-UI events.
+
+   ```tsx
+   'use client'
+
+   import '@openuidev/react-ui/components.css'
+
+   import { agUIAdapter } from '@openuidev/react-headless'
+   import { FullScreen } from '@openuidev/react-ui'
+   import { openuiChatLibrary } from '@openuidev/react-ui/genui-lib'
+
+   export default function Page() {
+     return (
+       <div className="relative h-screen w-screen overflow-hidden">
+         <FullScreen
+           processMessage={async ({ messages, threadId, abortController }) => {
+             return fetch('/api/chat', {
+               method: 'POST',
+               headers: { 'Content-Type': 'application/json' },
+               body: JSON.stringify({ messages, threadId }),
+               signal: abortController.signal,
+             })
+           }}
+           streamProtocol={agUIAdapter()}
+           componentLibrary={openuiChatLibrary}
+           agentName="OpenUI + Mastra Chat"
+         />
+       </div>
+     )
+   }
+   ```
+
+   The `componentLibrary` prop controls which components the model can generate. Replace `openuiChatLibrary` with your own library to restrict or extend the output.
+
+5. Start the development server:
+
+   **npm**:
+
+   ```bash
+   npm run dev
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm run dev
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn dev
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun run dev
+   ```
+
+   Open <http://localhost:3000>. You can now chat with your Mastra agent through the OpenUI chat surface, with structured UI rendered progressively as the model streams.
+
+## Streaming with AG-UI
+
+OpenUI consumes the [AG-UI protocol](https://docs.ag-ui.com), a transport-agnostic stream of typed events for AI agents. `@ag-ui/mastra` translates a Mastra `Agent` into this protocol:
+
+- The server calls `agent.run({ messages, threadId, runId, ... })` and serializes each emitted event as an SSE message.
+- The client passes `streamProtocol={agUIAdapter()}` to `<FullScreen />`, which parses the SSE stream into the internal events that drive OpenUI Lang rendering.
+
+`threadId` ties a conversation together across requests, and `runId` identifies a single execution. Generate a fresh `runId` per request and persist `threadId` on the client.
+
+## Component libraries
+
+OpenUI generates UI from a component library. The library defines which components are available, their props, and how the model is instructed to use them.
+
+### Built-in libraries
+
+`@openuidev/react-ui` ships two libraries you can use as-is:
+
+- `openuiChatLibrary`: components for chat interfaces (cards, forms, tables, charts).
+- `openuiDashboardLibrary`: components for dashboards and data-heavy surfaces.
+
+Pass the library to `<FullScreen componentLibrary={...} />` to make its components available to the model.
+
+### Customizing the library
+
+To restrict or extend the output, define your own library in `src/library.ts` and export a subset of components. Pass that library to `<FullScreen />` and regenerate the system prompt whenever the library changes:
+
+**npm**:
+
+```bash
+npx @openuidev/cli generate src/library.ts --out src/generated/system-prompt.txt
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx @openuidev/cli generate src/library.ts --out src/generated/system-prompt.txt
+```
+
+**Yarn**:
+
+```bash
+yarn dlx @openuidev/cli generate src/library.ts --out src/generated/system-prompt.txt
+```
+
+**Bun**:
+
+```bash
+bun x @openuidev/cli generate src/library.ts --out src/generated/system-prompt.txt
+```
+
+The generated prompt is read by the API route and merged into the agent's `instructions`, so the agent knows exactly which components it can emit.

package/.docs/models/gateways/custom-gateways.md

@@ -585,6 +585,18 @@ describe('MyPrivateGateway', () => {
 
 8. **Test thoroughly**: Write unit tests for all gateway methods
 
+## Showing only custom gateways in Studio
+
+By default, **Studio** lists every external model provider (such as OpenAI, Anthropic, and Gemini) alongside any custom gateways you register. To hide the external providers, set the `AUTO_BLOCK_EXTERNAL_PROVIDERS` environment variable:
+
+```bash
+AUTO_BLOCK_EXTERNAL_PROVIDERS=true
+```
+
+When this variable is set to `true` or `1`, Mastra returns only the providers from gateways you register yourself. The static provider registry and the built-in gateways (`models.dev`, `netlify`, and `mastra`) are hidden from the model picker. This is useful when you route all model traffic through a single private gateway and don't want the other providers to appear.
+
+With this variable set and no custom gateway registered, the model picker is empty. Register at least one custom gateway to expose its models.
+
 ## Built-in Gateways
 
 Mastra includes built-in gateways as reference implementations:

package/.docs/models/gateways/netlify.md

@@ -1,6 +1,6 @@
 # Netlify
 
-Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 69 models through Mastra's model router.
+Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 66 models through Mastra's model router.
 
 Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
 
@@ -38,27 +38,24 @@ ANTHROPIC_API_KEY=ant-...
 | `anthropic/claude-haiku-4-5`                |
 | `anthropic/claude-haiku-4-5-20251001`       |
 | `anthropic/claude-opus-4-1-20250805`        |
-| `anthropic/claude-opus-4-20250514`          |
 | `anthropic/claude-opus-4-5`                 |
 | `anthropic/claude-opus-4-5-20251101`        |
 | `anthropic/claude-opus-4-6`                 |
 | `anthropic/claude-opus-4-7`                 |
-| `anthropic/claude-sonnet-4-0`               |
-| `anthropic/claude-sonnet-4-20250514`        |
+| `anthropic/claude-opus-4-8`                 |
 | `anthropic/claude-sonnet-4-5`               |
 | `anthropic/claude-sonnet-4-5-20250929`      |
 | `anthropic/claude-sonnet-4-6`               |
-| `gemini/gemini-2.0-flash`                   |
-| `gemini/gemini-2.0-flash-lite`              |
 | `gemini/gemini-2.5-flash`                   |
 | `gemini/gemini-2.5-flash-image`             |
 | `gemini/gemini-2.5-flash-lite`              |
 | `gemini/gemini-2.5-pro`                     |
 | `gemini/gemini-3-flash-preview`             |
+| `gemini/gemini-3-pro-image`                 |
 | `gemini/gemini-3-pro-image-preview`         |
+| `gemini/gemini-3.1-flash-image`             |
 | `gemini/gemini-3.1-flash-image-preview`     |
 | `gemini/gemini-3.1-flash-lite`              |
-| `gemini/gemini-3.1-flash-lite-preview`      |
 | `gemini/gemini-3.1-pro-preview`             |
 | `gemini/gemini-3.1-pro-preview-customtools` |
 | `gemini/gemini-3.5-flash`                   |