@mastra/mcp-docs-server 1.0.0-beta.11 → 1.0.0-beta.14

package/.docs/raw/guides/migrations/vnext-to-standard-apis.mdx

@@ -106,7 +106,7 @@ See the following API references for more information:
 
 No `format` option: Always return AI SDK v4 types
 
-```typescript showLineNumbers copy
+```typescript
 // Mastra native format (default)
 const result = await agent.stream(messages);
 ```
@@ -118,7 +118,7 @@ Use `format` option to choose output:
 - `'mastra'` (default)
 - `'aisdk'` (AI SDK v5 compatible)
 
-```typescript showLineNumbers copy
+```typescript
 // AI SDK v5 compatibility
 const result = await agent.stream(messages, {
   format: "aisdk",
@@ -131,7 +131,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `format` - Choose between 'mastra' or 'aisdk' output format:
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     format: "aisdk", // or 'mastra' (default)
   });
@@ -139,7 +139,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `system` - Custom system message (separate from instructions).
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     system: "You are a helpful assistant",
   });
@@ -153,7 +153,7 @@ The following options are available in the standard `.stream()` and `generate()`
     - 'error' - throw an error
     - 'fallback' - return a fallback value you provide
 
-    ```typescript showLineNumbers copy
+    ```typescript copy
     const result = await agent.generate(messages, {
       structuredOutput: {
         schema: z.object({
@@ -170,7 +170,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `stopWhen` - Flexible stop conditions (step count, token limit, etc).
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     stopWhen: ({ steps, totalTokens }) => steps >= 5 || totalTokens >= 10000,
   });
@@ -178,7 +178,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `providerOptions` - Provider-specific options (e.g., OpenAI-specific settings)
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     providerOptions: {
       openai: {
@@ -191,7 +191,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `onChunk` - Callback for each streaming chunk.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     onChunk: (chunk) => {
       console.log("Received chunk:", chunk);
@@ -201,7 +201,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `onError` - Error callback.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     onError: (error) => {
       console.error("Stream error:", error);
@@ -211,7 +211,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `onAbort` - Abort callback.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     onAbort: () => {
       console.log("Stream aborted");
@@ -221,7 +221,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `activeTools` - Specify which tools are active for this execution.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     activeTools: ["search", "calculator"], // Only these tools will be available
   });
@@ -229,7 +229,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `abortSignal` - AbortSignal for cancellation.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const controller = new AbortController();
   const result = await agent.stream(messages, {
     abortSignal: controller.signal,
@@ -240,7 +240,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `prepareStep` - Callback before each step in multi-step execution.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     prepareStep: ({ step, state }) => {
       console.log("About to execute step:", step);
@@ -253,7 +253,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
 - `requireToolApproval` - Require approval for all tool calls.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     requireToolApproval: true,
   });
@@ -265,7 +265,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
   Unified in `modelSettings`
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     modelSettings: {
       temperature: 0.7,
@@ -279,7 +279,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
   Moved to memory object.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.stream(messages, {
     memory: {
       resource: "user-123",
@@ -294,7 +294,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
   Use `structuredOutput` instead to allow for tool calls and an object return.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.generate(messages, {
     structuredOutput: {
       schema: z.object({
@@ -309,7 +309,7 @@ The following options are available in the standard `.stream()` and `generate()`
 
   The `output` property is deprecated in favor of `structuredOutput`, to achieve the same results, omit the model and only pass `structuredOutput.schema`, optionally add `jsonPromptInjection: true` if your model does not natively support `response_format`.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.generate(messages, {
     structuredOutput: {
       schema: {
@@ -325,11 +325,9 @@ The following options are available in the standard `.stream()` and `generate()`
 
   Use `memory` instead.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   const result = await agent.generate(messages, {
-    memory: {
-      // ...
-    },
+    memory: {},
   });
   ```
 
