@mastra/mcp-docs-server 1.1.20-alpha.0 → 1.1.20-alpha.1

package/.docs/docs/server/mastra-client.md

@@ -4,7 +4,7 @@ The Mastra Client SDK provides a concise and type-safe interface for interacting
 
 ## Prerequisites
 
-To ensure smooth local development, make sure you have:
+Before you start local development, have:
 
 - Node.js `v22.13.0` or later
 - TypeScript `v4.7` or higher (if using TypeScript)
@@ -54,15 +54,17 @@ export const mastraClient = new MastraClient({
 
 ## Core APIs
 
-The Mastra Client SDK exposes all resources served by the Mastra Server
+The Mastra Client SDK exposes all resources served by the Mastra Server.
 
 - **[Agents](https://mastra.ai/reference/client-js/agents)**: Generate responses and stream conversations.
 - **[Memory](https://mastra.ai/reference/client-js/memory)**: Manage conversation threads and message history.
 - **[Tools](https://mastra.ai/reference/client-js/tools)**: Executed and managed tools.
 - **[Workflows](https://mastra.ai/reference/client-js/workflows)**: Trigger workflows and track their execution.
 - **[Vectors](https://mastra.ai/reference/client-js/vectors)**: Use vector embeddings for semantic search.
+- **[Responses](https://mastra.ai/reference/client-js/responses)**: Call the OpenAI Responses API through Mastra agents. This API is currently experimental.
+- **[Conversations](https://mastra.ai/reference/client-js/conversations)**: Work with OpenAI Responses API conversations and their stored item history. This API is currently experimental.
 - **[Logs](https://mastra.ai/reference/client-js/logs)**: View logs and debug system behavior.
-- **[Telemetry](https://mastra.ai/reference/client-js/telemetry)**: Monitor app performance and trace activity.
+- **[Telemetry](https://mastra.ai/reference/client-js/telemetry)**: View app performance and trace activity.
 
 ## Generating responses
 
@@ -133,7 +135,7 @@ export const mastraClient = new MastraClient({
 
 ## Credentials and session cookies
 
-**Authenticate Mastra API calls with session cookies** when your UI and Mastra API are not on the same origin—different host, subdomain, or port (for example Mastra Studio on one port and a custom server on another). Add **`credentials: 'include'`** to `MastraClient` so each request carries the cookies the user already has after sign-in. Skip this and you will often get **`401`** responses from Mastra even though login succeeded in the browser.
+**Authenticate Mastra API calls with session cookies** when your UI and Mastra API aren't on the same origin—different host, subdomain, or port (for example Mastra Studio on one port and a custom server on another). Add **`credentials: 'include'`** to `MastraClient` so each request carries the cookies the user already has after sign-in. Skip this and you will often get **`401`** responses from Mastra even though login succeeded in the browser.
 
 ```typescript
 import { MastraClient } from '@mastra/client-js'
@@ -146,7 +148,7 @@ export const mastraClient = new MastraClient({
 
 **Allow credentialed cross-origin requests on your server**—see [CORS: requests with credentials](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS#requests_with_credentials). You need a concrete `Access-Control-Allow-Origin` (not `*`) and `Access-Control-Allow-Credentials: true`, or the browser will block the call before it reaches Mastra.
 
-**Using `@mastra/react`?** Wrap your app with `MastraReactProvider`, set `baseUrl` and `apiPrefix` to match your server, and rely on the default `credentials: 'include'`. Change `credentials` only when you deliberately want `same-origin` or `omit` behavior.
+**Using `@mastra/react`?** Wrap your app with `MastraReactProvider`, set `baseUrl` and `apiPrefix` to match your server, and rely on the default `credentials: 'include'`. Change `credentials` only when you want `same-origin` or `omit` behavior.
 
 ## Adding request cancelling
 
@@ -219,7 +221,7 @@ const handleClientTool = async () => {
 }
 ```
 
-### Client tool's agent
+### Client tool agent
 
 This is a standard Mastra [agent](https://mastra.ai/docs/agents/overview) configured to return hex color codes, intended to work with the browser-based client tool defined above.
 
@@ -236,9 +238,9 @@ export const colorAgent = new Agent({
 })
 ```
 
-## Server-side environments
+## Use MastraClient on the server
 
-You can also use `MastraClient` in server-side environments such as API routes, serverless functions or actions. The usage will broadly remain the same but you may need to recreate the response to your client:
+You can also use `MastraClient` in server-side environments such as API routes, serverless functions, or actions. The usage remains the same, but you may need to recreate the response for your client:
 
 ```typescript
 export async function action() {
@@ -252,7 +254,7 @@ export async function action() {
 
 ## Best practices
 
-1. **Error Handling**: Implement proper [error handling](https://mastra.ai/reference/client-js/error-handling) for development scenarios.
+1. **Error Handling**: Use [error handling](https://mastra.ai/reference/client-js/error-handling) for development scenarios.
 2. **Environment Variables**: Use environment variables for configuration.
 3. **Debugging**: Enable detailed [logging](https://mastra.ai/reference/client-js/logs) when needed.
-4. **Performance**: Monitor application performance, [telemetry](https://mastra.ai/reference/client-js/telemetry) and traces.
+4. **Performance**: Track application performance, [telemetry](https://mastra.ai/reference/client-js/telemetry), and traces.

package/.docs/docs/server/mastra-server.md

@@ -12,7 +12,7 @@ The server provides:
 
 - API endpoints for all registered agents and workflows
 - Custom API routes and middleware
-- Authentication with multiple providers
+- Authentication across providers
 - Request context for dynamic configuration
 - Stream data redaction for secure responses
 
@@ -51,6 +51,18 @@ To explore the API interactively, visit the Swagger UI at <http://localhost:4111
 
 > **Note:** The OpenAPI and Swagger endpoints are disabled in production by default. To enable them, set [`server.build.openAPIDocs`](https://mastra.ai/reference/configuration) and [`server.build.swaggerUI`](https://mastra.ai/reference/configuration) to `true` respectively.
 
+## OpenAI Responses API
+
+Mastra exposes OpenAI-compatible Responses and Conversations routes. These routes are agent-backed adapters over Mastra agents, memory, and storage, so requests run through the selected Mastra agent instead of acting as a raw provider proxy.
+
+These APIs are currently experimental.
+
+Use `agent_id` to select the Mastra agent that should handle the request. Initial requests target an agent directly, and stored follow-up turns can continue with `previous_response_id`. You can also pass `model` to override the agent's configured model for a single request. If you omit `model`, Mastra uses the model already configured on the agent.
+
+The Responses routes support streaming, function calling (tools), stored continuations with `previous_response_id`, conversation threads through `conversation_id`, provider-specific passthrough with `providerOptions`, and JSON output through `text.format`.
+
+For the full request and response contract, see the [Responses API reference](https://mastra.ai/reference/client-js/responses) and [Conversations API reference](https://mastra.ai/reference/client-js/conversations). For the complete list of HTTP routes, see [server routes](https://mastra.ai/reference/server/routes).
+
 ## Stream data redaction
 
 When streaming agent responses, the HTTP layer redacts system prompts, tool definitions, API keys, and similar data from each chunk before sending it to clients. This is enabled by default.

package/.docs/guides/guide/firecrawl.md

@@ -0,0 +1,152 @@
+# Web scraping with Firecrawl
+
+Firecrawl is a web data API that turns websites into clean markdown or structured JSON. In this guide, you will wire Firecrawl into Mastra tools so your agents and workflows can search and scrape live web data on demand.
+
+## Prerequisites
+
+- Node.js `v22.13.0` or later installed
+- A Firecrawl API key (get one at <https://firecrawl.dev>)
+- An API key from a supported [Model Provider](https://mastra.ai/models)
+- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) to set up a new project)
+
+## Installation
+
+Install the Firecrawl SDK:
+
+**npm**:
+
+```bash
+npm install @mendable/firecrawl-js
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mendable/firecrawl-js
+```
+
+**Yarn**:
+
+```bash
+yarn add @mendable/firecrawl-js
+```
+
+**Bun**:
+
+```bash
+bun add @mendable/firecrawl-js
+```
+
+## Configure environment variables
+
+Create a `.env` file in your project root:
+
+```bash
+FIRECRAWL_API_KEY=fc-your-api-key
+# Optional: FIRECRAWL_API_URL=http://localhost:3002
+```
+
+## Build the Firecrawl tools
+
+Create a tool file that exposes Firecrawl search and scrape to Mastra.
+
+1. Create `src/mastra/tools/firecrawl.ts` and set up Firecrawl:
+
+   ```ts
+   import Firecrawl from '@mendable/firecrawl-js'
+   import { createTool } from '@mastra/core/tools'
+   import { z } from 'zod'
+
+   const firecrawl = new Firecrawl({ apiKey: process.env.FIRECRAWL_API_KEY! })
+
+   export const firecrawlSearch = createTool({
+     id: 'firecrawl-search',
+     description: 'Search the web and return top results.',
+     inputSchema: z.object({ query: z.string().min(1) }),
+     outputSchema: z.object({
+       results: z.array(
+         z.object({
+           title: z.string().nullable(),
+           url: z.string(),
+         }),
+       ),
+     }),
+     execute: async ({ query }) => {
+       const results = await firecrawl.search(query, { limit: 3 })
+       return {
+         results: (results.web ?? []).map(item => ({
+           title: item.title ?? null,
+           url: item.url,
+         })),
+       }
+     },
+   })
+
+   export const firecrawlScrape = createTool({
+     id: 'firecrawl-scrape',
+     description: 'Scrape a URL and return markdown content.',
+     inputSchema: z.object({ url: z.string().url() }),
+     outputSchema: z.object({ markdown: z.string() }),
+     execute: async ({ url }) => {
+       const result = await firecrawl.scrape(url, {
+         formats: ['markdown'],
+         onlyMainContent: true,
+       })
+       return { markdown: result.markdown ?? '' }
+     },
+   })
+   ```
+
+2. Create a new agent at `src/mastra/agents/web-agent.ts`:
+
+   ```ts
+   import { Agent } from '@mastra/core/agent'
+   import { firecrawlSearch, firecrawlScrape } from '../tools/firecrawl'
+
+   export const webAgent = new Agent({
+     id: 'web-agent',
+     name: 'Web Agent',
+     instructions: 'Use Firecrawl tools to search and scrape web pages, then summarize the results.',
+     model: 'openai/gpt-5.4',
+     tools: { firecrawlSearch, firecrawlScrape },
+   })
+   ```
+
+3. Register the newly created agent in `src/mastra/index.ts` on your Mastra instance:
+
+   ```ts
+   import { Mastra } from '@mastra/core'
+   import { webAgent } from './agents/web-agent'
+
+   export const mastra = new Mastra({
+     agents: { webAgent },
+   })
+   ```
+
+## Test in Studio
+
+Run the dev server and open [Studio](https://mastra.ai/docs/studio/overview):
+
+```bash
+mastra dev
+```
+
+In Studio, open the **Web Agent** and try:
+
+- "Find the latest Mastra changelog and summarize the last release."
+- "Search for Firecrawl pricing and extract the plan tiers."
+
+## Self-hosted Firecrawl
+
+If you run Firecrawl locally, set `FIRECRAWL_API_URL` or pass `apiUrl` in the client:
+
+```ts
+const firecrawl = new Firecrawl({
+  apiKey: process.env.FIRECRAWL_API_KEY!,
+  apiUrl: process.env.FIRECRAWL_API_URL,
+})
+```
+
+## Related
+
+- [Firecrawl documentation](https://docs.firecrawl.dev)

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 166 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 167 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -199,4 +199,5 @@ ANTHROPIC_API_KEY=ant-...
 | `z-ai/glm-4.6:exacto`                                           |
 | `z-ai/glm-4.7`                                                  |
 | `z-ai/glm-4.7-flash`                                            |
-| `z-ai/glm-5`                                                    |
+| `z-ai/glm-5`                                                    |
+| `z-ai/glm-5-turbo`                                              |

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 3566 models from 94 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3567 models from 94 providers through a single API.
 
 ## Features
 

package/.docs/reference/agents/getLLM.md

@@ -1,6 +1,6 @@
 # Agent.getLLM()
 
-The `.getLLM()` method retrieves the language model instance configured for an agent, resolving it if it's a function. This method provides access to the underlying LLM that powers the agent's capabilities.
+The `.getLLM()` method retrieves the language model instance configured for an agent, resolving it if it's a function. You can also pass a request-scoped `model` override without mutating the agent's configured model.
 
 ## Usage example
 
@@ -8,13 +8,19 @@ The `.getLLM()` method retrieves the language model instance configured for an a
 await agent.getLLM()
 ```
 
+```typescript
+await agent.getLLM({
+  model: 'openai/gpt-5.4',
+})
+```
+
 ## Parameters
 
-**options** (`{ requestContext?: RequestContext; model?: MastraLanguageModel | DynamicArgument<MastraLanguageModel> }`): Optional configuration object containing request context and optional model override. (Default: `{}`)
+**options** (`{ requestContext?: RequestContext; model?: MastraModelConfig | DynamicArgument<MastraModelConfig> }`): Optional configuration object containing request context and an optional request-scoped model override. (Default: `{}`)
 
 **options.requestContext** (`RequestContext`): Request Context for dependency injection and contextual information.
 
-**options.model** (`MastraLanguageModel | DynamicArgument<MastraLanguageModel>`): Optional model override. If provided, this model will be used used instead of the agent's configured model.
+**options.model** (`MastraModelConfig | DynamicArgument<MastraModelConfig>`): Optional request-scoped model override. The agent's configured model is not mutated.
 
 ## Returns
 

package/.docs/reference/client-js/conversations.md

@@ -0,0 +1,135 @@
+# OpenAI Responses API Conversations
+
+The OpenAI Responses API Conversations surface provides methods to create, retrieve, delete, and inspect thread-backed conversations in Mastra.
+
+This API follows up on the [OpenAI Responses API](https://mastra.ai/reference/client-js/responses). Stored Responses calls return `conversation_id`, and in Mastra that value is the raw memory `threadId`. Use `client.conversations` when you want to work with that thread directly.
+
+This API is currently experimental.
+
+## Relationship to OpenAI Responses
+
+Use the OpenAI Responses API for generation and continuation:
+
+```typescript
+const response = await client.responses.create({
+  agent_id: 'support-agent',
+  input: 'Start a support thread',
+  store: true,
+})
+
+console.log(response.conversation_id)
+```
+
+Use the Conversations API when you want to inspect or manage that stored thread:
+
+```typescript
+const conversation = await client.conversations.retrieve(response.conversation_id!)
+const items = await client.conversations.items.list(response.conversation_id!)
+```
+
+## Usage example
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+const client = new MastraClient({
+  baseUrl: 'http://localhost:4111',
+})
+
+const conversation = await client.conversations.create({
+  agent_id: 'support-agent',
+})
+
+console.log(conversation.id)
+```
+
+## Methods
+
+### Lifecycle
+
+#### `create(params)`
+
+Creates a new conversation thread for the selected agent.
+
+```typescript
+const conversation = await client.conversations.create({
+  agent_id: 'support-agent',
+  title: 'Billing support',
+})
+```
+
+**Returns:** `Promise<Conversation>`.
+
+#### `retrieve(conversationId, requestContext?)`
+
+Retrieves a conversation by its thread ID.
+
+```typescript
+const conversation = await client.conversations.retrieve('thread_123')
+
+console.log(conversation.thread)
+```
+
+**Returns:** `Promise<Conversation>`.
+
+#### `delete(conversationId, requestContext?)`
+
+Deletes a conversation by its thread ID.
+
+```typescript
+const deleted = await client.conversations.delete('thread_123')
+
+console.log(deleted.deleted)
+```
+
+**Returns:** `Promise<ConversationDeleted>`.
+
+### Items
+
+#### `items.list(conversationId, requestContext?)`
+
+Lists the stored items for a conversation.
+
+```typescript
+const items = await client.conversations.items.list('thread_123')
+
+console.log(items.data)
+```
+
+**Returns:** `Promise<ConversationItemsPage>`.
+
+## Response shape
+
+`create()` and `retrieve()` return a conversation object with:
+
+- `id`: The raw thread ID
+- `object`: Always `'conversation'`
+- `thread`: The stored thread record
+
+`delete()` returns:
+
+- `id`: The raw thread ID
+- `object`: Always `'conversation.deleted'`
+- `deleted`: Always `true`
+
+`items.list()` returns:
+
+- `object`: Always `'list'`
+- `data`: Conversation items such as `message`, `function_call`, and `function_call_output`
+- `first_id`: The first item ID in the page
+- `last_id`: The last item ID in the page
+- `has_more`: Whether more items exist beyond the current page
+
+## Parameters
+
+**agent\_id** (`string`): Required. The registered Mastra agent that owns the conversation memory.
+
+**conversation\_id** (`string`): Optional conversation ID to use as the raw thread ID.
+
+**resource\_id** (`string`): Optional resource ID to associate with the conversation thread.
+
+**title** (`string`): Optional thread title stored with the conversation.
+
+**metadata** (`Record<string, unknown>`): Optional thread metadata stored with the conversation.
+
+**requestContext** (`RequestContext | Record<string, any>`): Optional request context forwarded to the Mastra server.

package/.docs/reference/client-js/mastra-client.md

@@ -50,6 +50,10 @@ export const mastraClient = new MastraClient({
 
 **getWorkflow(workflowId)** (`Workflow`): Retrieves a specific workflow instance by ID.
 
+**responses** (`Responses`): Provides OpenAI-style Responses API helpers with \`create()\`, \`retrieve()\`, \`stream()\`, and \`delete()\`.
+
+**conversations** (`Conversations`): Provides conversation helpers with \`create()\`, \`retrieve()\`, \`delete()\`, and \`items.list()\`.
+
 **getVector(vectorName)** (`MastraVector`): Returns a vector store instance by name.
 
 **listLogs(params)** (`Promise<LogEntry[]>`): Fetches system logs matching the provided filters.

package/.docs/reference/client-js/responses.md

@@ -0,0 +1,213 @@
+# OpenAI Responses API
+
+The OpenAI Responses API provides methods to create, retrieve, stream, and delete OpenAI-compatible responses through Mastra agents.
+
+These routes are agent-backed adapters over Mastra agents, memory, and storage. Use `agent_id` to select the Mastra agent that should handle the request. You can pass `model` to override the agent's configured model for a single request, or omit it to use the model already configured on the agent.
+
+Stored responses also return `conversation_id`. In Mastra, this is the raw memory `threadId`.
+
+This API is currently experimental.
+
+## Usage example
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+
+const client = new MastraClient({
+  baseUrl: 'http://localhost:4111',
+})
+
+const response = await client.responses.create({
+  agent_id: 'support-agent',
+  input: 'Summarize this ticket',
+  store: true,
+})
+
+console.log(response.output_text)
+```
+
+## Methods
+
+### Lifecycle
+
+#### `create(params)`
+
+Creates a response.
+
+```typescript
+const response = await client.responses.create({
+  agent_id: 'support-agent',
+  input: 'Summarize this ticket',
+})
+```
+
+**Returns:** `Promise<ResponsesResponse>` when `stream` is omitted or `false`.
+
+When `stream: true`, `create()` returns an async iterable of SSE-style event payloads:
+
+```typescript
+const stream = await client.responses.create({
+  agent_id: 'support-agent',
+  input: 'Summarize this ticket',
+  stream: true,
+})
+
+for await (const event of stream) {
+  if (event.type === 'response.output_text.delta') {
+    process.stdout.write(event.delta)
+  }
+}
+```
+
+**Returns:** `Promise<ResponsesStream>`.
+
+#### `retrieve(responseId, requestContext?)`
+
+Retrieves a stored response.
+
+```typescript
+const response = await client.responses.retrieve('msg_123')
+```
+
+**Returns:** `Promise<ResponsesResponse>`.
+
+#### `delete(responseId, requestContext?)`
+
+Deletes a stored response.
+
+```typescript
+const deleted = await client.responses.delete('msg_123')
+```
+
+**Returns:** `Promise<{ id: string; object: "response"; deleted: true }>`
+
+#### `stream(params)`
+
+Creates a streaming response.
+
+```typescript
+const stream = await client.responses.stream({
+  agent_id: 'support-agent',
+  input: 'Say hello',
+})
+
+for await (const event of stream) {
+  console.log(event.type)
+}
+```
+
+**Returns:** `Promise<ResponsesStream>`.
+
+## Stored responses and conversations
+
+Stored responses include both `response.id` and `conversation_id`.
+
+- `response.id` is the response ID. For stored agent-backed responses, this is the persisted assistant message ID.
+- `conversation_id` is the raw Mastra thread ID.
+
+Use `previous_response_id` when you want to continue from a previous stored response. Use `conversation_id` when you want to target a known thread directly.
+
+```typescript
+const first = await client.responses.create({
+  agent_id: 'support-agent',
+  input: 'Start a support thread',
+  store: true,
+})
+
+const second = await client.responses.create({
+  agent_id: 'support-agent',
+  conversation_id: first.conversation_id!,
+  input: 'Add a follow-up to the same thread',
+  store: true,
+})
+```
+
+Use [`client.conversations`](https://mastra.ai/reference/client-js/conversations) when you want to create, retrieve, delete, or inspect the underlying OpenAI Responses API conversation directly.
+
+## Function calling (tools)
+
+`response.tools` contains the configured function definitions available for the request.
+
+If the model calls a function, that activity appears in `response.output` as `function_call` and `function_call_output` items alongside the final assistant `message`.
+
+## Structured output
+
+Use `text.format` when you want JSON output.
+
+- `json_object` enables JSON mode.
+- `json_schema` enables schema-constrained structured output.
+
+Mastra routes both through the agent's structured output path and still returns the JSON in the normal assistant message text output.
+
+```typescript
+const response = await client.responses.create({
+  agent_id: 'support-agent',
+  input: 'Return a structured support ticket summary.',
+  text: {
+    format: {
+      type: 'json_schema',
+      name: 'ticket_summary',
+      schema: {
+        type: 'object',
+        properties: {
+          summary: { type: 'string' },
+          priority: { type: 'string' },
+        },
+        required: ['summary', 'priority'],
+        additionalProperties: false,
+      },
+    },
+  },
+})
+```
+
+## Provider-backed requests
+
+Use `providerOptions` when you need provider-specific options that Mastra does not normalize at the Responses layer.
+
+```typescript
+const response = await client.responses.create({
+  agent_id: 'support-agent',
+  input: 'Continue this exchange',
+  providerOptions: {
+    openai: {
+      previousResponseId: 'resp_123',
+    },
+  },
+})
+```
+
+## Response shape
+
+The returned response object includes:
+
+- `id`: The response ID
+- `output`: Output items such as the assistant `message`, `function_call`, and `function_call_output`
+- `output_text`: Convenience getter that joins assistant text output
+- `tools`: Configured tool definitions for the request
+- `conversation_id`: The raw thread ID for stored responses
+- `text`: The requested text output format, when provided
+
+## Parameters
+
+**agent\_id** (`string`): Required on initial requests. Selects the Mastra agent that executes the request. Stored follow-up turns can omit it when continuing with \`previous\_response\_id\`.
+
+**model** (`string`): Optional model override for this request, such as \`openai/gpt-5\`. If omitted, Mastra uses the model configured on the selected agent.
+
+**input** (`string | Array<{ role: 'system' | 'developer' | 'user' | 'assistant'; content: string | Array<{ type: 'input_text' | 'text' | 'output_text'; text: string }> }>`): Required. Input text or message array for the response.
+
+**instructions** (`string`): Optional instruction override for this request.
+
+**text** (`{ format: { type: 'json_object' } | { type: 'json_schema'; name: string; schema: Record<string, unknown>; description?: string; strict?: boolean } }`): Optional text output format. Use \`json\_object\` for JSON mode or \`json\_schema\` for schema-constrained structured output.
+
+**providerOptions** (`Record<string, Record<string, unknown> | undefined>`): Optional provider-specific options passed through to the underlying model call.
+
+**stream** (`boolean`): When true, returns an async iterable of Responses API events.
+
+**store** (`boolean`): When true, persists the response through the selected agent memory.
+
+**conversation\_id** (`string`): Optional conversation identifier. In Mastra, this is the raw memory thread ID.
+
+**previous\_response\_id** (`string`): Continues a stored response chain from a previous stored response.
+
+**requestContext** (`RequestContext | Record<string, any>`): Optional request context forwarded to the Mastra server.

package/.docs/reference/index.md

@@ -41,11 +41,13 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [create-mastra](https://mastra.ai/reference/cli/create-mastra)
 - [mastra](https://mastra.ai/reference/cli/mastra)
 - [Agents API](https://mastra.ai/reference/client-js/agents)
+- [Conversations API](https://mastra.ai/reference/client-js/conversations)
 - [Error Handling](https://mastra.ai/reference/client-js/error-handling)
 - [Logs API](https://mastra.ai/reference/client-js/logs)
 - [Mastra Client SDK](https://mastra.ai/reference/client-js/mastra-client)
 - [Memory API](https://mastra.ai/reference/client-js/memory)
 - [Observability API](https://mastra.ai/reference/client-js/observability)
+- [Responses API](https://mastra.ai/reference/client-js/responses)
 - [Telemetry API](https://mastra.ai/reference/client-js/telemetry)
 - [Tools API](https://mastra.ai/reference/client-js/tools)
 - [Vectors API](https://mastra.ai/reference/client-js/vectors)

package/.docs/reference/server/routes.md

@@ -90,7 +90,7 @@ GET /api/agents/my-agent?versionId=abc123
 }
 ```
 
-### Start-async request body
+### Request body for `/start-async`
 
 ```typescript
 {
@@ -248,6 +248,27 @@ GET /api/agents/my-agent?versionId=abc123
 | `POST` | `/api/mcp/:serverId`               | MCP HTTP transport |
 | `GET`  | `/api/mcp/:serverId/sse`           | MCP SSE transport  |
 
+## Responses API
+
+| Method   | Path                            | Description                                                         |
+| -------- | ------------------------------- | ------------------------------------------------------------------- |
+| `POST`   | `/api/v1/responses`             | Create a response through the OpenAI-compatible Responses API route |
+| `GET`    | `/api/v1/responses/:responseId` | Retrieve a stored response                                          |
+| `DELETE` | `/api/v1/responses/:responseId` | Delete a stored response                                            |
+
+For the full request and response contract, see the [Responses API reference](https://mastra.ai/reference/client-js/responses).
+
+## Conversations API
+
+| Method   | Path                                          | Description                          |
+| -------- | --------------------------------------------- | ------------------------------------ |
+| `POST`   | `/api/v1/conversations`                       | Create a conversation                |
+| `GET`    | `/api/v1/conversations/:conversationId`       | Retrieve a conversation              |
+| `DELETE` | `/api/v1/conversations/:conversationId`       | Delete a conversation                |
+| `GET`    | `/api/v1/conversations/:conversationId/items` | List stored items for a conversation |
+
+For the full request and response contract, see the [Conversations API reference](https://mastra.ai/reference/client-js/conversations).
+
 ## Logs
 
 | Method | Path               | Description        |

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.1.20-alpha.1
+
+### Patch Changes
+
+- Updated dependencies [[`9a43b47`](https://github.com/mastra-ai/mastra/commit/9a43b476465e86c9aca381c2831066b5c33c999a)]:
+  - @mastra/core@1.21.0-alpha.0
+
 ## 1.1.19
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.20-alpha.0",
+  "version": "1.1.20-alpha.1",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,8 +29,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.20.0",
-    "@mastra/mcp": "^1.4.1"
+    "@mastra/mcp": "^1.4.1",
+    "@mastra/core": "1.21.0-alpha.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "4.0.18",
-    "@internal/types-builder": "0.0.52",
     "@internal/lint": "0.0.77",
-    "@mastra/core": "1.20.0"
+    "@internal/types-builder": "0.0.52",
+    "@mastra/core": "1.21.0-alpha.0"
   },
   "homepage": "https://mastra.ai",
   "repository": {