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

package/.docs/raw/getting-started/mcp-docs-server.mdx

@@ -1,24 +1,22 @@
 ---
-title: "Using with Cursor/Windsurf | Getting Started | Mastra Docs"
+title: "MCP Docs Server | Getting Started | Mastra Docs"
 description: "Learn how to use the Mastra MCP documentation server in your IDE to turn it into an agentic Mastra expert."
 ---
 
 import YouTube from "@/components/youtube";
 import { Tabs } from "nextra/components";
 
-# Mastra Tools for your agentic IDE
+# Mastra Docs Server
 
-`@mastra/mcp-docs-server` provides direct access to Mastra's complete knowledge base in Cursor, Windsurf, Cline, or any other IDE that supports MCP.
-
-It has access to documentation, code examples, technical blog posts / feature announcements, and package changelogs which your IDE can read to help you build with Mastra.
+The `@mastra/mcp-docs-server` package provides direct access to Mastra’s full knowledge base, including documentation, code examples, blog posts, and changelogs, via the MCP protocol. It works with Cursor, Windsurf, Cline, Claude Code, or any tool that supports MCP.
 
 <YouTube id="vciV57lF0og" />
 
-The MCP server tools have been designed to allow an agent to query the specific information it needs to complete a Mastra related task - for example: adding a Mastra feature to an agent, scaffolding a new project, or helping you understand how something works.
+These tools are designed to help agents retrieve precise, task-specific information—whether you're adding a feature to an agent, scaffolding a new project, or exploring how something works.
 
 ## How it works
 
-Once it's installed in your IDE you can write prompts and assume the agent will understand everything about Mastra.
+Once installed you can write prompts and assume the agent will understand everything about Mastra.
 
 ### Add features
 
@@ -41,18 +39,18 @@ Once it's installed in your IDE you can write prompts and assume the agent will
 
 **And more** - if you have a question, try asking your IDE and let it look it up for you.
 
-## Automatic Installation
+## Automatic installation
 
 For **new** projects, the MCP Docs Server can be added during installation either through the [interactive](/docs/getting-started/installation#interactive) setup prompts, or by specifying the `-m` flag using the [non-interactive](/docs/getting-started/installation#non-interactive) command.
 
-## Manual Installation
+## Manual installation
 
 To add the MCP Docs Server to an existing project, install it manually.
 
 - **Cursor**: Edit `.cursor/mcp.json` in your project root, or `~/.cursor/mcp.json` for global configuration
 - **Windsurf**: Edit `~/.codeium/windsurf/mcp_config.json` (only supports global configuration)
-- **VSCode**: Either move the created `.vscode` folder into the top-level of your workspace or open the created folder as your new workspace root. Edit `~/.vscode/mcp.json` in your project root.
-  Add the following configuration:
+- **VSCode**: Either move the created `.vscode` folder into the top-level of your workspace or open the created folder as your new workspace root. Edit `~/.vscode/mcp.json` in your project root. Add the following configuration:
+- **Claude Code**: Run the `claude mcp add` command as shown below.
 
 ### MacOS/Linux
 
@@ -63,7 +61,7 @@ The tabs help users find the correct configuration format for their IDE (Cursor,
 Each tab shows the exact JSON structure and file paths needed for that IDE's MCP configuration.
 */}
 
-<Tabs items={["Cursor", "Windsurf", "VSCode"]}>
+<Tabs items={["Cursor", "Windsurf", "VSCode", "Claude Code"]}>
   <Tabs.Tab>
 ```json
 {
@@ -99,6 +97,11 @@ Each tab shows the exact JSON structure and file paths needed for that IDE's MCP
     }
   }
 }
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash
+claude mcp add mastra -- npx -y @mastra/mcp-docs-server
 ```
   </Tabs.Tab>
 </Tabs>
@@ -113,7 +116,7 @@ Each tab shows the Windows-specific command structure needed for that IDE's MCP
 On latest Windsurf and Cursor the direct npx command works, while it's still unconfirmed if this has been fixed for VSCode.
 */}
 