@@ -350,7 +348,7 @@ See the following API references for more information:
 
   `toolChoice` uses the AI SDK v5 `ToolChoice` type.
 
-  ```typescript showLineNumbers copy
+  ```typescript copy
   type ToolChoice<TOOLS extends Record<string, unknown>> =
     | "auto"
     | "none"

package/.docs/raw/index.mdx

@@ -27,9 +27,9 @@ Some highlights include:
 
 - [**Workflows**](/docs/v1/workflows/overview) - When you need explicit control over execution, use Mastra's graph-based workflow engine to orchestrate complex multi-step processes. Mastra workflows use an intuitive syntax for control flow (`.then()`, `.branch()`, `.parallel()`).
 
-- [**Human-in-the-loop**](/docs/v1/workflows/suspend-and-resume) - Suspend an agent or workflow and await user input or approval before resuming. Mastra uses [storage](/docs/v1/server-db/storage) to remember execution state, so you can pause indefinitely and resume where you left off.
+- [**Human-in-the-loop**](/docs/v1/workflows/suspend-and-resume) - Suspend an agent or workflow and await user input or approval before resuming. Mastra uses storage to remember execution state, so you can pause indefinitely and resume where you left off.
 
-- **Context management** - Give your agents the right context at the right time. Provide [conversation history](/docs/v1/memory/conversation-history), [retrieve](/docs/v1/rag/overview) data from your sources (APIs, databases, files), and add human-like [working](/docs/v1/memory/working-memory) and [semantic](/docs/v1/memory/semantic-recall) memory so your agents behave coherently.
+- **Context management** - Give your agents the right context at the right time. Provide [message history](/docs/v1/memory/message-history), [retrieve](/docs/v1/rag/overview) data from your sources (APIs, databases, files), and add human-like [working](/docs/v1/memory/working-memory) and [semantic](/docs/v1/memory/semantic-recall) memory so your agents behave coherently.
 
 - **Integrations** - Bundle agents and workflows into existing React, Next.js, or Node.js apps, or ship them as standalone endpoints. When building UIs, integrate with agentic libraries like Vercel's AI SDK UI and CopilotKit to bring your AI assistant to life on the web.
 

package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/dashboard.mdx

@@ -3,13 +3,9 @@ title: "Navigating the Dashboard | Mastra Cloud"
 description: Details of each feature available in Mastra Cloud
 ---
 
-import { MastraCloudCallout } from "@site/src/components/MastraCloudCallout";
-
 # Navigating the Dashboard
 
