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

package/.docs/raw/agents/runtime-context.mdx

@@ -0,0 +1,103 @@
+---
+title: "Runtime context | Agents | Mastra Docs"
+description: Learn how to use Mastra's RuntimeContext to provide dynamic, request-specific configuration to agents.
+---
+
+# Agent Runtime Context
+
+Mastra provides `RuntimeContext`, a dependency injection system that lets you configure agents with runtime variables. If you find yourself creating multiple agents that perform similar tasks, runtime context allows you to consolidate them into a single, more flexible agent.
+
+## Overview
+
+The dependency injection system allows you to:
+
+1. Pass runtime configuration variables to agents through a type-safe `runtimeContext`
+2. Access these variables within tool execution contexts
+3. Modify agent behavior without changing the underlying code
+4. Share configuration across multiple tools within the same agent
+
+## Using `runtimeContext` with agents
+
+Agents can access `runtimeContext` via the `instructions` parameter, and retrieve variables using `runtimeContext.get()`. This allows agent behavior to adapt dynamically based on user input or external configuration, without changing the underlying implementation.
+
+```typescript {6-7,14} filename="src/mastra/agents/test-weather-agent.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+
+export const testWeatherAgent = new Agent({
+  name: "test-weather-agent",
+  instructions: async ({ runtimeContext }) => {
+    const temperatureUnit = runtimeContext.get("temperature-unit");
+
+    return `You are a weather assistant that provides current weather information for any city.
+
+    When a user asks for weather:
+    - Extract the city name from their request
+    - Respond with: temperature, feels-like temperature, humidity, wind speed, and conditions
+    - Use ${temperatureUnit} for all temperature values
+    - If no city is mentioned, ask for a city name
+    `;
+  },
+  model: openai("gpt-4o-mini")
+});
+```
+
+### Example usage
+
+In this example, `temperature-unit` is set using `runtimeContext.set()` to either **celsius** or **fahrenheit**, allowing the agent to respond with temperatures in the appropriate unit.
+
+```typescript {12} filename="src/test-weather-agent.ts" showLineNumbers copy
+import { mastra } from "./mastra";
+import { RuntimeContext } from "@mastra/core/runtime-context";
+
+const agent = mastra.getAgent("testWeatherAgent");
+
+export type WeatherRuntimeContext = {
+  "temperature-unit": "celsius" | "fahrenheit";
+};
+
+const runtimeContext = new RuntimeContext<WeatherRuntimeContext>();
+
+runtimeContext.set("temperature-unit", "fahrenheit");
+
+const response = await agent.generate("What's the weather in London?", {
+  runtimeContext
+});
+
+console.log(response.text);
+```
+
+## Accessing `runtimeContext` with server middleware
+
+You can populate `runtimeContext` dynamically in server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.
+
+```typescript {2,12-21} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { RuntimeContext } from "@mastra/core/runtime-context";
+import { testWeatherAgent } from "./agents/test-weather-agent";
+
+type WeatherRuntimeContext = {
+  "temperature-unit": "celsius" | "fahrenheit";
+};
+
+export const mastra = new Mastra({
+  agents: { testWeatherAgent },
+  server: {
+    middleware: [
+      async (context, next) => {
+        const country = context.req.header("CF-IPCountry");
+        const runtimeContext = context.get("runtimeContext") as RuntimeContext<WeatherRuntimeContext>;
+
+        runtimeContext.set("temperature-unit", country === "US" ? "fahrenheit" : "celsius");
+
+        await next();
+      }
+    ]
+  }
+});
+```
+
+## Related
+
+- [Dynamic Agents](./dynamic-agents.mdx)
+- [Tool Runtime Context](../tools-mcp/runtime-context.mdx)

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

@@ -1,11 +1,11 @@
 ---
-title: "MastraJwtAuth"
+title: "MastraJwtAuth Class"
 description: "Documentation for the MastraJwtAuth class, which authenticates Mastra applications using JSON Web Tokens."
 ---
 
 import { Tabs, Tab } from "@/components/tabs";
 
-# 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.
 

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

