@mastra/mcp-docs-server 1.0.0-beta.13 → 1.0.0-beta.15

package/.docs/raw/mastra-cloud/setup.mdx

@@ -0,0 +1,64 @@
+---
+title: "Setup | Mastra Cloud"
+description: Import your Mastra project to Mastra Cloud
+---
+
+import Steps from "@site/src/components/Steps";
+import StepItem from "@site/src/components/StepItem";
+
+# Setup
+
+Import your Mastra project to [Mastra Cloud](https://cloud.mastra.ai) to use [Studio](/docs/v1/mastra-cloud/studio) and optionally [deploy](/docs/v1/mastra-cloud/deployment) your agent.
+
+## Before you begin
+
+- [Sign in](https://cloud.mastra.ai) to Cloud
+- Push your [Mastra project](/docs/v1/getting-started/start) to GitHub
+
+## Options
+
+
+![Select project type](/img/mastra-cloud/mastra-cloud-select.png)
+
+When you create a new project, you can choose from three options:
+
+1. **Create from GitHub** - Import a Mastra project from GitHub
+2. **Create from your server** - Connect a self-hosted Mastra instance to [Studio](/docs/v1/mastra-cloud/studio)
+3. **Create from template** - Start from a [pre-built template](https://mastra.ai/templates)
+
+
+To create a project from GitHub, follow these steps:
+
+## Create from GitHub
+
+<Steps>
+
+<StepItem>
+Connect to GitHub when prompted
+
+![Deployment details](/img/mastra-cloud/mastra-cloud-connect.png)
+</StepItem>
+
+<StepItem>
+Search for your repository and click **Import**
+
+![Deployment details](/img/mastra-cloud/mastra-cloud-import-git-repository.jpg)
+</StepItem>
+
+<StepItem>
+Configure your project settings. Mastra Cloud auto-detects most settings, but you'll still need to enter the environment variables for your configured [model provider](/models/v1):
+
+![Deployment details](/img/mastra-cloud/mastra-cloud-deployment-details.jpg)
+</StepItem>
+
+<StepItem>
+
+Click **Create Project**
+</StepItem>
+</Steps>
+
+## Next steps
+
+Once your project is imported, [Studio](/docs/v1/mastra-cloud/studio) automatically creates a sandbox where you can interact with your agents and share access with your team.
+
+When you're ready for production, enable [Deployment](/docs/v1/mastra-cloud/deployment) settings and hit deploy!

package/.docs/raw/mastra-cloud/studio.mdx

@@ -0,0 +1,35 @@
+---
+title: "Studio | Mastra Cloud"
+description: Run Studio in the cloud for team collaboration
+---
+
+import YouTube from "@site/src/components/YouTube-player";
+
+# Studio
+
+<YouTube id="ojGu6Bi4wYk" />
+
+Mastra Cloud provides a hosted version of [Studio](/docs/v1/getting-started/studio) that gives your team a shared environment for interacting with and testing your agents. Team members can chat with agents, review traces, give feedback, and tweak system prompts - without needing to run the project locally.
+
+[Set up your project](/docs/v1/mastra-cloud/setup) to access Studio in the cloud.
+
+See the [Studio documentation](/docs/v1/getting-started/studio) for details on features like the Agents playground, Workflows runner, Tools testing, and MCP Servers.
+
+:::note
+You don't need to deploy your agent to use Studio. Studio runs in a sandbox environment separate from your production deployment
+:::
+
+## Sharing access
+
+To invite team members, go to [Mastra Cloud](https://cloud.mastra.ai), click **Team Settings**, then **Members** to add them. Once invited, they can sign in and access your project's Studio.
+
+![Invite team members](/img/mastra-cloud/mastra-cloud-invite.png)
+
+:::warning
+Team members can view environment variables and delete projects. Only invite people you trust.
+:::
+
+## Next steps
+
+- [Deployment](/docs/v1/mastra-cloud/deployment) - Manage deployments and settings
+- [Observability](/docs/v1/mastra-cloud/observability) - Monitor traces and logs

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);
+```

package/.docs/raw/memory/overview.mdx

@@ -1,32 +1,35 @@
 ---
 title: "Memory overview | Memory"
-description: "Learn how Mastra's memory system works with working memory, conversation history, and semantic recall."
+description: "Learn how Mastra's memory system works with working memory, message history, and semantic recall."
 ---
 
-# Memory Overview
+# Memory
 
-Memory in Mastra helps agents manage context across conversations by condensing relevant information into the language model's context window.
+Memory gives your agent coherence across interactions and allows it to improve over time by retaining relevant information from past conversations.
 
-Mastra supports three types of memory: working memory, conversation history, and semantic recall. It uses a two-tier scoping system where memory can be isolated per conversation thread (thread-scoped) or shared across all conversations for the same user (resource-scoped).
+Mastra requires a [storage provider](./storage) to persist memory and supports three types:
 
-Mastra's memory system uses [storage providers](#memory-storage-adapters) to persist conversation threads, messages, and working memory across application restarts.
+- [**Message history**](/docs/v1/memory/message-history) captures recent messages from the current conversation, providing short-term continuity and maintaining dialogue flow.
+- [**Working memory**](/docs/v1/memory/working-memory) stores persistent user-specific details such as names, preferences, goals, and other structured data.
+- [**Semantic recall**](/docs/v1/memory/semantic-recall) retrieves older messages from past conversations based on semantic relevance. Matches are retrieved using vector search and can include surrounding context for better comprehension.
+
+You can enable any combination of these memory types. Mastra assembles the relevant memories into the model’s context window. If the total exceeds the model's token limit, use [memory processors](/docs/v1/memory/memory-processors) to trim or filter messages before sending them to the model.
 
 ## Getting started
 
-First install the required dependencies:
+Install Mastra's memory module and the storage adapter for your preferred database (see the storage section below):
 
-```bash copy
-npm install @mastra/core@beta @mastra/memory@beta @mastra/libsql@beta
+```bash 
+npm install @mastra/memory@beta @mastra/libsql@beta
 ```
 
-Then add a storage adapter to the main Mastra instance. Any agent with memory enabled will use this shared storage to store and recall interactions.
+Add the storage adapter to the main Mastra instance:
 
-```typescript {6-8} title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { LibSQLStore } from "@mastra/libsql";
 
 export const mastra = new Mastra({
-  // ...
   storage: new LibSQLStore({
     id: 'mastra-storage',
     url: ":memory:",
@@ -34,88 +37,43 @@ export const mastra = new Mastra({
 });
 ```
 
-Now, enable memory by passing a `Memory` instance to the agent's `memory` parameter:
-
-```typescript {3-5} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
-import { Memory } from "@mastra/memory";
-import { Agent } from "@mastra/core/agent";
-
-export const testAgent = new Agent({
-  id: "test-agent",
-  // ...
-  memory: new Memory(),
-});
-```
-
-That memory instance has options you can configure for working memory, conversation history, and semantic recall.
-
-## Different types of memory
-
-Mastra supports three types of memory: working memory, conversation history, and semantic recall.
-
-[**Working memory**](./working-memory) stores persistent user-specific details such as names, preferences, goals, and other structured data. (Compare this to ChatGPT where you can ask it to tell you about yourself). This is implemented as a block of Markdown text that the agent is able to update over time (or alternately, as a Zod schema)
-
-[**Conversation history**](./conversation-history) captures recent messages from the current conversation, providing short-term continuity and maintaining dialogue flow.
-
-[**Semantic recall**](./semantic-recall) retrieves older messages from past conversations based on semantic relevance. Matches are retrieved using vector search and can include surrounding context for better comprehension.
+Enable memory by passing a `Memory` instance to your agent:
 
-Mastra combines all memory types into a single context window. If the total exceeds the model’s token limit, use [memory processors](./memory-processors) to trim or filter messages before sending them to the model.
-
-## Scoping memory with threads and resources
-
-All memory types are [resource-scoped](./working-memory#resource-scoped-memory-default) by default, meaning they persist across all conversations for the same user or entity. [Thread-scoped](./working-memory#thread-scoped-memory) configuration isolates memory to a single conversation thread.
-
-## Memory Storage Adapters
-
-To persist and recall information between conversations, memory requires a storage adapter.
-
-Supported options include [LibSQL](/docs/v1/memory/storage/memory-with-libsql), [MongoDB](/docs/v1/memory/storage/memory-with-mongodb), [Postgres](/docs/v1/memory/storage/memory-with-pg), and [Upstash](/docs/v1/memory/storage/memory-with-upstash)
-
-We use LibSQL out of the box because it is file-based or in-memory, so it is easy to install and works well with Studio.
-
-## Dedicated storage
-
-Agents can be configured with their own dedicated storage, keeping tasks, conversations, and recalled information separate across agents.
-
-### Adding storage to agents
-
-To assign dedicated storage to an agent, install and import the required dependency and pass a `storage` instance to the `Memory` constructor:
-
-```typescript {3, 9-11} title="src/mastra/agents/test-agent.ts" showLineNumbers copy
+```typescript title="src/mastra/agents/test-agent.ts"
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
-import { LibSQLStore } from "@mastra/libsql";
 
 export const testAgent = new Agent({
   id: "test-agent",
-  // ...
   memory: new Memory({
-    // ...
-    storage: new LibSQLStore({
-      id: 'test-agent-storage',
-      url: "file:agent-memory.db",
-    }),
-    // ...
+    options: {
+      lastMessages: 20,
+    },
   }),
 });
 ```
+When you send a new message, the model can now "see" the previous 20 messages, which gives it better context for the conversation and leads to more coherent, accurate replies.
 
-## Viewing retrieved messages
+This example configures basic [message history](/docs/v1/memory/message-history). You can also enable [working memory](/docs/v1/memory/working-memory) and [semantic recall](/docs/v1/memory/semantic-recall) by passing additional options to `Memory`.
 
-If tracing is enabled in your Mastra deployment and memory is configured either with `lastMessages` and/or `semanticRecall`, the agent’s trace output will show all messages retrieved for context—including both recent conversation history and messages recalled via semantic recall.
+## Storage
 
-This is helpful for debugging, understanding agent decisions, and verifying that the agent is retrieving the right information for each request.
+Before enabling memory, you must first configure a storage adapter. Mastra supports multiple database providers including PostgreSQL, MongoDB, libSQL, and more.
 
-For more details on enabling and configuring tracing, see [Tracing](../observability/tracing/overview).
+Storage can be configured at the instance level (shared across all agents) or at the agent level (dedicated per agent). You can also use different databases for storage and vector operations.
 
-## Local development with LibSQL
+See the [Storage](/docs/v1/memory/storage) documentation for configuration options, supported providers, and examples.
 
-For local development with `LibSQLStore`, you can inspect stored memory using the [SQLite Viewer](https://marketplace.visualstudio.com/items?itemName=qwtel.sqlite-viewer) extension in VS Code.
+## Debugging memory
 
-![SQLite Viewer](/img/memory/memory-sqlite-viewer.jpg)
+When tracing is enabled, you can inspect exactly which messages the agent uses for context in each request. The trace output shows all memory included in the agent's context window - both recent message history and messages recalled via semantic recall.
 
-## Next Steps
+This visibility helps you understand why an agent made specific decisions and verify that memory retrieval is working as expected.
+
+For more details on enabling and configuring tracing, see [Tracing](/docs/v1/observability/tracing/overview).
 
-Now that you understand the core concepts, continue to [semantic recall](./semantic-recall) to learn how to add RAG memory to your Mastra agents.
+## Next Steps
 
-Alternatively you can visit the [configuration reference](/reference/v1/memory/memory-class) for available options.
+- Learn more about [Storage](/docs/v1/memory/storage) providers and configuration options
+- Add [Message History](/docs/v1/memory/message-history), [Working Memory](/docs/v1/memory/working-memory), or [Semantic Recall](/docs/v1/memory/semantic-recall)
+- Visit [Memory configuration reference](/reference/v1/memory/memory-class) for all available options