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

package/.docs/docs/observability/overview.md

@@ -1,35 +1,61 @@
 # Observability overview
 
-Mastra provides observability features for AI applications. Monitor LLM operations, trace agent decisions, and debug complex workflows with tools that understand AI-specific patterns.
+Mastra's observability system gives you visibility into every agent run, workflow step, tool call, and model interaction. It captures three complementary signals that work together to help you understand what your application is doing and why.
 
-## Key features
+- [**Tracing**](https://mastra.ai/docs/observability/tracing/overview): Records every operation as a hierarchical timeline of spans, capturing inputs, outputs, token usage, and timing.
+- [**Logging**](https://mastra.ai/docs/observability/logging): Forwards structured log entries from your application and Mastra internals to observability storage, correlated to traces automatically.
+- [**Metrics**](https://mastra.ai/docs/observability/metrics/overview): Extracts duration, token usage, and cost data from traces automatically, with no additional instrumentation required.
 
-### Tracing
+## When to use observability
 
-Specialized tracing for AI operations that captures:
+- Debug unexpected agent behavior by inspecting the full decision path, tool calls, and model responses.
+- Monitor latency across agents, workflows, and tools to identify bottlenecks.
+- Track token consumption and estimated cost over time to control spending.
+- Diagnose workflow failures by tracing execution through each step.
+- Compare agent performance before and after prompt or model changes.
 
-- **Model interactions**: Token usage, latency, prompts, and completions
-- **Agent execution**: Decision paths, tool calls, and memory operations
-- **Workflow steps**: Branching logic, parallel execution, and step outputs
-- **Automatic instrumentation**: Tracing with decorators
+## How the pieces fit together
 
-### Logging
+Tracing is the foundation. When observability is configured, every agent run, workflow execution, tool call, and model interaction produces a [span](https://opentelemetry.io/docs/concepts/signals/traces/#spans). Spans are organized into traces that show the full request lifecycle as a hierarchical timeline.
 
-All logger calls from your application and Mastra's internal components are automatically forwarded to observability storage when observability is configured. You can [control the log level and disable forwarding](https://mastra.ai/docs/observability/logging) independently from your console logger.
+Metrics are derived from traces automatically. When a span ends, Mastra extracts duration, token counts, and cost estimates without any extra code. These metrics power the dashboards in [Studio](https://mastra.ai/docs/studio/observability).
 
-## Storage requirements
+Logs are correlated to traces automatically. Every `logger.info()`, `logger.warn()`, or `logger.error()` call within a traced context is tagged with the current trace and span IDs. You can navigate from a log entry directly to the trace that produced it.
 
-The `DefaultExporter` persists traces to your configured storage backend. Not all storage providers support observability—for the full list, see [Storage Provider Support](https://mastra.ai/docs/observability/tracing/exporters/default).
+All three signals share correlation IDs (trace ID, span ID, entity type, entity name), so you can jump between a metric spike, the traces behind it, and the logs within those traces.
 
-For production environments with high traffic, we recommend using **ClickHouse** for the observability domain via [composite storage](https://mastra.ai/reference/storage/composite). See [Production Recommendations](https://mastra.ai/docs/observability/tracing/exporters/default) for details.
+## Get started
 
-## Quickstart
+Install `@mastra/observability` and a storage backend:
 
-Configure Observability in your Mastra instance:
+**npm**:
+
+```bash
+npm install @mastra/observability @mastra/libsql @mastra/duckdb
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/observability @mastra/libsql @mastra/duckdb
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/observability @mastra/libsql @mastra/duckdb
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/observability @mastra/libsql @mastra/duckdb
+```
+
+Then configure observability in your Mastra instance. The following example uses composite storage to route observability data to DuckDB (which supports metrics aggregation) while keeping everything else in LibSQL:
 
 ```ts
 import { Mastra } from '@mastra/core/mastra'
-import { PinoLogger } from '@mastra/loggers'
 import { LibSQLStore } from '@mastra/libsql'
 import { DuckDBStore } from '@mastra/duckdb'
 import { MastraCompositeStore } from '@mastra/core/storage'
@@ -41,7 +67,6 @@ import {
 } from '@mastra/observability'
 
 export const mastra = new Mastra({
-  logger: new PinoLogger(),
   storage: new MastraCompositeStore({
     id: 'composite-storage',
     default: new LibSQLStore({
@@ -60,9 +85,6 @@ export const mastra = new Mastra({
           new DefaultExporter(), // Persists traces to storage for Mastra Studio
           new CloudExporter(), // Sends traces to Mastra Cloud (if MASTRA_CLOUD_ACCESS_TOKEN is set)
         ],
-        logging: {
-          level: 'info', // Minimum log level forwarded to storage (default: 'debug')
-        },
         spanOutputProcessors: [
           new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
         ],
@@ -72,14 +94,18 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Serverless environments:** The `file:./mastra.db` storage URL uses the local filesystem, which doesn't work in serverless environments like Vercel, AWS Lambda, or Cloudflare Workers. For serverless deployments, use external storage. See the [Vercel deployment guide](https://mastra.ai/guides/deployment/vercel) for a complete example.
+This enables tracing, log forwarding, and metrics. Mastra also supports external tracing providers like Langfuse, Datadog, and any OpenTelemetry-compatible platform. See [Tracing](https://mastra.ai/docs/observability/tracing/overview) for configuration details.
+
+## Storage
 
-With this basic setup, you will see Traces and Logs in both Studio and in Mastra Cloud.
+Not all storage backends support every signal. Traces and logs work with most backends, but metrics require an OLAP-capable store like DuckDB (development) or ClickHouse (production). For the full compatibility list, see [storage provider support](https://mastra.ai/docs/observability/tracing/exporters/default).
 
-We also support various external tracing providers like MLflow, Langfuse, Braintrust, and any OpenTelemetry-compatible platform (Datadog, New Relic, SigNoz, etc.). See more about this in the [Tracing](https://mastra.ai/docs/observability/tracing/overview) documentation.
+For production environments with high traffic, use composite storage to route the observability domain to a dedicated backend. See [production recommendations](https://mastra.ai/docs/observability/tracing/exporters/default) for details.
 
-## What's next?
+## Next steps
 
-- **[Set up Tracing](https://mastra.ai/docs/observability/tracing/overview)**: Configure tracing for your application
-- **[Configure Logging](https://mastra.ai/docs/observability/logging)**: Add structured logging
-- **[API Reference](https://mastra.ai/reference/observability/tracing/instances)**: Detailed configuration options
+- [Tracing](https://mastra.ai/docs/observability/tracing/overview)
+- [Logging](https://mastra.ai/docs/observability/logging)
+- [Metrics](https://mastra.ai/docs/observability/metrics/overview)
+- [Mastra Studio](https://mastra.ai/docs/studio/observability)
+- [Automatic metrics reference](https://mastra.ai/reference/observability/metrics/automatic-metrics)

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/docs/studio/observability.md

@@ -4,6 +4,7 @@ Studio includes these observability views:
 
 - **Metrics** for aggregate performance data
 - **Traces** for individual request inspection
+- **Logs** for browsing internal and application logs
 
 All require an [observability storage backend](#quickstart) to be configured.
 
@@ -21,6 +22,12 @@ When you run an agent or workflow, the Observability tab displays traces that hi
 
 Tracing filters out low-level framework details so your traces stay focused and readable. Visit the [tracing overview](https://mastra.ai/docs/observability/tracing/overview) for more details.
 
+## Logs
+
+Browse internal Mastra logs forwarded to your observability storage. Logs provide full-text search (across message content, entity names, and trace IDs), date presets (last 24 hours to 30 days), and multi-select filters for level, entity type, and entity name. Selecting a log opens a detail panel showing the full message, structured data, and metadata. If the log is correlated with a trace, you can navigate directly to the trace and span timeline.
+
+Log forwarding is enabled by default when you configure observability. See [logging](https://mastra.ai/docs/observability/logging) for level configuration, query examples, and customization details.
+
 ## Quickstart
 
 For detailed instructions, follow the [observability instructions](https://mastra.ai/docs/observability/overview). To get up and running quickly, add the `@mastra/observability` package to your project and configure it with [LibSQL](https://mastra.ai/reference/storage/libsql) and [DuckDB](https://mastra.ai/reference/vectors/duckdb) for a local development setup that supports both traces and metrics.
@@ -95,4 +102,5 @@ export const mastra = new Mastra({
 
 - [Observability overview](https://mastra.ai/docs/observability/overview)
 - [Metrics overview](https://mastra.ai/docs/observability/metrics/overview)
-- [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)
+- [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)
+- [Logging](https://mastra.ai/docs/observability/logging)

package/.docs/docs/studio/overview.md

@@ -124,4 +124,4 @@ Mastra also supports HTTPS development through the [`--https`](https://mastra.ai
 
 - Learn how to [deploy Studio](https://mastra.ai/docs/studio/deployment) for production use.
 - Add [authentication](https://mastra.ai/docs/studio/auth) to control access to your deployed Studio.
-- Explore [Studio observability](https://mastra.ai/docs/studio/observability) to monitor agent performance and gain insights through metrics, logs, and traces.
+- Explore [Studio observability](https://mastra.ai/docs/studio/observability) to monitor agent performance through metrics, traces, and logs.

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.
+
+Both formats return JSON in the assistant message content. Use `json_schema` when you need strict schema enforcement. Use `json_object` when you only need valid JSON 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,19 @@
 # @mastra/mcp-docs-server
 
+## 1.1.20-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`13f4327`](https://github.com/mastra-ai/mastra/commit/13f4327f052faebe199cefbe906d33bf90238767)]:
+  - @mastra/core@1.21.0-alpha.1
+
+## 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.3",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.20.0",
+    "@mastra/core": "1.21.0-alpha.1",
     "@mastra/mcp": "^1.4.1"
   },
   "devDependencies": {
@@ -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.1"
   },
   "homepage": "https://mastra.ai",
   "repository": {