@@ -0,0 +1,128 @@
+---
+title: "MastraAuthSupabase Class"
+description: "Documentation for the MastraAuthSupabase class, which authenticates Mastra applications using Supabase Auth."
+---
+
+import { Tabs, Tab } from "@/components/tabs";
+
+# 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.
+
+## Prerequisites
+
+This example uses Supabase Auth. Make sure to add your Supabase credentials to your `.env` file and ensure your Supabase project is properly configured.
+
+```env filename=".env" copy
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_ANON_KEY=your-anon-key
+```
+
+> **Note:** Review your Supabase Row Level Security (RLS) settings to ensure proper data access controls.
+
+## Installation
+
+Before you can use the `MastraAuthSupabase` class you have to install the `@mastra/auth-supabase` package.
+
+```bash copy
+npm install @mastra/auth-supabase@latest
+```
+
+## Usage example
+
+```typescript {2,7-9} 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
+    }),
+  },
+});
+```
+
+> **Note:** The default `authorizeUser` method checks the `isAdmin` column in the `users` table in the `public` schema. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
+
+> See the [MastraAuthSupabase](/reference/auth/supabase.mdx) API reference for all available configuration options.
+
+## Client-side setup
+
+When using Supabase auth, you'll need to retrieve the access token from Supabase on the client side and pass it to your Mastra requests.
+
+### Retrieving the access token
+
+Use the Supabase client to authenticate users and retrieve their access token:
+
+```typescript filename="lib/auth.ts" showLineNumbers copy
+import { createClient } from "@supabase/supabase-js";
+
+const supabase = createClient("<supabase-url>", "<supabase-key>");
+
+const authTokenResponse = await supabase.auth.signInWithPassword({
+  email: "<user's email>",
+  password: "<user's password>",
+});
+
+const accessToken = authTokenResponse.data?.session?.access_token;
+```
+
+> Refer to the [Supabase documentation](https://supabase.com/docs/guides/auth) for other authentication methods like OAuth, magic links, and more.
+
+## Configuring `MastraClient`
+
+When `experimental_auth` is enabled, all requests made with `MastraClient` must include a valid Supabase access token in the `Authorization` header:
+
+```typescript {6} filename="lib/mastra/mastra-client.ts" showLineNumbers copy
+import { MastraClient } from "@mastra/client-js";
+
+export const mastraClient = new MastraClient({
+  baseUrl: "https://<mastra-api-url>",
+  headers: {
+    Authorization: `Bearer ${accessToken}`
+  }
+});
+```
+
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
+
+> See [Mastra Client SDK](/docs/server-db/mastra-client.mdx) for more configuration options.
+
+### Making authenticated requests
+
+Once `MastraClient` is configured with the Supabase access token, you can send authenticated requests:
+
+<Tabs items={["MastraClient", "curl"]}>
+  <Tab>
+    ```tsx filename="src/components/test-agent.tsx" showLineNumbers copy
+    import { mastraClient } from "../../lib/mastra-client";
+
+    export const TestAgent = () => {
+      async function handleClick() {
+        const agent = mastraClient.getAgent("weatherAgent");
+
+        const response = await agent.generate({
+          messages: "What's the weather like in New York"
+        });
+
+        console.log(response);
+      }
+
+      return <button onClick={handleClick}>Test Agent</button>;
+    };
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
+      -H "Content-Type: application/json" \
+      -H "Authorization: Bearer <your-supabase-access-token>" \
+      -d '{
+        "messages": "Weather in London"
+      }'
+    ```
+  </Tab>
+</Tabs>

package/.docs/raw/deployment/overview.mdx

@@ -19,19 +19,19 @@ Mastra Cloud is a deployment platform that connects to your GitHub repository, a
 - Comprehensive logs and traces
 - Custom domains for each project
 
-[View Mastra Cloud documentation →](/docs/mastra-cloud/overview)
+[View Mastra Cloud documentation →](../mastra-cloud/overview.mdx)
 
 
 ### With a Web Framework
 
 Mastra can be integrated with a variety of web frameworks. For example, see one of the following for a detailed guide.
 
-- [With Next.js](/docs/frameworks/web-frameworks/next-js)
-- [With Astro](/docs/frameworks/web-frameworks/astro)
+- [With Next.js](../frameworks/web-frameworks/next-js.mdx)
+- [With Astro](../frameworks/web-frameworks/astro.mdx)
 
 When integrated with a framework, Mastra typically requires no additional configuration for deployment.
 
-[View Web Framework Integration →](/docs/deployment/web-framework)
+[View Web Framework Integration →](./web-framework.mdx)
 
 ### With a Server
 
@@ -42,7 +42,7 @@ You can deploy Mastra as a standard Node.js HTTP server, which gives you full co
 - Deploy to VMs, containers, or PaaS platforms
 - Ideal for integrating with existing Node.js applications
 
-[Server deployment guide →](/docs/deployment/server)
+[Server deployment guide →](./server-deployment.mdx)
 
 ### Serverless Platforms
 
@@ -53,7 +53,7 @@ Mastra provides platform-specific deployers for popular serverless platforms, en
 - Simplified deployment process
 - Automatic scaling through the platform
 
-[Serverless deployment guide →](/docs/deployment/deployment)
+[Serverless deployment guide →](./server-deployment.mdx)
 
 ## Client Configuration
 
@@ -64,7 +64,7 @@ Once your Mastra application is deployed, you'll need to configure your client t
 - Retries and error handling
 - Support for streaming responses
 
-[Client configuration guide →](/docs/deployment/client)
+[Client configuration guide →](../server-db/mastra-client.mdx)
 
 ## Choosing a Deployment Option
 

package/.docs/raw/frameworks/agentic-uis/ai-sdk.mdx

@@ -287,7 +287,7 @@ export const mastra = new Mastra({
 });
 ```
 
-> You can then access this data in your tools via the `runtimeContext` parameter. See the [Runtime Context documentation](/docs/agents/runtime-variables) for more details.
+> You can then access this data in your tools via the `runtimeContext` parameter. See the [Agent Runtime Context documentation](/docs/agents/runtime-context) for more details.
 
 ## Streaming data
 

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/agents/getDefaultGenerateOptions.mdx

@@ -64,4 +64,4 @@ await agent.getDefaultGenerateOptions({
 ## Related
 
 - [Agent generation](../../docs/agents/overview.mdx#generate)
-- [Runtime variables](../../docs/agents/runtime-variables.mdx)
+- [Agent Runtime Context](../../docs/agents/runtime-context.mdx)

package/.docs/raw/reference/agents/getDefaultStreamOptions.mdx

@@ -65,4 +65,4 @@ await agent.getDefaultStreamOptions({
 
 - [Generating responses](../../docs/agents/overview.mdx#generating-responses)
 - [Streaming responses](../../docs/agents/overview.mdx#streaming-responses)
-- [Runtime variables](../../docs/agents/runtime-variables.mdx)
+- [Agent Runtime Context](../../docs/agents/runtime-context.mdx)

package/.docs/raw/reference/agents/getDefaultVNextStreamOptions.mdx

@@ -64,4 +64,4 @@ await agent.getDefaultVNextStreamOptions({
 ## Related
 
 - [Streaming with agents](../../docs/streaming/overview.mdx#streaming-with-agents)
-- [Runtime variables](../../docs/agents/runtime-variables.mdx)
+- [Agent Runtime Context](../../docs/agents/runtime-context.mdx)

package/.docs/raw/reference/agents/getInstructions.mdx

@@ -64,4 +64,4 @@ await agent.getInstructions({
 ## Related
 
 - [Agents overview](../../docs/agents/overview.mdx)
-- [Runtime variables](../../docs/agents/runtime-variables.mdx)
+- [Agent Runtime Context](../../docs/agents/runtime-context.mdx)

package/.docs/raw/reference/agents/getLLM.mdx

@@ -71,4 +71,4 @@ await agent.getLLM({
 ## Related
 
 - [Agents overview](../../docs/agents/overview.mdx)
-- [Runtime variables](../../docs/agents/runtime-variables.mdx)
+- [Agent Runtime Context](../../docs/agents/runtime-context.mdx)

package/.docs/raw/reference/agents/getMemory.mdx

@@ -64,4 +64,4 @@ await agent.getMemory({
 ## Related
 
 - [Agent memory](../../docs/agents/agent-memory.mdx)
-- [Runtime variables](../../docs/agents/runtime-variables.mdx)
+- [Agent Runtime Context](../../docs/agents/runtime-context.mdx)

package/.docs/raw/reference/agents/getModel.mdx

@@ -64,4 +64,4 @@ await agent.getModel({
 ## Related
 
 - [Agents overview](../../docs/agents/overview.mdx)
-- [Runtime variables](../../docs/agents/runtime-variables.mdx)
+- [Agent Runtime Context](../../docs/agents/runtime-context.mdx)

package/.docs/raw/reference/agents/getScorers.mdx

@@ -64,4 +64,4 @@ await agent.getScorers({
 ## Related
 
 - [Agents overview](../../docs/agents/overview.mdx)
-- [Runtime variables](../../docs/agents/runtime-variables.mdx)
+- [Agent Runtime Context](../../docs/agents/runtime-context.mdx)