@mastra/mcp-docs-server 0.13.5 → 0.13.7-alpha.0

package/.docs/raw/agents/agent-memory.mdx

@@ -37,6 +37,132 @@ const agent = new Agent({
 
 This basic setup uses the default settings. Visit the [Memory documentation](/docs/memory/overview) for more configuration info.
 
+## Dynamic Memory Configuration
+
+Similar to how you can configure dynamic [instructions, models, and tools](./dynamic-agents.mdx), you can also configure memory dynamically using runtime context. This allows you to:
+
+- Use different memory systems based on user tiers or preferences
+- Switch between memory configurations for different environments
+- Enable or disable memory features based on feature flags
+- Customize memory behavior based on user context
+
+### Example: User Tier-Based Memory
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+import { LibSQLStore } from "@mastra/libsql";
+import { PostgresStore } from "@mastra/pg";
+import { openai } from "@ai-sdk/openai";
+
+// Create different memory instances for different user tiers
+const premiumMemory = new Memory({
+  storage: new LibSQLStore({ url: "file:premium.db" }),
+  options: {
+    semanticRecall: { topK: 10, messageRange: 5 }, // More context for premium users
+    workingMemory: { enabled: true },
+  },
+});
+
+const standardMemory = new Memory({
+  storage: new LibSQLStore({ url: "file:standard.db" }),
+  options: {
+    semanticRecall: { topK: 3, messageRange: 2 }, // Basic recall for standard users
+    workingMemory: { enabled: false },
+  },
+});
+
+const agent = new Agent({
+  name: "TieredMemoryAgent",
+  instructions: "You are a helpful assistant with tiered memory capabilities.",
+  model: openai("gpt-4o"),
+  memory: ({ runtimeContext }) => {
+    const userTier = runtimeContext.get("userTier");
+    return userTier === "premium" ? premiumMemory : standardMemory;
+  },
+});
+```
+
+### Example: Environment-Based Memory
+
+```typescript
+const agent = new Agent({
+  name: "EnvironmentAwareAgent",
+  instructions: "You are a helpful assistant.",
+  model: openai("gpt-4o"),
+  memory: ({ runtimeContext }) => {
+    const environment = runtimeContext.get("environment");
+    
+    if (environment === "test") {
+      // Use local storage for testing
+      return new Memory({
+        storage: new LibSQLStore({ url: ":memory:" }),
+        options: {
+          workingMemory: { enabled: true },
+        },
+      });
+    } else if (environment === "production") {
+      // Use production database
+      return new Memory({
+        storage: new PostgresStore({ connectionString: process.env.PRODUCTION_DB_URL }),
+        options: {
+          workingMemory: { enabled: true },
+        },
+      });
+    }
+    
+    // Development environment
+    return new Memory({
+      storage: new LibSQLStore({ url: "file:dev.db" }),
+    });
+  },
+});
+```
+
+### Example: Async Memory Configuration
+
+```typescript
+const agent = new Agent({
+  name: "AsyncMemoryAgent",
+  instructions: "You are a helpful assistant.",
+  model: openai("gpt-4o"),
+  memory: async ({ runtimeContext }) => {
+    const userId = runtimeContext.get("userId");
+    
+    // Simulate async memory setup (e.g., database lookup)
+    await new Promise(resolve => setTimeout(resolve, 10));
+    
+    return new Memory({
+      storage: new LibSQLStore({ 
+        url: `file:user_${userId}.db` 
+      }),
+    });
+  },
+});
+```
+
+### Using Dynamic Memory
+
+When using dynamic memory, pass the runtime context to your agent calls:
+
+```typescript
+import { RuntimeContext } from "@mastra/core/runtime-context";
+
+// Create runtime context with user information
+const runtimeContext = new RuntimeContext();
+runtimeContext.set("userTier", "premium");
+runtimeContext.set("environment", "production");
+
+// Use the agent with runtime context
+const response = await agent.generate("Remember my favorite color is blue.", {
+  memory: {
+    resource: "user_alice",
+    thread: { id: "preferences_thread" },
+  },
+  runtimeContext, // Pass the runtime context
+});
+```
+
 ## Using Memory in Agent Calls
 
 To utilize memory during interactions, you **must** provide `resourceId` and `threadId` when calling the agent's `stream()` or `generate()` methods.

package/.docs/raw/agents/dynamic-agents.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Dynamic Agents"
-description: Dynamically configure your agent's instruction, model and tools using runtime context.
+description: Dynamically configure your agent's instruction, model, tools, and memory using runtime context.
 ---
 
 # Dynamic Agents
 
 Dynamic agents use [runtime context](./runtime-variables), like user IDs and other important parameters, to adjust their settings in real-time.
 
-This means they can change the model they use, update their instructions, and select different tools as needed.
+This means they can change the model they use, update their instructions, select different tools, and configure memory as needed.
 
 By using this context, agents can better respond to each user's needs. They can also call any API to gather more information, which helps improve what the agents can do.
 
@@ -55,6 +55,37 @@ const supportAgent = new Agent({
 
     return baseTools;
   },
+
+  memory: ({ runtimeContext }) => {
+    const userTier = runtimeContext.get("user-tier");
+    
+    if (userTier === "enterprise") {
+      return new Memory({
+        storage: new LibSQLStore({ url: "file:enterprise.db" }),
+        options: {
+          semanticRecall: { topK: 15, messageRange: 8 },
+          workingMemory: { enabled: true },
+        },
+      });
+    } else if (userTier === "pro") {
+      return new Memory({
+        storage: new LibSQLStore({ url: "file:pro.db" }),
+        options: {
+          semanticRecall: { topK: 8, messageRange: 4 },
+          workingMemory: { enabled: true },
+        },
+      });
+    }
+    
+    // Basic memory for free tier
+    return new Memory({
+      storage: new LibSQLStore({ url: "file:free.db" }),
+      options: {
+        semanticRecall: { topK: 3, messageRange: 2 },
+        workingMemory: { enabled: false },
+      },
+    });
+  },
 });
 ```
 
@@ -63,6 +94,7 @@ In this example, the agent:
 - Adjusts its instructions based on the user's subscription tier (free, pro, or enterprise)
 - Uses a more powerful model (GPT-4) for enterprise users
 - Provides different sets of tools based on the user's tier
+- Configures memory with different capabilities based on the user's tier
 - Responds in the user's preferred language
 
 This demonstrates how a single agent can handle different types of users and scenarios by leveraging runtime context, making it more flexible and maintainable than creating separate agents for each use case.

package/.docs/raw/agents/overview.mdx

@@ -9,6 +9,8 @@ description: Overview of agents in Mastra, detailing their capabilities and how
 
 Agents can run autonomously in a loop, run once, or take turns with a user. You can give short-term, long-term, and working memory of their user interactions. They can stream text or return structured output (ie, JSON). They can access third-party APIs, query knowledge bases, and so on.
 
+Additionally, agents support dynamic configuration, allowing you to change their instructions, model, tools, and memory based on runtime context like user preferences, subscription tiers, or environment settings.
+
 ## 1. Creating an Agent
 
 To create an agent in Mastra, you use the `Agent` class and define its properties:
@@ -36,6 +38,8 @@ Also, make sure you have the `@mastra/core` package installed:
 npm install @mastra/core@latest
 ```
 
+All agent properties (instructions, model, tools, memory) can be configured dynamically using runtime context. See the [Dynamic Agents guide](./dynamic-agents.mdx) for examples of how to adapt agent behavior based on user context, subscription tiers, or other runtime variables.
+
 ### Registering the Agent
 
 Register your agent with Mastra to enable logging and access to configured tools and integrations:
@@ -282,5 +286,6 @@ For more details, see the [Local Dev Playground](/docs/server-db/local-dev-playg
 ## Next Steps
 
 - Learn about Agent Memory in the [Agent Memory](./agent-memory.mdx) guide.
+- Learn about Dynamic Agent configuration in the [Dynamic Agents](./dynamic-agents.mdx) guide.
 - Learn about Agent Tools in the [Agent Tools and MCP](./using-tools-and-mcp.mdx) guide.
 - See an example agent in the [Chef Michel](../../guides/guide/chef-michel.mdx) example.

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

@@ -23,7 +23,7 @@ const agent = mastra.getAgent("weatherAgent");
 
 // Define your runtimeContext's type structure
 type WeatherRuntimeContext = {
-  "temperature-scale": "celsius" | "fahrenheit"; // Fixed typo in "fahrenheit"
+  "temperature-scale": "celsius" | "fahrenheit";
 };
 
 const runtimeContext = new RuntimeContext<WeatherRuntimeContext>();

package/.docs/raw/auth/index.mdx

@@ -0,0 +1,24 @@
+---
+title: Auth Overview
+description: Learn about different Auth options for your Mastra applications
+---
+
+# Auth Overview
+
+Mastra lets you choose how you handle authentication, so you can secure access to your application's endpoints using the identity system that fits your stack.
+
+You can start with simple shared secret JWT authentication and switch to providers like Supabase, Firebase Auth, Auth0, Clerk, or WorkOS when you need more advanced identity features.
+
+## Available providers
+
+- [JSON Web Token (JWT)](/docs/auth/jwt)
+
+### Coming soon
+
+The following providers will be available soon:
+
+- Supabase Auth
+- Firebase Auth
+- Auth0
+- Clerk
+- WorkOS

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

@@ -0,0 +1,99 @@
+---
+title: "MastraJwtAuth"
+description: "Documentation for the MastraJwtAuth class, which authenticates Mastra applications using JSON Web Tokens."
+---
+
+import { Tabs, Tab } from "@/components/tabs";
+
+# MastraJwtAuth
+
+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.
+
+## Installation
+
+```bash copy
+npm install @mastra/auth
+```
+
+## Usage example
+
+```typescript {2,7-9} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraJwtAuth } from '@mastra/auth';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraJwtAuth({
+        secret: process.env.MASTRA_JWT_SECRET
+    }),
+  },
+});
+```
+
+> See the [MastraJwtAuth](/reference/auth/jwt.mdx) API reference for all available configuration options.
+
+## Configuring `MastraClient`
+
+When `experimental_auth` is enabled, all requests made with `MastraClient` must include a valid JWT 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 ${process.env.MASTRA_JWT_TOKEN}`
+  }
+});
+```
+
+> See [Mastra Client SDK](/docs/server-db/mastra-client.mdx) for more configuration options.
+
+### Making authenticated requests
+
+Once `MastraClient` is configured, you can send authenticated requests from your frontend application, or use `curl` for quick local testing:
+
+<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: "Weather in London"
+        });
+
+        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-jwt>" \
+      -d '{
+        "messages": "Weather in London"
+      }'
+    ```
+  </Tab>
+</Tabs>
+
+## Creating a JWT
+
+To authenticate requests to your Mastra server, you'll need a valid JSON Web Token (JWT) signed with your `MASTRA_JWT_SECRET`.
+
+The easiest way to generate one is using [jwt.io](https://www.jwt.io/):
+
+1. Select **JWT Encoder**.
+2. Scroll down to the **Sign JWT: Secret** section.
+3. Enter your secret (for example: `supersecretdevkeythatishs256safe!`).
+4. Click **Generate example** to create a valid JWT.
+5. Copy the generated token and set it as `MASTRA_JWT_TOKEN` in your `.env` file.

package/.docs/raw/deployment/cloud-providers/amazon-ec2.mdx

@@ -3,8 +3,7 @@ title: "Amazon EC2"
 description: "Deploy your Mastra applications to Amazon EC2."
 ---
 
-import { Callout, Steps } from "nextra/components";
-import ServerConfig from "@/components/content-blocks/server-config.mdx";
+import { Callout, Steps, Tabs } from "nextra/components";
 
 ## Amazon EC2
 
@@ -17,50 +16,85 @@ Deploy your Mastra applications to Amazon EC2 (Elastic Cloud Compute).
   refer to our [getting started guide](/docs/getting-started/installation)
 </Callout>
 
-### Setting up EC2
+### Prerequisites
+
+- An AWS account with [EC2](https://aws.amazon.com/ec2/) access
+- An EC2 instance running Ubuntu 24+ or Amazon Linux
+- A domain name with an A record pointing to your instance
+- A reverse proxy configured (e.g., using [nginx](https://nginx.org/))
+- SSL certificate configured (e.g., using [Let's Encrypt](https://letsencrypt.org/))
+- Node.js 18+ installed on your instance
+
+### Deployment Steps
 
 <Steps>
 
-#### Log into your AWS console
+#### Clone your Mastra application
 
-Navigate to the [AWS Management Console](https://aws.amazon.com/console/) and sign in to your account.
+Connect to your EC2 instance and clone your repository:
 
-#### Navigate to EC2
+<Tabs items={["Public Repository", "Private Repository"]}>
+<Tabs.Tab>
 
-Head over to **All services** in the left side navigation. Under **Compute**, click on **EC2**.
+```bash copy
+git clone https://github.com/<your-username>/<your-repository>.git
+```
 
-#### Launch a virtual server instance
+</Tabs.Tab>
 
-Click on **Launch instance** to create a new EC2 instance.
+<Tabs.Tab>
+
+```bash copy
+git clone https://<your-username>:<your-personal-access-token>@github.com/<your-username>/<your-repository>.git
+```
 
-#### Configure your instance details
+</Tabs.Tab>
+</Tabs>
 
-Add the following details for your instance:
+Navigate to the repository directory:
 
-- **Name**: Give your instance a descriptive name
-- **Application and OS Images**: For this example, we'll use the **Amazon Linux** environment
-- **Instance type**: Select **t3.micro** (eligible for free tier)
-- **Key pair**: Select an existing key pair or create a new one for secure login
-- **Network settings**: Ensure to **allow HTTPS and HTTP traffic from the internet** by checking the appropriate boxes
+```bash copy
+cd "<your-repository>"
+```
 
-#### Launch your instance
+#### Install dependencies
 
-Review your configuration and click **Launch instance**.
+```bash copy
+npm install
+```
 
-#### Connect to your instance
+#### Set up environment variables
 
-You'll be redirected to a next steps page. You can connect to your instance either:
+Create a `.env` file and add your environment variables:
 
-- **Through the browser**: Click the **Connect** button for browser-based access
-- **Via SSH**: Use your key pair to SSH into the instance (instructions available when you click **Connect**)
+```bash copy
+touch .env
+```
 
-</Steps>
+Edit the `.env` file and add your environment variables:
 
-### Server Configuration
+```bash copy
+OPENAI_API_KEY=<your-openai-api-key>
+# Add other required environment variables
+```
 
-Once you have access to your EC2 instance (either via SSH or browser), follow these steps to set up your server environment:
+#### Build the application
 
-<ServerConfig />
+```bash copy
+npm run build
+```
+
+#### Run the application
+
+```bash copy
+node --import=./.mastra/output/instrumentation.mjs --env-file=".env" .mastra/output/index.mjs
+```
+
+<Callout>
+Your Mastra application will run on port 4111 by default. Ensure your reverse proxy is configured to forward requests to this port.
+</Callout>
+
+</Steps>
 
 ### Connect to your Mastra server
 

package/.docs/raw/deployment/cloud-providers/azure-app-services.mdx

@@ -18,8 +18,8 @@ Deploy your Mastra applications to Azure App Services.
 
 ### Prerequisites
 
-- An Azure account with an active subscription
-- A GitHub repository containing your Mastra application
+- An [Azure account](https://azure.microsoft.com/) with an active subscription
+- A [GitHub repository](https://github.com/) containing your Mastra application
 - Your Mastra application should be created using `npx create-mastra@latest`
 
 ### Deployment Steps
@@ -29,7 +29,7 @@ Deploy your Mastra applications to Azure App Services.
 #### Create a new App Service
 
 - Log in to the [Azure Portal](https://portal.azure.com)
-- Navigate to **App Services** or search for it in the top search bar
+- Navigate to **[App Services](https://docs.microsoft.com/en-us/azure/app-service/)** or search for it in the top search bar
 - Click **Create** to create a new App Service
 - In the drop-down, select **Web App**
 
@@ -67,7 +67,7 @@ Before setting up deployment, configure your environment variables:
 - Navigate to **Deployment Center** in the left sidebar
 - Select **GitHub** as your source
 - Sign in to GitHub if you're not already authenticated with Azure
-- In this example, we will keep GitHub Actions as our provider.
+- In this example, we will keep [GitHub Actions](https://docs.github.com/en/actions) as our provider
 - Select your organization, repository, and branch
 - Azure will generate a GitHub workflow file and you can preview it before proceeding
 - Click **Save** (the save button is located at the top of the page)
@@ -84,7 +84,7 @@ Pull the latest changes to your local repository and modify the generated workfl
 
 1. **Update the build step**: Find the step named "npm install, build, and test" and:
    - Change the step name to "npm install and build"
-   - Remove the `npm test` command from the run section
+   - If you haven't set up proper tests in your Mastra application, remove the `npm test` command from the run section as the default test script will fail and disrupt deployment. If you have working tests, you can keep the test command.
 
 2. **Update the zip artifact step**: Find the "Zip artifact for deployment" step and replace the zip command with:
 
@@ -133,4 +133,5 @@ such as `LibSQLStore` with a file URL. Consider using cloud-based storage soluti
 - [Mastra Client SDK](/docs/client-js/overview)
 - [Configure custom domains](https://docs.microsoft.com/en-us/azure/app-service/app-service-web-tutorial-custom-domain)
 - [Enable HTTPS](https://docs.microsoft.com/en-us/azure/app-service/configure-ssl-bindings)
+- [Azure App Service documentation](https://docs.microsoft.com/en-us/azure/app-service/)
 

package/.docs/raw/deployment/cloud-providers/digital-ocean.mdx

@@ -4,7 +4,6 @@ description: "Deploy your Mastra applications to Digital Ocean."
 ---
 
 import { Callout, Steps, Tabs } from "nextra/components";
-import ServerConfig from "@/components/content-blocks/server-config.mdx";
 
 ## Digital Ocean
 
@@ -25,8 +24,8 @@ Deploy your Mastra applications to Digital Ocean's App Platform and Droplets.
 
 #### Prerequisites [#app-platform-prerequisites]
 
-- A Git repository containing your Mastra application. This can be a GitHub repository, GitLab repository, or any other compatible source provider.
-- A Digital Ocean account
+- A Git repository containing your Mastra application. This can be a [GitHub](https://github.com/) repository, [GitLab](https://gitlab.com/) repository, or any other compatible source provider.
+- A [Digital Ocean account](https://www.digitalocean.com/)
 
 #### Deployment Steps
 
@@ -34,8 +33,8 @@ Deploy your Mastra applications to Digital Ocean's App Platform and Droplets.
 
 #### Create a new App
 
-- Log in to your Digital Ocean dashboard.
-- Navigate to the App Platform service.
+- Log in to your [Digital Ocean dashboard](https://cloud.digitalocean.com/).
+- Navigate to the [App Platform](https://docs.digitalocean.com/products/app-platform/) service.
 - Select your source provider and create a new app.
 
 #### Configure Deployment Source
@@ -76,21 +75,86 @@ such as `LibSQLStore` with a file URL.
 ### Droplets
 
 Deploy your Mastra application to Digital Ocean's Droplets.
-This guide will cover setting up a droplet, a reverse proxy using Nginx, and running your Mastra application.
-
-<Callout>
-The guide assumes your droplet runs Ubuntu 24+.
-</Callout>
 
 #### Prerequisites [#droplets-prerequisites]
 
-- A Digital Ocean account
-- A droplet running Ubuntu 24+
+- A [Digital Ocean account](https://www.digitalocean.com/)
+- A [Droplet](https://docs.digitalocean.com/products/droplets/) running Ubuntu 24+
 - A domain name with an A record pointing to your droplet
+- A reverse proxy configured (e.g., using [nginx](https://nginx.org/))
+- SSL certificate configured (e.g., using [Let's Encrypt](https://letsencrypt.org/))
+- Node.js 18+ installed on your droplet
+
+#### Deployment Steps
+
+<Steps>
+
+#### Clone your Mastra application
+
+Connect to your Droplet and clone your repository:
+
+<Tabs items={["Public Repository", "Private Repository"]}>
+<Tabs.Tab>
+
+```bash copy
+git clone https://github.com/<your-username>/<your-repository>.git
+```
+
+</Tabs.Tab>
+
+<Tabs.Tab>
+
+```bash copy
+git clone https://<your-username>:<your-personal-access-token>@github.com/<your-username>/<your-repository>.git
+```
+
+</Tabs.Tab>
+</Tabs>
+
+Navigate to the repository directory:
 
-#### Setting up the droplet
+```bash copy
+cd "<your-repository>"
+```
+
+#### Install dependencies
+
+```bash copy
+npm install
+```
+
+#### Set up environment variables
+
+Create a `.env` file and add your environment variables:
 
-<ServerConfig />
+```bash copy
+touch .env
+```
+
+Edit the `.env` file and add your environment variables:
+
+```bash copy
+OPENAI_API_KEY=<your-openai-api-key>
+# Add other required environment variables
+```
+
+#### Build the application
+
+```bash copy
+npm run build
+```
+
+#### Run the application
+
+```bash copy
+node --import=./.mastra/output/instrumentation.mjs --env-file=".env" .mastra/output/index.mjs
+```
+
+<Callout>
+Your Mastra application will run on port 4111 by default. Ensure your reverse proxy is configured to forward requests to this port.
+</Callout>
+
+</Steps>
 
 </Tabs.Tab>
 
@@ -109,3 +173,9 @@ const mastraClient = new MastraClient({
   baseUrl: "https://<your-domain-name>",
 });
 ```
+
+## Next steps
+
+- [Mastra Client SDK](/docs/client-js/overview)
+- [Digital Ocean App Platform documentation](https://docs.digitalocean.com/products/app-platform/)
+- [Digital Ocean Droplets documentation](https://docs.digitalocean.com/products/droplets/)