-<Tabs items={["Cursor", "Windsurf", "VSCode"]}>
+<Tabs items={["Cursor", "Windsurf", "VSCode", "Claude Code"]}>
   <Tabs.Tab>
 ```json
 {
@@ -149,11 +152,16 @@ On latest Windsurf and Cursor the direct npx command works, while it's still unc
     }
   }
 }
+```
+  </Tabs.Tab>
+  <Tabs.Tab>
+```bash
+claude mcp add mastra -- npx -y @mastra/mcp-docs-server
 ```
   </Tabs.Tab>
 </Tabs>
 
-## After Configuration
+## After configuration
 
 ### Cursor
 
@@ -167,25 +175,23 @@ If you followed the automatic installation, you'll see a popup when you open cur
 
 Otherwise, for manual installation, do the following.
 
-1. Open Cursor settings
-2. Navigate to MCP settings
-3. Click "enable" on the Mastra MCP server
-4. If you have an agent chat open, you'll need to re-open it or start a new chat to use the MCP server
+1. Open Cursor settings.
+2. Navigate to MCP settings.
+3. Click "enable" on the Mastra MCP server.
+4. If you have an agent chat open, you'll need to re-open it or start a new chat to use the MCP server.
 
 ### Windsurf
 
-1. Fully quit and re-open Windsurf
+1. Fully quit and re-open Windsurf.
 2. If tool calls start failing, go to Windsurfs MCP settings and re-start the MCP server. This is a common Windsurf MCP issue and isn't related to Mastra. Right now Cursor's MCP implementation is more stable than Windsurfs is.
 
 In both IDEs it may take a minute for the MCP server to start the first time as it needs to download the package from npm.
 
 ### VSCode
 
-1. Open VSCode settings
-2. Navigate to MCP settings
-3. Click "enable" on the Chat > MCP option
-
-<br />
+1. Open VSCode settings.
+2. Navigate to MCP settings.
+3. Click "enable" on the Chat > MCP option.
 
 <img
   src="/image/vscode-mcp-setting.png"
@@ -196,7 +202,6 @@ In both IDEs it may take a minute for the MCP server to start the first time as
 
 MCP only works in Agent mode in VSCode. Once you are in agent mode, open the `mcp.json` file and click the "start" button. Note that the "start" button will only appear if the `.vscode` folder containing `mcp.json` is in your workspace root, or the highest level of the in-editor file explorer.
 
-<br />
 <img
   src="/image/vscode-start-mcp.png"
   alt="Settings page of VSCode to enable MCP"