-This page explains how to navigate the Mastra Cloud dashboard, where you can configure your project, view deployment details, and interact with agents and workflows using the built-in [Studio](/docs/v1/deployment/mastra-cloud/dashboard#studio).
-
-<MastraCloudCallout />
+This page explains how to navigate the Mastra Cloud dashboard, where you can configure your project, view deployment details, and interact with agents and workflows using the built-in [Studio](/docs/v1/mastra-cloud/dashboard#studio).
 
 ## Overview
 
@@ -97,4 +93,4 @@ Each MCP Server includes API endpoints for HTTP and SSE, along with IDE configur
 
 ## Next steps
 
-- [Understanding Tracing and Logs](/docs/v1/deployment/mastra-cloud/observability)
+- [Understanding Tracing and Logs](/docs/v1/mastra-cloud/observability)

package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/observability.mdx

@@ -3,16 +3,12 @@ title: "Understanding Tracing and Logs | Mastra Cloud"
 description: Monitoring and debugging tools for Mastra Cloud deployments
 ---
 
-import { MastraCloudCallout } from "@site/src/components/MastraCloudCallout";
-
 # Understanding Tracing and Logs
 
 Mastra Cloud provides full observability for production applications, giving you insight into how your agents and workflows behave. Observability can be enabled whether your application is deployed to Mastra Cloud, running locally, or hosted on your own infrastructure. Any Mastra project can send traces and logs to the platform regardless of where it's running.
 
 For details on configuring observability, see the [Cloud Exporter](/docs/v1/observability/tracing/exporters/cloud) docs.
 
-<MastraCloudCallout />
-
 ## Traces
 
 More detailed traces are available for both agents and workflows by enabling [observability](/docs/v1/observability/tracing/overview) using one of our [supported providers](/docs/v1/observability/tracing/overview#exporters).
@@ -39,7 +35,7 @@ Workflow traces capture each step in the run, including transitions, branching,
 
 ## Logs
 
-You can view detailed logs for debugging and monitoring your application's behavior on the [Logs](/docs/v1/deployment/mastra-cloud/dashboard#logs) page of the Dashboard.
+You can view detailed logs for debugging and monitoring your application's behavior on the [Logs](/docs/v1/mastra-cloud/dashboard#logs) page of the Dashboard.
 
 ![Dashboard logs](/img/mastra-cloud/mastra-cloud-dashboard-logs.jpg)
 

package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/overview.mdx

@@ -3,13 +3,9 @@ title: "Mastra Cloud | Mastra Cloud"
 description: Deployment and monitoring service for Mastra applications
 ---
 
-import { MastraCloudCallout } from "@site/src/components/MastraCloudCallout";
-
 # Mastra Cloud
 
-[Mastra Cloud](https://mastra.ai/cloud) is a platform for deploying, managing, monitoring, and debugging Mastra applications. When you [deploy](/docs/v1/deployment/mastra-cloud/setting-up) your application, Mastra Cloud exposes your agents, tools, and workflows as REST API endpoints.
-
-<MastraCloudCallout />
+[Mastra Cloud](https://mastra.ai/cloud) is a platform for deploying, managing, monitoring, and debugging Mastra applications. When you [deploy](/docs/v1/mastra-cloud/setting-up) your application, Mastra Cloud exposes your agents, tools, and workflows as REST API endpoints.
 
 ## Platform features
 
@@ -62,4 +58,4 @@ Mastra Cloud is purpose-built for Mastra agents, tools, and workflows. It handle
 
 ## Next steps
 
-- [Setting Up and Deploying](/docs/v1/deployment/mastra-cloud/setting-up)
+- [Setting Up and Deploying](/docs/v1/mastra-cloud/setting-up)

package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/setting-up.mdx

@@ -3,7 +3,6 @@ title: "Setting Up and Deploying | Mastra Cloud"
 description: Configuration steps for Mastra Cloud projects
 ---
 
-import { MastraCloudCallout } from "@site/src/components/MastraCloudCallout";
 import Steps from "@site/src/components/Steps";
 import StepItem from "@site/src/components/StepItem";
 
@@ -11,14 +10,16 @@ import StepItem from "@site/src/components/StepItem";
 
 This page explains how to set up a project on [Mastra Cloud](https://mastra.ai/cloud) with automatic deployments using our GitHub integration.
 
-<MastraCloudCallout />
-
 ## Prerequisites
 
 - A [Mastra Cloud](https://mastra.ai/cloud) account
 - A GitHub account / repository containing a Mastra application
 
-> See our [Getting started](/guides/v1/getting-started/quickstart) guide to scaffold out a new Mastra project with sensible defaults.
+:::info
+
+Visit our [Getting started](/guides/v1/getting-started/quickstart) guide to scaffold out a new Mastra project with sensible defaults.
+
+:::
 
 ## Setup and Deploy process
 
@@ -73,7 +74,7 @@ Mastra Cloud automatically detects the right build settings, but you can customi
   - **Install command**: Runs pre-build to install project dependencies
   - **Project setup command**: Runs pre-build to prepare any external dependencies
   - **Port**: The network port the server will use
-  - **Store settings**: Use Mastra Cloud's built-in [LibSQLStore](/docs/v1/server-db/storage) storage
+  - **Store settings**: Use Mastra Cloud's built-in [LibSQLStore](/reference/v1/storage/libsql) storage
 - **Deploy Project**: Starts the deployment process
 
 </StepItem>
@@ -98,8 +99,8 @@ Your project is now configured with automatic deployments which occur whenever y
 
 ## Testing your application
 
-After a successful deployment you can test your agents and workflows [Studio](/docs/v1/deployment/mastra-cloud/dashboard#studio) in Mastra Cloud, or interact with them using our [Client SDK](/docs/v1/server-db/mastra-client).
+After a successful deployment you can test your agents and workflows [Studio](/docs/v1/mastra-cloud/dashboard#studio) in Mastra Cloud, or interact with them using our [Client SDK](/docs/v1/server/mastra-client).
 
 ## Next steps
 
-- [Navigating the Dashboard](/docs/v1/deployment/mastra-cloud/dashboard)
+- [Navigating the Dashboard](/docs/v1/mastra-cloud/dashboard)

package/.docs/raw/mcp/overview.mdx

@@ -29,7 +29,7 @@ npm install @mastra/mcp@beta
 
 The `MCPClient` connects Mastra primitives to external MCP servers, which can be local packages (invoked using `npx`) or remote HTTP(S) endpoints. Each server must be configured with either a `command` or a `url`, depending on how it's hosted.
 
-```typescript title="src/mastra/mcp/test-mcp-client.ts" showLineNumbers copy
+```typescript title="src/mastra/mcp/test-mcp-client.ts"
 import { MCPClient } from "@mastra/mcp";
 
 export const testMcpClient = new MCPClient({
@@ -48,13 +48,17 @@ export const testMcpClient = new MCPClient({
 });
 ```
 
-> See [MCPClient](/reference/v1/tools/mcp-client) for a full list of configuration options.
+:::info
+
+Visit [MCPClient](/reference/v1/tools/mcp-client) for a full list of configuration options.
+
+:::
 
 ## Using `MCPClient` with an agent
 
 To use tools from an MCP server in an agent, import your `MCPClient` and call `.getTools()` in the `tools` parameter. This loads from the defined MCP servers, making them available to the agent.
 
-```typescript {3,15} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
+```typescript {3,15} title="src/mastra/agents/test-agent.ts"
 import { Agent } from "@mastra/core/agent";
 
 import { testMcpClient } from "../mcp/test-mcp-client";
@@ -73,13 +77,17 @@ export const testAgent = new Agent({
 });
 ```
 
-> See the [Agent Class](/reference/v1/agents/agent) for a full list of configuration options.
+:::info
+
+Visit [Agent Class](/reference/v1/agents/agent) for a full list of configuration options.
+
+:::
 
 ## Configuring `MCPServer`
 
 To expose agents, tools, and workflows from your Mastra application to external systems over HTTP(S) use the `MCPServer` class. This makes them accessible to any system or agent that supports the protocol.
 
-```typescript title="src/mastra/mcp/test-mcp-server.ts" showLineNumbers copy
+```typescript title="src/mastra/mcp/test-mcp-server.ts"
 import { MCPServer } from "@mastra/mcp";
 
 import { testAgent } from "../agents/test-agent";
@@ -96,19 +104,22 @@ export const testMcpServer = new MCPServer({
 });
 ```
 
-> See [MCPServer](/reference/v1/tools/mcp-server) for a full list of configuration options.
+:::info
+
+Visit [MCPServer](/reference/v1/tools/mcp-server) for a full list of configuration options.
+
+:::
 
 ## Registering an `MCPServer`
 
 To make an MCP server available to other systems or agents that support the protocol, register it in the main `Mastra` instance using `mcpServers`.
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core/mastra";
 
 import { testMcpServer } from "./mcp/test-mcp-server";
 
 export const mastra = new Mastra({
-  // ...
   mcpServers: { testMcpServer },
 });
 ```
@@ -128,15 +139,18 @@ export const mastra = new Mastra({
 
 Use the `.getTools()` method to fetch tools from all configured MCP servers. This is suitable when configuration (such as API keys) is static and consistent across users or requests. Call it once and pass the result to the `tools` property when defining your agent.
 
-> See [getTools()](/reference/v1/tools/mcp-client#gettools) for more information.
+:::info
+
+Visit [getTools()](/reference/v1/tools/mcp-client#gettools) for more information.
+
+:::
 
-```typescript {7} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
+```typescript {6} title="src/mastra/agents/test-agent.ts"
 import { Agent } from "@mastra/core/agent";
 
 import { testMcpClient } from "../mcp/test-mcp-client";
 
 export const testAgent = new Agent({
-  // ...
   tools: await testMcpClient.getTools(),
 });
 ```
@@ -145,7 +159,7 @@ export const testAgent = new Agent({
 
 Use the `.getToolsets()` method when tool configuration may vary by request or user, such as in a multi-tenant system where each user provides their own API key. This method returns toolsets that can be passed to the `toolsets` option in the agent's `.generate()` or `.stream()` calls.
 
-```typescript {5-16,21} showLineNumbers copy
+```typescript {5-16,21}
 import { MCPClient } from "@mastra/mcp";
 import { mastra } from "./mastra";
 
@@ -177,7 +191,11 @@ async function handleRequest(userPrompt: string, userApiKey: string) {
 }
 ```
 
-> See [getToolsets()](/reference/v1/tools/mcp-client#gettoolsets) for more information.
+:::info
+
+Visit [getToolsets()](/reference/v1/tools/mcp-client#gettoolsets) for more information.
+
+:::
 
 ## Connecting to an MCP registry
 

package/.docs/raw/mcp/publishing-mcp-server.mdx

@@ -32,7 +32,7 @@ Create a file for your stdio server, for example, `/src/mastra/stdio.ts`.
 
 Add the following code to the file. Remember to import your actual Mastra tools and name the server appropriately.
 
-```typescript title="src/mastra/stdio.ts" copy
+```typescript title="src/mastra/stdio.ts"
 #!/usr/bin/env node
 import { MCPServer } from "@mastra/mcp";
 import { weatherTool } from "./tools";
@@ -55,7 +55,7 @@ server.startStdio().catch((error) => {
 
 Update your `package.json` to include the `bin` entry pointing to your built server file and a script to build the server with both ESM and CJS outputs.
 
-```json title="package.json" copy
+```json title="package.json"
 {
   "bin": "dist/stdio.mjs",
   "scripts": {

package/.docs/raw/memory/memory-processors.mdx

@@ -7,7 +7,7 @@ description: "Learn how to use memory processors in Mastra to filter, trim, and
 
 Memory processors transform and filter messages as they pass through an agent with memory enabled. They manage context window limits, remove unnecessary content, and optimize the information sent to the language model.
 
-When memory is enabled on an agent, Mastra adds memory processors to the agent's processor pipeline. These processors retrieve conversation history, working memory, and semantically relevant messages, then persist new messages after the model responds.
+When memory is enabled on an agent, Mastra adds memory processors to the agent's processor pipeline. These processors retrieve message history, working memory, and semantically relevant messages, then persist new messages after the model responds.
 
 Memory processors are [processors](/docs/v1/agents/processors) that operate specifically on memory-related messages and state.
 
@@ -17,7 +17,7 @@ Mastra automatically adds these processors when memory is enabled:
 
 ### MessageHistory
 
-Retrieves conversation history and persists new messages.
+Retrieves message history and persists new messages.
 
 **When you configure:**
 
@@ -40,7 +40,7 @@ memory: new Memory({
 
 **Example:**
 
-```typescript copy showLineNumbers
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { LibSQLStore } from "@mastra/libsql";
@@ -89,7 +89,7 @@ memory: new Memory({
 
 **Example:**
 
-```typescript copy showLineNumbers
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { LibSQLStore } from "@mastra/libsql";
@@ -145,7 +145,7 @@ memory: new Memory({
 
 **Example:**
 
-```typescript copy showLineNumbers
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { LibSQLStore } from "@mastra/libsql";
@@ -169,7 +169,7 @@ const agent = new Agent({
 
 If you manually add a memory processor to `inputProcessors` or `outputProcessors`, Mastra will **not** automatically add it. This gives you full control over processor ordering:
 
-```typescript copy showLineNumbers
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { MessageHistory } from "@mastra/memory/processors";
@@ -211,7 +211,7 @@ Understanding the execution order is important when combining guardrails with me
 1. **Memory processors run FIRST**: `WorkingMemory`, `MessageHistory`, `SemanticRecall`
 2. **Your input processors run AFTER**: guardrails, filters, validators
 
-This means memory loads conversation history before your processors can validate or filter the input.
+This means memory loads message history before your processors can validate or filter the input.
 
 ### Output Processors
 
@@ -236,7 +236,7 @@ Output guardrails run **before** memory processors save messages. If a guardrail
 - Memory processors are skipped
 - **No messages are persisted to storage**
 
-```typescript copy showLineNumbers
+```typescript
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { openai } from "@ai-sdk/openai";
@@ -281,7 +281,7 @@ Input guardrails run **after** memory processors load history. If a guardrail ab
 - Output processors (including memory persistence) are skipped
 - **No messages are persisted to storage**
 
-```typescript copy showLineNumbers
+```typescript
 // Input guardrail that validates user input
 const inputValidator = {
   id: "input-validator",

package/.docs/raw/memory/message-history.mdx

@@ -0,0 +1,69 @@
+---
+title: "Message History | Memory"
+description: "Learn how to configure message history in Mastra to store recent messages from the current conversation."
+---
+
+# Message History
+
+Message history is the simplest kind of memory. It is a list of messages from the current conversation.
+
+Once enabled, each request includes the last 10 messages from the current memory thread, giving the agent short-term conversational context. This limit can be increased using the `lastMessages` parameter:
+
+```typescript
+export const agent = new Agent({
+  id: "test-agent",
+  memory: new Memory({
+    options: {
+      lastMessages: 20,
+    },
+  }),
+});
+```
+
+## Querying Messages
+
+Messages are stored in the `MastraDBMessage` format, which provides a consistent structure across the entire Mastra system:
+
+```typescript 
+// Get messages for a thread with pagination
+const result = await mastra
+  .getStorage()
+  .listMessages({
+    threadId: "your-thread-id",
+    page: 0,
+    perPage: 50
+  });
+
+console.log(result.messages); // MastraDBMessage[]
+console.log(result.total); // Total count
+console.log(result.hasMore); // Whether more pages exist
+
+// Get messages from multiple threads at once
+const multiThreadResult = await mastra
+  .getStorage()
+  .listMessages({
+    threadId: ["thread-1", "thread-2", "thread-3"],
+    page: 0,
+    perPage: 100
+  });
+
+// Get messages by their IDs
+const messages = await mastra
+  .getStorage()
+  .listMessagesById({ messageIds: messageIdArr });
+```
+
+The `threadId` parameter accepts either a single thread ID string or an array of thread IDs to query messages from multiple threads in a single request.
+
+All message queries return `MastraDBMessage[]` format. If you need to convert messages to AI SDK formats for UI rendering, use the conversion utilities from `@mastra/ai-sdk/ui`:
+
+```typescript 
+import { toAISdkV5Messages } from '@mastra/ai-sdk/ui';
+
+const result = await mastra
+  .getStorage()
+  .listMessages({ threadId: "your-thread-id" });
+
+// Convert to AI SDK v5 UIMessage format for UI rendering
+const uiMessages = toAISdkV5Messages(result.messages);
+```