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

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

@@ -1,13 +1,15 @@
 ---
-title: "Creating and Calling Agents | Agent Documentation | Mastra"
+title: "Agent Overview | Agent Documentation | Mastra"
 description: Overview of agents in Mastra, detailing their capabilities and how they interact with tools, workflows, and external systems.
 ---
 
-# Creating and Calling Agents
+# Using Agents
 
-Agents in Mastra are systems where the language model can autonomously decide on a sequence of actions to perform tasks. They have access to tools, workflows, and synced data, enabling them to perform complex tasks and interact with external systems. Agents can invoke your custom functions, utilize third-party APIs through integrations, and access knowledge bases you have built.
+**Agents** are one of the core Mastra primitives. Agents use a language model to decide on a sequence of actions. They can call functions (known as _tools_). You can compose them with *workflows* (the other main Mastra primitive), either by giving an agent a workflow as a tool, or by running an agent from within a workflow.
 
-Agents are like employees who can be used for ongoing projects. They have names, persistent memory, consistent model configurations, and instructions across calls, as well as a set of enabled tools.
+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
 
@@ -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:
@@ -185,11 +189,13 @@ console.log("Structured Output:", response.object);
 
 This allows you to have strong typing and validation for the structured data returned by the agent.
 
-## 4. Multi-step Tool use Agents
+## 4. Multi-step tool use
+
+Agents can be enhanced with tools - functions that extend their capabilities beyond text generation. Tools allow agents to perform calculations, access external systems, and process data. Agents not only decide whether to call tools they're given, they determine the parameters that should be given to that tool.
 
-Agents can be enhanced with tools - functions that extend their capabilities beyond text generation. Tools allow agents to perform calculations, access external systems, and process data. For details on creating and configuring tools, see the [Adding Tools documentation](/docs/agents/using-tools-and-mcp).
+For a detailed guide to creating and configuring tools, see the [Adding Tools documentation](/docs/agents/using-tools-and-mcp), but below are the important things to know.
 
-### Using maxSteps
+### Using `maxSteps`
 
 The `maxSteps` parameter controls the maximum number of sequential LLM calls an agent can make, particularly important when using tool calls. By default, it is set to 1 to prevent infinite loops in case of misconfigured tools. You can increase this limit based on your use case:
 