@@ -206,7 +211,6 @@ MCP only works in Agent mode in VSCode. Once you are in agent mode, open the `mc
 
 After starting the mcp server, click the tools button in the copilot pane to see available tools.
 
-<br />
 <img
   src="/image/vscode-mcp-running.png"
   alt="Tools page of VSCode to see available tools"
@@ -214,49 +218,49 @@ After starting the mcp server, click the tools button in the copilot pane to see
   className="rounded-lg"
 />
 
-## Available Agent Tools
+## Available agent tools
 
 ### Documentation
 
 Access Mastra's complete documentation:
 
-- Getting started / installation
-- Guides and tutorials
-- API references
+- Getting started / installation.
+- Guides and tutorials.
+- API references.
 
 ### Examples
 
 Browse code examples:
 
-- Complete project structures
-- Implementation patterns
-- Best practices
+- Complete project structures.
+- Implementation patterns.
+- Best practices.
 
-### Blog Posts
+### Blog posts
 
 Search the blog for:
 
-- Technical posts
-- Changelog and feature announcements
-- AI news and updates
+- Technical posts.
+- Changelog and feature announcements.
+- AI news and updates.
 
-### Package Changes
+### Package changes
 
 Track updates for Mastra and `@mastra/*` packages:
 
-- Bug fixes
-- New features
-- Breaking changes
+- Bug fixes.
+- New features.
+- Breaking changes.
 
-## Common Issues
+## Common issues
 
 1. **Server Not Starting**
 
-   - Ensure [npx](https://docs.npmjs.com/cli/v11/commands/npx) is installed and working
-   - Check for conflicting MCP servers
-   - Verify your configuration file syntax
-   - On Windows, make sure to use the Windows-specific configuration
+   - Ensure [npx](https://docs.npmjs.com/cli/v11/commands/npx) is installed and working.
+   - Check for conflicting MCP servers.
+   - Verify your configuration file syntax.
+   - On Windows, make sure to use the Windows-specific configuration.
 
 2. **Tool Calls Failing**
-   - Restart the MCP server and/or your IDE
-   - Update to the latest version of your IDE
+   - Restart the MCP server and/or your IDE.
+   - Update to the latest version of your IDE.

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

@@ -133,7 +133,7 @@ const memory = new Memory({
 });
 ```
 
-**Important:** Only send the newest user message in each agent call. Mastra handles retrieving and injecting the necessary history. Sending the full history yourself will cause duplication. See the [AI SDK Memory Example](../../examples/memory/use-chat.mdx) for how to handle this with when using the `useChat` frontend hooks.
+**Important:** Only send the newest user message in each agent call. Mastra handles retrieving and injecting the necessary history. Sending the full history yourself will cause duplication. See the [AI SDK Memory Example](../../docs/frameworks/agentic-uis/ai-sdk.mdx) for how to handle this with when using the `useChat` frontend hooks.
 
 ### Storage Configuration
 
@@ -176,4 +176,4 @@ For more details on enabling and configuring tracing, see [Tracing](../observabi
 
 Now that you understand the core concepts, continue to [semantic recall](./semantic-recall.mdx) to learn how to add RAG memory to your Mastra agents.
 
-Alternatively you can visit the [configuration reference](../../reference/memory/Memory.mdx) for available options, or browse [usage examples](../../examples/memory/use-chat.mdx).
+Alternatively you can visit the [configuration reference](../../reference/memory/Memory.mdx) for available options.

package/.docs/raw/reference/auth/jwt.mdx

@@ -1,9 +1,9 @@
 ---
-title: "MastraJwtAuth"
+title: "MastraJwtAuth Class"
 description: "API reference for the MastraJwtAuth class, which authenticates Mastra applications using JSON Web Tokens."
 ---
 
-# MastraJwtAuth
+# MastraJwtAuth Class
 
 The `MastraJwtAuth` class provides a lightweight authentication mechanism for Mastra using JSON Web Tokens (JWTs). It verifies incoming requests based on a shared secret and integrates with the Mastra server using the `experimental_auth` option.
 
@@ -36,7 +36,6 @@ export const mastra = new Mastra({
   ]}
 />
 
-
 ## Related
 
 [MastraJwtAuth](/docs/auth/jwt.mdx)

package/.docs/raw/reference/auth/supabase.mdx

@@ -0,0 +1,62 @@
+---
+title: "MastraAuthSupabase Class"
+description: "API reference for the MastraAuthSupabase class, which authenticates Mastra applications using Supabase Auth."
+---
+
+# MastraAuthSupabase Class
+
+The `MastraAuthSupabase` class provides authentication for Mastra using Supabase Auth. It verifies incoming requests using Supabase's authentication system and integrates with the Mastra server using the `experimental_auth` option.
+
+## Usage example
+
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthSupabase } from '@mastra/auth-supabase';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraAuthSupabase({
+      url: process.env.SUPABASE_URL,
+      anonKey: process.env.SUPABASE_ANON_KEY
+    }),
+  },
+});
+```
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "url",
+      type: "string",
+      description: "The URL of your Supabase project. Can be found in your Supabase project settings.",
+      isOptional: true,
+      defaultValue: "process.env.SUPABASE_URL"
+    },
+    {
+      name: "anonKey",
+      type: "string",
+      description: "The anonymous/public key for your Supabase project. Used for client-side authentication.",
+      isOptional: true,
+      defaultValue: "process.env.SUPABASE_ANON_KEY"
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Custom name for the auth provider instance.",
+      isOptional: true,
+    },
+    {
+      name: "authorizeUser",
+      type: "(user: User, request: HoneRequest) => Promise<boolean> | boolean",
+      description: "Custom authorization function to determine if a user should be granted access. Called after token verification. By default, checks the 'isAdmin' column in the 'users' table.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Related
+
+[MastraAuthSupabase](/docs/auth/supabase.mdx)

package/.docs/raw/reference/{agents → core}/getAgent.mdx

@@ -3,7 +3,7 @@ title: "Reference: Agent.getAgent() | Agents | Mastra Docs"
 description: "Documentation for the `Agent.getAgent()` method in Mastra, which retrieves an agent by name."
 ---
 
-# Agent.getAgent()
+# Mastra.getAgent()
 
 The `.getAgent()` method is used to retrieve an agent. The method accepts a single `string` parameter for the agent's name.
 
@@ -13,7 +13,6 @@ The `.getAgent()` method is used to retrieve an agent. The method accepts a sing
 mastra.getAgent("testAgent");
 ```
 
-
 ## Parameters
 
 <PropertiesTable

package/.docs/raw/reference/core/getAgentById.mdx

@@ -0,0 +1,43 @@
+---
+title: "Reference: Mastra.getAgentById() | Core | Mastra Docs"
+description: "Documentation for the `Mastra.getAgentById()` method in Mastra, which retrieves an agent by its ID."
+---
+
+# Mastra.getAgentById()
+
+The `.getAgentById()` method is used to retrieve an agent by its ID. The method accepts a single `string` parameter for the agent's ID.
+
+## Usage example
+
+```typescript copy
+mastra.getAgentById("test-agent-123");
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "The ID of the agent to retrieve. The method will first search for an agent with this ID, and if not found, will attempt to use it as a name to call getAgent().",
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "agent",
+      type: "Agent",
+      description: "The agent instance with the specified ID. Throws an error if the agent is not found.",
+    },
+  ]}
+/>
+
+## Related
+
+- [Agents overview](../../docs/agents/overview.mdx)
+- [Dynamic agents](../../docs/agents/dynamic-agents.mdx)

package/.docs/raw/reference/core/getAgents.mdx

@@ -0,0 +1,35 @@
+---
+title: "Reference: Mastra.getAgents() | Core | Mastra Docs"
+description: "Documentation for the `Mastra.getAgents()` method in Mastra, which retrieves all configured agents."
+---
+
+# Mastra.getAgents()
+
+The `.getAgents()` method is used to retrieve all agents that have been configured in the Mastra instance.
+
+## Usage example
+
+```typescript copy
+mastra.getAgents();
+```
+
+## Parameters
+
+This method does not accept any parameters.
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "agents",
+      type: "TAgents",
+      description: "A record of all configured agents, where keys are agent names and values are agent instances.",
+    },
+  ]}
+/>
+
+## Related
+
+- [Agents overview](../../docs/agents/overview.mdx)
+- [Dynamic agents](../../docs/agents/dynamic-agents.mdx)

package/.docs/raw/reference/core/getDeployer.mdx

@@ -0,0 +1,35 @@
+---
+title: "Reference: Mastra.getDeployer() | Core | Mastra Docs"
+description: "Documentation for the `Mastra.getDeployer()` method in Mastra, which retrieves the configured deployer instance."
+---
+
+# Mastra.getDeployer()
+
+The `.getDeployer()` method is used to retrieve the deployer instance that has been configured in the Mastra instance.
+
+## Usage example
+
+```typescript copy
+mastra.getDeployer();
+```
+
+## Parameters
+
+This method does not accept any parameters.
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "deployer",
+      type: "MastraDeployer | undefined",
+      description: "The configured deployer instance, or undefined if no deployer has been configured.",
+    },
+  ]}
+/>
+
+## Related
+
+- [Deployment overview](../../docs/deployment/overview.mdx)
+- [Deployer reference](../../reference/deployer/deployer.mdx)

package/.docs/raw/reference/core/getLogger.mdx

@@ -0,0 +1,35 @@
+---
+title: "Reference: Mastra.getLogger() | Core | Mastra Docs"
+description: "Documentation for the `Mastra.getLogger()` method in Mastra, which retrieves the configured logger instance."
+---
+
+# Mastra.getLogger()
+
+The `.getLogger()` method is used to retrieve the logger instance that has been configured in the Mastra instance.
+
+## Usage example
+
+```typescript copy
+mastra.getLogger();
+```
+
+## Parameters
+
+This method does not accept any parameters.
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "logger",
+      type: "TLogger",
+      description: "The configured logger instance used for logging across all components (agents, workflows, etc.).",
+    },
+  ]}
+/>
+
+## Related
+
+- [Logging overview](../../docs/observability/logging.mdx)
+- [Logger reference](../../reference/observability/logger.mdx)

package/.docs/raw/reference/core/getLogs.mdx

@@ -0,0 +1,92 @@
+---
+title: "Reference: Mastra.getLogs() | Core | Mastra Docs"
+description: "Documentation for the `Mastra.getLogs()` method in Mastra, which retrieves all logs for a specific transport ID."
+---
+
+# Mastra.getLogs()
+
+The `.getLogs()` method is used to retrieve all logs for a specific transport ID. This method requires a configured logger that supports the `getLogs` operation.
+
+## Usage example
+
+```typescript copy
+mastra.getLogs("456");
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "transportId",
+      type: "string",
+      description: "The transport ID to retrieve logs from.",
+    },
+    {
+      name: "options",
+      type: "object",
+      description: "Optional parameters for filtering and pagination. See Options section below for details.",
+      optional: true,
+    },
+  ]}
+/>
+
+### Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "fromDate",
+      type: "Date",
+      description: "Optional start date for filtering logs. e.g., new Date('2024-01-01').",
+      optional: true,
+    },
+    {
+      name: "toDate",
+      type: "Date",
+      description: "Optional end date for filtering logs. e.g., new Date('2024-01-31').",
+      optional: true,
+    },
+    {
+      name: "logLevel",
+      type: "LogLevel",
+      description: "Optional log level to filter by.",
+      optional: true,
+    },
+    {
+      name: "filters",
+      type: "Record<string, any>",
+      description: "Optional additional filters to apply to the log query.",
+      optional: true,
+    },
+    {
+      name: "page",
+      type: "number",
+      description: "Optional page number for pagination.",
+      optional: true,
+    },
+    {
+      name: "perPage",
+      type: "number",
+      description: "Optional number of logs per page for pagination.",
+      optional: true,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "logs",
+      type: "Promise<any>",
+      description: "A promise that resolves to the logs for the specified transport ID.",
+    },
+  ]}
+/>
+
+## Related
+
+- [Logging overview](../../docs/observability/logging.mdx)
+- [Logger reference](../../reference/observability/logger.mdx)

package/.docs/raw/reference/core/getLogsByRunId.mdx

@@ -0,0 +1,84 @@
+---
+title: "Reference: Mastra.getLogsByRunId() | Core | Mastra Docs"
+description: "Documentation for the `Mastra.getLogsByRunId()` method in Mastra, which retrieves logs for a specific run ID and transport ID."
+---
+
+# Mastra.getLogsByRunId()
+
+The `.getLogsByRunId()` method is used to retrieve logs for a specific run ID and transport ID. This method requires a configured logger that supports the `getLogsByRunId` operation.
+
+## Usage example
+
+```typescript copy
+mastra.getLogsByRunId({ runId: "123", transportId: "456" });
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "runId",
+      type: "string",
+      description: "The run ID to retrieve logs for.",
+    },
+    {
+      name: "transportId",
+      type: "string",
+      description: "The transport ID to retrieve logs from.",
+    },
+    {
+      name: "fromDate",
+      type: "Date",
+      description: "Optional start date for filtering logs. e.g., new Date('2024-01-01').",
+      optional: true,
+    },
+    {
+      name: "toDate",
+      type: "Date",
+      description: "Optional end date for filtering logs. e.g., new Date('2024-01-31').",
+      optional: true,
+    },
+    {
+      name: "logLevel",
+      type: "LogLevel",
+      description: "Optional log level to filter by.",
+      optional: true,
+    },
+    {
+      name: "filters",
+      type: "Record<string, any>",
+      description: "Optional additional filters to apply to the log query.",
+      optional: true,
+    },
+    {
+      name: "page",
+      type: "number",
+      description: "Optional page number for pagination.",
+      optional: true,
+    },
+    {
+      name: "perPage",
+      type: "number",
+      description: "Optional number of logs per page for pagination.",
+      optional: true,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "logs",
+      type: "Promise<any>",
+      description: "A promise that resolves to the logs for the specified run ID and transport ID.",
+    },
+  ]}
+/>
+
+## Related
+
+- [Logging overview](../../docs/observability/logging.mdx)
+- [Logger reference](../../reference/observability/logger.mdx)