@@ -217,7 +223,7 @@ const response = await myAgent.generate(
     {
       role: "user",
       content:
-        "If a taxi driver earns $9461 per hour and works 12 hours a day, how much do they earn in one day?",
+        "If a taxi driver earns $41 per hour and works 12 hours a day, how much do they earn in one day?",
     },
   ],
   {
@@ -226,9 +232,10 @@ const response = await myAgent.generate(
 );
 ```
 
-### Using onStepFinish
+### Streaming progress with `onStepFinish`
 
 You can monitor the progress of multi-step operations using the `onStepFinish` callback. This is useful for debugging or providing progress updates to users.
+
 `onStepFinish` is only available when streaming or generating text without structured output.
 
 ```ts showLineNumbers filename="src/mastra/agents/index.ts" copy
@@ -243,7 +250,7 @@ const response = await myAgent.generate(
 );
 ```
 
-### Using onFinish
+### Detecting completion with `onFinish`
 
 The `onFinish` callback is available when streaming responses and provides detailed information about the completed interaction. It is called after the LLM has finished generating its response and all tool executions have completed.
 This callback receives the final response text, execution steps, token usage statistics, and other metadata that can be useful for monitoring and logging:
@@ -270,34 +277,15 @@ const stream = await myAgent.stream(
 );
 ```
 
-## 5. Running Agents
-
-Mastra provides a CLI command `mastra dev` to run your agents behind an API. By default, this looks for exported agents in files in the `src/mastra/agents` directory.
+## 5. Testing agents locally
 
-### Starting the Server
+Mastra provides a CLI command `mastra dev` to run your agents behind an API. By default, this looks for exported agents in files in the `src/mastra/agents` directory. It generates endpoints for testing your agent (eg `http://localhost:4111/api/agents/myAgent/generate`) and provides a visual playground where you can chat with an agent and view traces.
 
-```bash
-mastra dev
-```
-
-This will start the server and make your agent available at `http://localhost:4111/api/agents/myAgent/generate`.
-
-### Interacting with the Agent
-
-You can interact with the agent using `curl` from the command line:
-
-```bash
-curl -X POST http://localhost:4111/api/agents/myAgent/generate \
-  -H "Content-Type: application/json" \
-  -d '{
-    "messages": [
-      { "role": "user", "content": "Hello, how can you assist me today?" }
-    ]
-  }'
-```
+For more details, see the [Local Dev Playground](/docs/server-db/local-dev-playground) docs.
 
 ## 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/community/licensing.mdx

@@ -5,36 +5,39 @@ description: "Mastra License"
 
 # License
 
-## Elastic License 2.0 (ELv2)
+## Apache License 2.0
 
-Mastra is licensed under the Elastic License 2.0 (ELv2), a modern license designed to balance open-source principles with sustainable business practices.
+Mastra is licensed under the Apache License 2.0, a permissive open-source license that provides users with broad rights to use, modify, and distribute the software.
 
-### What is Elastic License 2.0?
+### What is Apache License 2.0?
 
-The Elastic License 2.0 is a source-available license that grants users broad rights to use, modify, and distribute the software while including specific limitations to protect the project's sustainability. It allows:
+The Apache License 2.0 is a permissive open-source license that grants users extensive rights to use, modify, and distribute the software. It allows:
 
-- Free use for most purposes
+- Free use for any purpose, including commercial use
 - Viewing, modifying, and redistributing the source code
 - Creating and distributing derivative works
-- Commercial use within your organization
+- Commercial use without restrictions
+- Patent protection from contributors
 
-The primary limitation is that you cannot provide Mastra as a hosted or managed service that offers users access to the substantial functionality of the software.
+The Apache License 2.0 is one of the most permissive and business-friendly open-source licenses available.
 
-### Why We Chose Elastic License 2.0
+### Why We Chose Apache License 2.0
 
-We selected the Elastic License 2.0 for several important reasons:
+We selected the Apache License 2.0 for several important reasons:
 
-1. **Sustainability**: It enables us to maintain a healthy balance between openness and the ability to sustain long-term development.
+1. **True Open Source**: It's a recognized open-source license that aligns with open-source principles and community expectations.
 
-2. **Innovation Protection**: It ensures we can continue investing in innovation without concerns about our work being repackaged as competing services.
+2. **Business Friendly**: It allows for unrestricted commercial use and distribution, making it ideal for businesses of all sizes.
 
-3. **Community Focus**: It maintains the spirit of open source by allowing users to view, modify, and learn from our code while protecting our ability to support the community.
+3. **Patent Protection**: It includes explicit patent protection for users, providing additional legal security.
 
-4. **Business Clarity**: It provides clear guidelines for how Mastra can be used in commercial contexts.
+4. **Community Focus**: It encourages community contributions and collaboration without restrictions.
+
+5. **Widely Adopted**: It's one of the most popular and well-understood open-source licenses in the industry.
 
 ### Building Your Business with Mastra
 
-Despite the licensing restrictions, there are numerous ways to build successful businesses using Mastra:
+The Apache License 2.0 provides maximum flexibility for building businesses with Mastra:
 
 #### Allowed Business Models
 
@@ -43,6 +46,8 @@ Despite the licensing restrictions, there are numerous ways to build successful
 - **Developing Custom Solutions**: Build bespoke AI solutions for clients using Mastra
 - **Creating Add-ons and Extensions**: Develop and sell complementary tools that extend Mastra's functionality
 - **Training and Education**: Offer courses and educational materials about using Mastra effectively
+- **Hosted Services**: Offer Mastra as a hosted or managed service
+- **SaaS Platforms**: Build SaaS platforms powered by Mastra
 
 #### Examples of Compliant Usage
 
@@ -50,14 +55,17 @@ Despite the licensing restrictions, there are numerous ways to build successful
 - A consulting firm offers implementation and customization services for Mastra
 - A developer creates specialized agents and tools with Mastra and licenses them to other businesses
 - A startup builds a vertical-specific solution (e.g., healthcare AI assistant) powered by Mastra
+- A company offers Mastra as a hosted service to their customers
+- A SaaS platform integrates Mastra as their AI backend
 
-#### What to Avoid
+#### Compliance Requirements
 
-The main restriction is that you cannot offer Mastra itself as a hosted service where users access its core functionality. This means:
+The Apache License 2.0 has minimal requirements:
 
-- Don't create a SaaS platform that is essentially Mastra with minimal modifications
-- Don't offer a managed Mastra service where customers are primarily paying to use Mastra's features
+- **Attribution**: Maintain copyright notices and license information (including NOTICE file)
+- **State Changes**: If you modify the software, state that you have made changes
+- **Include License**: Include a copy of the Apache License 2.0 when distributing
 
 ### Questions About Licensing?
 
-If you have specific questions about how the Elastic License 2.0 applies to your use case, please [contact us](https://discord.gg/BTYqqHKUrf) on Discord for clarification. We're committed to supporting legitimate business use cases while protecting the sustainability of the project.
+If you have specific questions about how the Apache License 2.0 applies to your use case, please [contact us](https://discord.gg/BTYqqHKUrf) on Discord for clarification. We're committed to supporting all legitimate use cases while maintaining the open-source nature of the project.

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/digital-ocean.mdx

@@ -100,7 +100,7 @@ The guide assumes your droplet runs Ubuntu 24+.
 
 You can now connect to your Mastra server from your client application using a `MastraClient` from the `@mastra/client-js` package.
 
-Refer to the [`MastraClient` documentation](../../client-js/overview.mdx) for more information.
+Refer to the [`MastraClient` documentation](/docs/server-db/mastra-client) for more information.
 
 ```typescript copy showLineNumbers
 import { MastraClient } from "@mastra/client-js";

package/.docs/raw/deployment/cloud-providers/index.mdx

@@ -1,17 +1,52 @@
 ---
 title: "Cloud Providers"
 description: "Deploy your Mastra applications to popular cloud providers."
-asIndexPage: true
 ---
 
-import { CardGrid, CardGridItem } from "@/components/cards/card-grid";
-
 ## Cloud Providers
 
-Deploy your Mastra applicaitons to popular cloud providers.
+Standalone Mastra applications can be deployed to popular cloud providers, see one of the following guides for more information:
+
+- [Amazon EC2](/docs/deployment/cloud-providers/amazon-ec2)
+- [AWS Lambda](/docs/deployment/cloud-providers/aws-lambda)
+- [Digital Ocean](/docs/deployment/cloud-providers/digital-ocean)
+- [Azure App Services](/docs/deployment/cloud-providers/azure-app-services)
+
+For self-hosted Node.js server deployment, see the [Creating A Mastra Server](/docs/deployment/server) guide.
+
+## Prerequisites
+
+Before deploying to a cloud provider, ensure you have:
+
+- A [Mastra application](/docs/getting-started/installation)
+- Node.js `v20.0` or higher
+- A GitHub repository for your application (required for most CI/CD setups)
+- Domain name management access (for SSL and HTTPS)
+- Basic familiarity with server setup (e.g. Nginx, environment variables)
+
+## LibSQLStore
+
+`LibSQLStore` writes to the local filesystem, which is not supported in cloud environments that use ephemeral file systems. If you're deploying to platforms like **AWS Lambda**, **Azure App Services**, or **Digital Ocean App Platform**, you **must remove** all usage of `LibSQLStore`.
+
+Specifically, ensure you've removed it from both `src/mastra/index.ts` and `src/mastra/agents/weather-agent.ts`:
+
+```typescript filename="src/mastra/index.ts" showLineNumbers
+export const mastra = new Mastra({
+  // ...
+  storage: new LibSQLStore({ // [!code --]
+    // stores telemetry, evals, ... into memory storage, if it needs to persist, change to file:../mastra.db // [!code --]
+    url: ":memory:", // [!code --]
+  })//[!code --]
+});
+```
 
-<CardGrid>
-  <CardGridItem title="Digital Ocean" description="Deploy your Mastra applications to Digital Ocean" href="./cloud-providers/digital-ocean" />
-  <CardGridItem title="Amazon EC2" description="Deploy your Mastra applications to Amazon EC2" href="./cloud-providers/amazon-ec2" />
-  <CardGridItem title="Azure App Services" description="Deploy your Mastra applications to Azure App Services" href="./cloud-providers/azure-app-services" />
-</CardGrid>
+```typescript filename="src/mastra/agents/weather-agent.ts" showLineNumbers
+export const weatherAgent = new Agent({
+ // ..
+ memory: new Memory({  // [!code --]
+   storage: new LibSQLStore({ // [!code --]
+      url: "file:../mastra.db" // path is relative to the .mastra/output directory // [!code --]
+   }) // [!code --]
+ })//  [!code --]
+});
+```

package/.docs/raw/deployment/server-deployment.mdx

@@ -0,0 +1,56 @@
+---
+title: "Deploy A Mastra Server"
+description: "Deploy a Mastra server with middleware and other options"
+---
+
+# Deploy A Mastra Server
+
+Mastra builds to a standard Node.js server, so you can deploy it to any platform that supports Node.js applications.
+
+- Cloud VMs (AWS EC2, DigitalOcean Droplets, GCP Compute Engine)
+- Container platforms (Docker, Kubernetes)
+- Platform as a Service (Heroku, Railway)
+- Self-hosted servers
+
+See the [Cloud Providers](/docs/deployment/cloud-providers/) for more information.
+
+### Building
+
+Build the application:
+
+```bash copy
+# Build from current directory
+mastra build
+
+# Or specify a directory
+mastra build --dir ./my-project
+```
+
+The build process:
+
+1. Locates entry file (`src/mastra/index.ts` or `src/mastra/index.js`)
+2. Creates `.mastra` output directory
+3. Bundles code using Rollup with tree shaking and source maps
+4. Generates [Hono](https://hono.dev) HTTP server
+
+See [`mastra build`](/reference/cli/build) for all options.
+
+### Running the Server
+
+Start the HTTP server:
+
+```bash copy
+node .mastra/output/index.mjs
+```
+
+### Enable Telemetry for build output
+
+Load instrumentation for the build output like so:
+
+```bash copy
+node --import=./.mastra/output/instrumentation.mjs .mastra/output/index.mjs
+```
+
+## Serverless Deployment
+
+Mastra also supports serverless deployment on Cloudflare Workers, Vercel, and Netlify. See [Serverless Platforms](/docs/deployment/serverless-platforms/) for more information.

package/.docs/raw/deployment/serverless-platforms/cloudflare-deployer.mdx

@@ -24,6 +24,7 @@ import { CloudflareDeployer } from "@mastra/deployer-cloudflare";
 export const mastra = new Mastra({
   // ...
   deployer: new CloudflareDeployer({
+    scope: "your-account-id",
     projectName: "hello-mastra",
     scope: "",
     auth: {
@@ -36,44 +37,23 @@ export const mastra = new Mastra({
 
 > See the [CloudflareDeployer](/reference/deployer/cloudflare) API reference for all available configuration options.
 
-### Cloudflare API token
-
-In your Cloudflare dashboard, navigate to **Profile** > **API Tokens**, then select **Edit Cloudflare Workers** and click **Use template** to create a token for the `CloudflareDeployer`.
-
-> To learn how to create a Cloudflare API token, see [Create API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) in the Cloudflare docs.
-
-## Continuous integration
-In the Cloudflare dashboard, navigate to **Workers** > **Import a repository**. After importing your Mastra project's Git repository, create an application and configure the build settings with:
-
-- **Build command**: `npm run build`
-- **Deploy command**: `cd .mastra/output && npx wrangler deploy`
-
-- **Build command**: `npm run build` (optional)
-
 ## Manual deployment
 
 Manual deployments are also possible using the [Cloudflare Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/). With the Wrangler CLI installed run the following from your project root to deploy your application.
 
+With the Wrangler CLI installed, login and authenticate with your Cloudflare logins:
+
 ```bash copy
-npm run build && wrangler deploy --config .mastra/output/wrangler.json
+npx wrangler login
 ```
 
-> You can also run `wrangler dev --config .mastra/output/wrangler.json` from your project root to test your Mastra application locally.
-
-## Cloudflare secrets
-
-To add secrets to your Cloudflare Workers application, use the Wrangler CLI. Secrets are environment variables that are encrypted and stored securely.
-
-
-For example, to add an API key:
+Run the following to build and deploy your application to Cloudflare
 
 ```bash copy
-npx wrangler secret put OPENAI_API_KEY
+npm run build && wrangler deploy --config .mastra/output/wrangler.json
 ```
 
-When prompted, enter the secret value. The secret will be encrypted and stored securely in your Cloudflare account.
-
-> For more details on managing secrets, see [Environment Variables and Secrets](https://developers.cloudflare.com/workers/configuration/secrets/) in the Cloudflare documentation.
+> You can also run `wrangler dev --config .mastra/output/wrangler.json` from your project root to test your Mastra application locally.
 
 ## Build output
 
@@ -99,13 +79,12 @@ The `CloudflareDeployer` automatically generates a `wrangler.json` configuration
   "compatibility_flags": ["nodejs_compat", "nodejs_compat_populate_process_env"],
   "observability": { "logs": { "enabled": true } },
   "vars": {
-    "OPENAI_API_KEY": "..",
+    "OPENAI_API_KEY": "...",
     "CLOUDFLARE_API_TOKEN": "..."
   }
 }
-```
-
 
+```
 ## Next steps
 
 - [Mastra Client SDK](/docs/client-js/overview)

package/.docs/raw/deployment/serverless-platforms/index.mdx

@@ -19,7 +19,7 @@ For self-hosted Node.js server deployment, see the [Creating A Mastra Server](/d
 
 Before you begin, ensure you have:
 
-- **Node.js** installed (version 18 or higher is recommended)
+- Node.js `v20.0` or higher
 - If using a platform-specific deployer:
   - An account with your chosen platform
   - Required API keys or credentials
@@ -30,23 +30,23 @@ Before you begin, ensure you have:
 
 Specifically, ensure you've removed it from both `src/mastra/index.ts` and `src/mastra/agents/weather-agent.ts`:
 
-```diff filename="src/mastra/index.ts" showLineNumbers
+```typescript filename="src/mastra/index.ts" showLineNumbers
 export const mastra = new Mastra({
   // ...
--  storage: new LibSQLStore({
--    // stores telemetry, evals, ... into memory storage, if it needs to persist, change to file:../mastra.db
--    url: ":memory:",
--  })
+  storage: new LibSQLStore({ // [!code --]
+    // stores telemetry, evals, ... into memory storage, if it needs to persist, change to file:../mastra.db // [!code --]
+    url: ":memory:", // [!code --]
+  })//[!code --]
 });
 ```
 
-``` diff filename="src/mastra/agents/weather-agent.ts" showLineNumbers
+```typescript filename="src/mastra/agents/weather-agent.ts" showLineNumbers
 export const weatherAgent = new Agent({
-  // ..
--  memory: new Memory({
--    storage: new LibSQLStore({
--      url: "file:../mastra.db" // path is relative to the .mastra/output directory
--    })
--  })
+ // ..
+ memory: new Memory({  // [!code --]
+   storage: new LibSQLStore({ // [!code --]
+      url: "file:../mastra.db" // path is relative to the .mastra/output directory // [!code --]
+   }) // [!code --]
+ })//  [!code --]
 });
 ```