@mastra/mcp-docs-server 1.0.0-beta.4 → 1.0.0-beta.6

package/.docs/raw/course/01-first-agent/05-running-playground.md

@@ -1,14 +1,14 @@
-# Running the Playground
+# Running Mastra Studio
 
-To test your agent as you build it, you'll need to run the Mastra playground:
+To test your agent as you build it, you'll need to run the Mastra Studio:
 
 ```bash
 npm run dev
 ```
 
-This will start the playground at `http://localhost:4111/`, where you can interact with your agent and test its capabilities.
+This will start the studio at `http://localhost:4111`, where you can interact with your agent and test its capabilities.
 
-The playground provides a user-friendly interface for testing your agent, allowing you to:
+The studio provides a user-friendly interface for testing your agent, allowing you to:
 
 - Send messages to your agent
 - See the agent's responses
@@ -16,4 +16,4 @@ The playground provides a user-friendly interface for testing your agent, allowi
 - Test tools directly
 - Debug any issues that arise
 
-In the next step, we'll create our first agent with a simple system prompt and test it in the playground.
+In the next step, we'll create our first agent with a simple system prompt and test it in the studio.

package/.docs/raw/course/01-first-agent/09-testing-your-agent.md

@@ -1,12 +1,12 @@
 # Testing Your Agent
 
-Now let's test our agent in the playground:
+Now let's test our agent in Mastra Studio:
 
 1. Make sure your development server is running with `npm run dev`
-2. Open the playground at http://localhost:4111/
+2. Open the studio at http://localhost:4111/
 3. You should see your "Financial Assistant Agent" in the list of agents
 4. Try sending a message like "Hello, can you help me analyze my spending?"
 
 At this point, your agent can respond to basic questions but doesn't have access to any transaction data. In the next step, we'll create a custom tool to fetch transaction data from a Google Sheet.
 
-Testing your agent in the playground is an important step in the development process. It allows you to see how your agent responds to different inputs and identify any issues that need to be addressed before deploying it to production.
+Testing your agent in the studio is an important step in the development process. It allows you to see how your agent responds to different inputs and identify any issues that need to be addressed before deploying it to production.

package/.docs/raw/course/01-first-agent/13-testing-your-tool.md

@@ -1,9 +1,9 @@
 # Testing Your Tool
 
-Let's test our tool and agent in the playground:
+Let's test our tool and agent in Mastra Studio:
 
 1. Make sure your development server is running with `npm run dev`
-2. Open the playground at http://localhost:4111/
+2. Open the studio at http://localhost:4111/
 3. You can test the tool directly in the Tools tab to make sure it's working
 4. Then, try asking your agent questions like:
    - "Can you show me my recent transactions?"
@@ -12,4 +12,4 @@ Let's test our tool and agent in the playground:
 
 Your agent should now be able to fetch the transaction data and answer questions about it. However, it doesn't yet have memory, so it won't remember previous conversations. We'll add that in the next step.
 
-Testing your tool directly in the playground is a great way to verify that it's working correctly before integrating it with your agent. This helps you identify and fix any issues with the tool itself before troubleshooting potential issues with the agent's use of the tool.
+Testing your tool directly in the studio is a great way to verify that it's working correctly before integrating it with your agent. This helps you identify and fix any issues with the tool itself before troubleshooting potential issues with the agent's use of the tool.

package/.docs/raw/course/01-first-agent/17-testing-memory.md

@@ -1,9 +1,9 @@
 # Testing Your Agent with Memory
 
-Let's test our agent's memory capabilities in the playground:
+Let's test our agent's memory capabilities in Mastra Studio:
 
 1. Make sure your development server is running with `npm run dev`
-2. Open the playground at http://localhost:4111/
+2. Open the studio at http://localhost:4111/
 3. Start a conversation with your agent by asking about transactions
 4. Then, ask a follow-up question that references the previous conversation, like:
    - "What was that largest transaction again?"

package/.docs/raw/course/04-workflows/07-using-playground.md

@@ -14,7 +14,7 @@ You should see output like:
 
 ```bash
 🚀 Mastra Dev Server starting...
-📊 Playground available at: http://localhost:4111
+📊 Studio available at: http://localhost:4111
 ```
 
 ## Accessing Workflows in Playground

package/.docs/raw/deployment/building-mastra.mdx

@@ -9,7 +9,7 @@ Mastra runs as a standard Node.js server and can be deployed across a wide range
 
 ## Default project structure
 
-The [getting started guide](/guides/v1/quickstarts/standalone-server) scaffolds a project with sensible defaults to help you begin quickly. By default, the CLI organizes application files under the `src/mastra/` directory, resulting in a structure similar to the following:
+The [getting started guide](/guides/v1/getting-started/quickstart) scaffolds a project with sensible defaults to help you begin quickly. By default, the CLI organizes application files under the `src/mastra/` directory, resulting in a structure similar to the following:
 
 ```
 src/

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

@@ -16,7 +16,7 @@ Deploy your Mastra applications to Amazon EC2 (Elastic Cloud Compute).
 This guide assumes your Mastra application has been created using the default
 `npx create-mastra@beta` command.
 For more information on how to create a new Mastra application,
-refer to our [getting started guide](/guides/v1/quickstarts/standalone-server)
+refer to our [getting started guide](/guides/v1/getting-started/quickstart)
 :::
 
 ## Prerequisites

package/.docs/raw/deployment/cloud-providers/aws-lambda.mdx

@@ -15,7 +15,7 @@ This approach allows you to run your Mastra server as a containerized Lambda fun
 This guide assumes your Mastra application has been created using the default
 `npx create-mastra@beta` command.
 For more information on how to create a new Mastra application,
-refer to our [getting started guide](/guides/v1/quickstarts/standalone-server)
+refer to our [getting started guide](/guides/v1/getting-started/quickstart)
 :::
 
 ## Prerequisites

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

@@ -14,7 +14,7 @@ Deploy your Mastra applications to Azure App Services.
 This guide assumes your Mastra application has been created using the default
 `npx create-mastra@beta` command.
 For more information on how to create a new Mastra application,
-refer to our [getting started guide](/guides/v1/quickstarts/standalone-server)
+refer to our [getting started guide](/guides/v1/getting-started/quickstart)
 :::
 
 ## Prerequisites

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

@@ -16,7 +16,7 @@ Deploy your Mastra applications to Digital Ocean's App Platform and Droplets.
 This guide assumes your Mastra application has been created using the default
 `npx create-mastra@beta` command.
 For more information on how to create a new Mastra application,
-refer to our [getting started guide](/guides/v1/quickstarts/standalone-server)
+refer to our [getting started guide](/guides/v1/getting-started/quickstart)
 :::
 
 <Tabs>

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

@@ -15,14 +15,13 @@ Standalone Mastra applications can be deployed to popular cloud providers, see o
 - [Netlify](/docs/v1/deployment/cloud-providers/netlify-deployer)
 - [Vercel](/docs/v1/deployment/cloud-providers/vercel-deployer)
 
-
 For self-hosted Node.js server deployment, see the [Creating A Mastra Server](/docs/v1/deployment/building-mastra) guide.
 
 ## Prerequisites
 
 Before deploying to a cloud provider, ensure you have:
 
-- A [Mastra application](/guides/v1/quickstarts/standalone-server)
+- A [Mastra application](/guides/v1/getting-started/quickstart)
 - Node.js `v22.13.0` or later
 - A GitHub repository for your application (required for most CI/CD setups)
 - Domain name management access (for SSL and HTTPS)
@@ -30,33 +29,27 @@ Before deploying to a cloud provider, ensure you have:
 
 ## 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`.
+`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, Netlify, 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`:
+Specifically, ensure you've removed it from all Mastra files, including configuration on the main Mastra instance and any agents using it, e.g. for memory storage.
 
-```typescript title="src/mastra/index.ts" showLineNumbers
-export const mastra = new Mastra({
-  // ...
-  storage: new LibSQLStore({
-    id: 'mastra-storage',
-    // [!code --]
-    // stores telemetry, scorer results, ... into memory storage, if it needs to persist, change to file:../mastra.db // [!code --]
-    url: ":memory:", // [!code --]
-  }), //[!code --]
-});
+```diff title="src/mastra/index.ts"
+ export const mastra = new Mastra({
+-  storage: new LibSQLStore({
+-    id: 'mastra-storage',
+-    url: ":memory:",
+-  }),
+ });
 ```
 
-```typescript title="src/mastra/agents/weather-agent.ts" showLineNumbers
-export const weatherAgent = new Agent({
-  id: "weather-agent",
-  // ..
-  memory: new Memory({
-    // [!code --]
-    storage: new LibSQLStore({
-      id: 'mastra-storage',
-      // [!code --]
-      url: "file:../mastra.db", // path is relative to the .mastra/output directory // [!code --]
-    }), // [!code --]
-  }), //  [!code --]
-});
+```diff
+ export const weatherAgent = new Agent({
+   id: "weather-agent",
+   memory: new Memory({
+-    storage: new LibSQLStore({
+-      id: 'mastra-storage',
+-      url: "file:../mastra.db",
+-    }),
+   }),
+ });
 ```

package/.docs/raw/deployment/cloud-providers/netlify-deployer.mdx

@@ -15,12 +15,11 @@ npm install @mastra/deployer-netlify@beta
 
 ## Usage example
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts" copy
 import { Mastra } from "@mastra/core";
 import { NetlifyDeployer } from "@mastra/deployer-netlify";
 
 export const mastra = new Mastra({
-  // ...
   deployer: new NetlifyDeployer(),
 });
 ```
@@ -43,32 +42,64 @@ Your project is now configured with automatic deployments which occur whenever y
 
 ## Manual deployment
 
-Manual deployments are also possible using the [Netlify CLI](https://docs.netlify.com/cli/get-started/). With the Netlify CLI installed run the following from your project root to deploy your application.
+Manual deployments are also possible using the [Netlify CLI](https://docs.netlify.com/cli/get-started/). With the Netlify CLI installed run the following from your project root to deploy your application. You can also run `netlify dev` from your project root to test your Mastra application locally.
 
 ```bash copy
 netlify deploy --prod
 ```
 
-> You can also run `netlify dev` from your project root to test your Mastra application locally.
+:::warning
 
-## Build output
+When using `netlify deploy` instead of continuous deployment, you need to create a `netlify.toml` file with these contents:
+
+```toml
+[build]
+  command = "npm run build"
+  publish = ".netlify/v1/functions"
 
-The build output for Mastra applications using the `NetlifyDeployer` includes all agents, tools, and workflows in your project, along with Mastra specific files required to run your application on Netlify.
+[functions]
+  directory = ".netlify/v1/functions"
+  node_bundler = "none"
+  included_files = [".netlify/v1/functions/**"]
 
+[[redirects]]
+  from = "/*"
+  to = "/.netlify/functions/api/:splat"
+  status = 200
+
+[build.environment]
+  NODE_VERSION = "22.13.0"
 ```
-.netlify/
-└── v1/
-    ├── functions/
-    │   └── api/
-    │       └── index.mjs
-    └── config.json
-package.json
+
+Adjust the `build.command` to your project.
+
+:::
+
+## Build output
+
+The build output for Mastra applications using the `NetlifyDeployer` includes all agents, tools, and workflows in your project, along with Mastra-specific files required to run your application on Netlify.
+
+```bash
+your-project/
+└── .netlify/
+    └── v1/
+        ├── config.json
+        └── functions/
+            └── api/
+                ├── index.js
+                ├── package.json
+                └── node_modules/
 ```
 
 The `NetlifyDeployer` automatically generates a `config.json` configuration file in `.netlify/v1` with the following settings:
 
 ```json
 {
+  "functions": {
+    "directory": ".netlify/v1/functions",
+    "node_bundler": "none",
+    "included_files": [".netlify/v1/functions/**"]
+  },
   "redirects": [
     {
       "force": true,

package/.docs/raw/deployment/mastra-cloud/observability.mdx

@@ -7,45 +7,47 @@ import { MastraCloudCallout } from "@site/src/components/MastraCloudCallout";
 
 # Understanding Tracing and Logs
 
-Mastra Cloud captures execution data to help you monitor your application's behavior in the production environment.
+Mastra Cloud provides full observability for production applications, giving you insight into how your agents and workflows behave. Observability can be enabled whether your application is deployed to Mastra Cloud, running locally, or hosted on your own infrastructure. Any Mastra project can send traces and logs to the platform regardless of where it's running.
 
-<MastraCloudCallout />
-
-## Logs
+For details on configuring observability, see the [Cloud Exporter](/docs/v1/observability/tracing/exporters/cloud) docs.
 
-You can view detailed logs for debugging and monitoring your application's behavior on the [Logs](/docs/v1/deployment/mastra-cloud/dashboard#logs) page of the Dashboard.
-
-![Dashboard logs](/img/mastra-cloud/mastra-cloud-dashboard-logs.jpg)
-
-Key features:
-
-Each log entry includes its severity level and a detailed message showing agent, workflow, or storage activity.
+<MastraCloudCallout />
 
 ## Traces
 
-More detailed traces are available for both agents and workflows by using a [logger](/docs/v1/logging) or enabling [observability](/docs/v1/observability/tracing/overview) using one of our [supported providers](/docs/v1/observability/tracing/overview#exporters).
+More detailed traces are available for both agents and workflows by enabling [observability](/docs/v1/observability/tracing/overview) using one of our [supported providers](/docs/v1/observability/tracing/overview#exporters).
 
 ### Agents
 
-With a [logger](/docs/v1/logging) enabled, you can view detailed outputs from your agents in the **Traces** section in Studio.
+With observability enabled, you can view detailed outputs from your agents in the **Traces** section in Studio.
 
 ![observability agents](/img/mastra-cloud/mastra-cloud-observability-agents.jpg)
 
 Key features:
 
-Tools passed to the agent during generation are standardized using `convertTools`. This includes retrieving client-side tools, memory tools, and tools exposed from workflows.
+Agent traces break a run into clear steps, model calls, tool calls, and intermediate chunks, each with timing, inputs, outputs, and errors. You can drill into any span to inspect prompts, token usage, and results, making it easy to diagnose issues and understand how the agent produced its output.
 
 ### Workflows
 
-With a [logger](/docs/v1/logging) enabled, you can view detailed outputs from your workflows in the **Traces** section in Studio.
+With observability enabled, you can view detailed outputs from your workflows in the **Traces** section in Studio.
 
 ![observability workflows](/img/mastra-cloud/mastra-cloud-observability-workflows.jpg)
 
 Key features:
 
-Workflows are created using `createWorkflow`, which sets up steps, metadata, and tools. You can run them with `runWorkflow` by passing input and options.
+Workflow traces capture each step in the run, including transitions, branching, timing, and any tool calls inside the workflow. You can inspect inputs, outputs, and errors for every step, making it easy to debug long-running or multi-step processes and understand how data flows through the workflow.
+
+## Logs
+
+You can view detailed logs for debugging and monitoring your application's behavior on the [Logs](/docs/v1/deployment/mastra-cloud/dashboard#logs) page of the Dashboard.
+
+![Dashboard logs](/img/mastra-cloud/mastra-cloud-dashboard-logs.jpg)
+
+Key features:
+
+Each log entry includes its severity level and a detailed message showing agent, workflow, or storage activity.
 
 ## Next steps
 
-- [Logging](/docs/v1/logging)
+- [Logging](/docs/v1/observability/logging)
 - [Tracing](/docs/v1/observability/tracing/overview)

package/.docs/raw/deployment/mastra-cloud/setting-up.mdx

@@ -18,7 +18,7 @@ This page explains how to set up a project on [Mastra Cloud](https://mastra.ai/c
 - A [Mastra Cloud](https://mastra.ai/cloud) account
 - A GitHub account / repository containing a Mastra application
 
-> See our [Getting started](/guides/v1/quickstarts/standalone-server) guide to scaffold out a new Mastra project with sensible defaults.
+> See our [Getting started](/guides/v1/getting-started/quickstart) guide to scaffold out a new Mastra project with sensible defaults.
 
 ## Setup and Deploy process
 

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

@@ -41,8 +41,8 @@ Mastra Cloud is a deployment platform that connects to your GitHub repository, a
 
 Mastra can be integrated with a variety of web frameworks. For example, see one of the following for a detailed guide.
 
-- [With Next.js](../frameworks/web-frameworks/next-js)
-- [With Astro](../frameworks/web-frameworks/astro)
+- [With Next.js](/guides/v1/getting-started/next-js)
+- [With Astro](/guides/v1/getting-started/astro)
 
 When integrated with a framework, Mastra typically requires no additional configuration for deployment.
 

package/.docs/raw/deployment/web-framework.mdx

@@ -7,14 +7,14 @@ description: "Learn how Mastra can be deployed when integrated with a Web Framew
 
 This guide covers deploying integrated Mastra applications. Mastra can be integrated with a variety of web frameworks, see one of the following for a detailed guide.
 
-- [With Next.js](/docs/v1/frameworks/web-frameworks/next-js)
-- [With Astro](/docs/v1/frameworks/web-frameworks/astro)
+- [With Next.js](/guides/v1/getting-started/next-js)
+- [With Astro](/guides/v1/getting-started/astro)
 
 When integrated with a framework, Mastra typically requires no additional configuration for deployment.
 
 ## With Next.js on Vercel
 
-If you've integrated Mastra with Next.js [by following our guide](/docs/v1/frameworks/web-frameworks/next-js) and plan to deploy to Vercel, no additional setup is required.
+If you've integrated Mastra with Next.js [by following our guide](/guides/v1/getting-started/next-js) and plan to deploy to Vercel, no additional setup is required.
 
 The only thing to verify is that you've added the following to your `next.config.ts` and removed any usage of [LibSQLStore](/docs/v1/deployment/overview), which is not supported in serverless environments:
 
@@ -30,7 +30,7 @@ export default nextConfig;
 
 ## With Astro on Vercel
 
-If you've integrated Mastra with Astro [by following our guide](/docs/v1/frameworks/web-frameworks/astro) and plan to deploy to Vercel, no additional setup is required.
+If you've integrated Mastra with Astro [by following our guide](/guides/v1/getting-started/astro) and plan to deploy to Vercel, no additional setup is required.
 
 The only thing to verify is that you've added the following to your `astro.config.mjs` and removed any usage of [LibSQLStore](/docs/v1/deployment/overview), which is not supported in serverless environments:
 
@@ -47,7 +47,7 @@ export default defineConfig({
 
 ## With Astro on Netlify
 
-If you've integrated Mastra with Astro [by following our guide](/docs/v1/frameworks/web-frameworks/astro) and plan to deploy to Netlify, no additional setup is required.
+If you've integrated Mastra with Astro [by following our guide](/guides/v1/getting-started/astro) and plan to deploy to Netlify, no additional setup is required.
 
 The only thing to verify is that you've added the following to your `astro.config.mjs` and removed any usage of [LibSQLStore](/docs/v1/deployment/overview), which is not supported in serverless environments:
 

package/.docs/raw/evals/custom-scorers.mdx

@@ -41,13 +41,12 @@ Every scorer starts with the `createScorer` factory function, which requires a n
 
 ```typescript
 import { createScorer } from '@mastra/core/evals';
-import { openai } from '@ai-sdk/openai';
 
 const glutenCheckerScorer = createScorer({
   name: 'Gluten Checker',
   description: 'Check if recipes contain gluten ingredients',
   judge: {                    // Optional: for prompt object steps
-    model: openai('gpt-4o'),
+    model: 'openai/gpt-5.1',
     instructions: 'You are a Chef that identifies if recipes contain gluten.'
   }
 })
@@ -245,7 +244,6 @@ Together, these components allow you to define custom evaluation logic using LLM
 > See [createScorer](/reference/v1/evals/create-scorer) for the full API and configuration options.
 
 ```typescript title="src/mastra/scorers/gluten-checker.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { createScorer } from "@mastra/core/evals";
 import { z } from "zod";
 
@@ -303,7 +301,7 @@ export const glutenCheckerScorer = createScorer({
   name: "Gluten Checker",
   description: "Check if the output contains any gluten",
   judge: {
-    model: openai("gpt-4o"),
+    model: "openai/gpt-4.1-nano",
     instructions: GLUTEN_INSTRUCTIONS,
   },
 })
@@ -338,7 +336,7 @@ Sets up the LLM model and defines its role as a domain expert.
 
 ```typescript
 judge: {
-  model: openai('gpt-4o'),
+  model: 'openai/gpt-4.1-nano',
   instructions: GLUTEN_INSTRUCTIONS,
 }
 ```

package/.docs/raw/evals/overview.mdx

@@ -37,7 +37,6 @@ You can add built-in scorers to your agents to automatically evaluate their outp
 
 ```typescript title="src/mastra/agents/evaluated-agent.ts" showLineNumbers copy
 import { Agent } from "@mastra/core/agent";
-import { openai } from "@ai-sdk/openai";
 import {
   createAnswerRelevancyScorer,
   createToxicityScorer,
@@ -47,11 +46,11 @@ export const evaluatedAgent = new Agent({
   // ...
   scorers: {
     relevancy: {
-      scorer: createAnswerRelevancyScorer({ model: openai("gpt-4o-mini") }),
+      scorer: createAnswerRelevancyScorer({ model: "openai/gpt-4.1-nano" }),
       sampling: { type: "ratio", rate: 0.5 },
     },
     safety: {
-      scorer: createToxicityScorer({ model: openai("gpt-4o-mini") }),
+      scorer: createToxicityScorer({ model: "openai/gpt-4.1-nano" }),
       sampling: { type: "ratio", rate: 1 },
     },
   },

package/.docs/raw/evals/running-in-ci.mdx

@@ -49,8 +49,6 @@ describe('Weather Agent Tests', () => {
 });
 ```
 
-View the full example [here](/examples/v1/evals/running-in-ci)
-
 ## Understanding Results
 
 The `runEvals` function returns an object with:

package/.docs/raw/{guides/guide → getting-started}/manual-install.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Manual Install | Guides"
+title: "Manual Install | Getting Started"
 description: Set up a Mastra project manually without using the create mastra CLI.
 ---
 
@@ -11,7 +11,7 @@ import StepItem from "@site/src/components/StepItem";
 # Manual Install
 
 :::info
-Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow the [Standalone Server Quickstart](/guides/v1/quickstarts/standalone-server), which achieves the same result using the [`mastra create`](/reference/v1/cli/create-mastra) command. For existing projects, you can also use [`mastra init`](/reference/v1/cli/mastra#mastra-init).
+Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow a [getting-started guide](/docs/v1/getting-started/start), which achieves the same result using the [`mastra create`](/reference/v1/cli/create-mastra) command. For existing projects, you can also use [`mastra init`](/reference/v1/cli/mastra#mastra-init).
 :::
 
 If you prefer not to use our automatic CLI tool, you can set up your project yourself by following the guide below.

package/.docs/raw/getting-started/project-structure.mdx

@@ -62,6 +62,6 @@ Top-level files define how your Mastra project is configured, built, and connect
 ## Next steps
 
 - Read more about [Mastra's features](/docs/v1#why-mastra).
-- Integrate Mastra with your frontend framework: [Next.js](/docs/v1/frameworks/web-frameworks/next-js), [React](/docs/v1/frameworks/web-frameworks/vite-react), or [Astro](/docs/v1/frameworks/web-frameworks/astro).
+- Integrate Mastra with your frontend framework: [Next.js](/guides/v1/getting-started/next-js), [React](/guides/v1/getting-started/vite-react), or [Astro](/guides/v1/getting-started/astro).
 - Build an agent from scratch following one of our [guides](/guides/v1).
 - Watch conceptual guides on our [YouTube channel](https://www.youtube.com/@mastra-ai) and [subscribe](https://www.youtube.com/@mastra-ai?sub_confirmation=1)!

package/.docs/raw/getting-started/start.mdx

@@ -0,0 +1,72 @@
+---
+title: "Start with Mastra | Getting Started"
+description: Choose how to get started with Mastra - quickstart, framework integration, or agentic UI.
+---
+
+import { CardGrid, CardGridItem } from "@site/src/components/cards/card-grid";
+ 
+# Start
+Create a new Mastra project, or integrate Mastra with your preferred framework to start building.
+
+## New project
+
+The `create mastra` command is the fastest way to build your first agent. It walks you through setup and generates an example agent you can run and adapt in [Studio](/docs/v1/getting-started/studio) right away. You can always integrate Mastra with your framework or UI when you’re ready.
+
+<CardGrid columns={1}>
+  <CardGridItem
+    title="Quickstart"
+    href="/guides/v1/getting-started/quickstart"
+    logo={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 34 21" fill="none" width="32" height="32"><path d="M4.49805 11.6934C6.98237 11.6934 8.99609 13.7081 8.99609 16.1924C8.9959 18.6765 6.98225 20.6904 4.49805 20.6904C2.01394 20.6903 0.000196352 18.6765 0 16.1924C0 13.7081 2.01382 11.6935 4.49805 11.6934ZM10.3867 0C12.8709 0 14.8846 2.01388 14.8848 4.49805C14.8848 4.8377 14.847 5.16846 14.7755 5.48643C14.4618 6.88139 14.1953 8.4633 14.9928 9.65L16.2575 11.5319C16.3363 11.6491 16.4727 11.7115 16.6137 11.703C16.7369 11.6957 16.8525 11.6343 16.9214 11.5318L18.1876 9.64717C18.9772 8.47198 18.7236 6.90783 18.4205 5.52484C18.3523 5.21392 18.3164 4.89094 18.3164 4.55957C18.3167 2.07546 20.3313 0.0615234 22.8154 0.0615234C25.2994 0.0617476 27.3132 2.0756 27.3135 4.55957C27.3135 4.93883 27.2665 5.30712 27.178 5.65896C26.8547 6.94441 26.5817 8.37932 27.2446 9.52714L28.459 11.6301C28.4819 11.6697 28.5245 11.6934 28.5703 11.6934C31.0545 11.6935 33.0684 13.7081 33.0684 16.1924C33.0682 18.6765 31.0544 20.6903 28.5703 20.6904C26.0861 20.6904 24.0725 18.6765 24.0723 16.1924C24.0723 15.8049 24.1212 15.4288 24.2133 15.0701C24.5458 13.7746 24.8298 12.3251 24.1609 11.1668L23.0044 9.16384C22.9656 9.09659 22.8931 9.05859 22.8154 9.05859C22.7983 9.05859 22.7824 9.06614 22.7728 9.08033L21.4896 10.9895C20.686 12.1851 20.9622 13.781 21.284 15.1851C21.3582 15.5089 21.3975 15.8461 21.3975 16.1924C21.3973 18.6764 19.3834 20.6902 16.8994 20.6904C14.4152 20.6904 12.4006 18.6765 12.4004 16.1924C12.4004 15.932 12.4226 15.6768 12.4651 15.4286C12.6859 14.14 12.8459 12.7122 12.1167 11.6271L11.2419 10.3253C10.6829 9.49347 9.71913 9.05932 8.78286 8.70188C7.0906 8.05584 5.88867 6.41734 5.88867 4.49805C5.88886 2.0139 7.90254 3.29835e-05 10.3867 0Z" fill="currentColor"/></svg>}
+  >
+    Spin up a Mastra server and interact with agents in Studio or via the API
+  </CardGridItem>
+</CardGrid>
+
+## Integrate with your framework
+
+Add Mastra to an existing project, or scaffold a new Mastra-powered app if you’re starting from scratch.
+
+<CardGrid columns={3}>
+  <CardGridItem
+    title="Next.js"
+    href="/guides/v1/getting-started/next-js"
+    logo={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 180 180" width="32"><mask height="180" id=":r8:mask0_408_134" maskUnits="userSpaceOnUse" width="180" x="0" y="0" style={{maskType: "alpha"}}><circle cx="90" cy="90" fill="black" r="90"></circle></mask><g mask="url(#:r8:mask0_408_134)"><circle cx="90" cy="90" data-circle="true" fill="black" r="90"></circle><path d="M149.508 157.52L69.142 54H54V125.97H66.1136V69.3836L139.999 164.845C143.333 162.614 146.509 160.165 149.508 157.52Z" fill="url(#:r8:paint0_linear_408_134)"></path><rect fill="url(#:r8:paint1_linear_408_134)" height="72" width="12" x="115" y="54"></rect></g><defs><linearGradient gradientUnits="userSpaceOnUse" id=":r8:paint0_linear_408_134" x1="109" x2="144.5" y1="116.5" y2="160.5"><stop stopColor="white"></stop><stop offset="1" stopColor="white" stopOpacity="0"></stop></linearGradient><linearGradient gradientUnits="userSpaceOnUse" id=":r8:paint1_linear_408_134" x1="121" x2="120.799" y1="54" y2="106.875"><stop stopColor="white"></stop><stop offset="1" stopColor="white" stopOpacity="0"></stop></linearGradient></defs></svg>}
+  >
+    Build an AI-powered Next.js app
+  </CardGridItem>
+  <CardGridItem
+    title="React"
+    href="/guides/v1/getting-started/vite-react"
+    logo={<svg width="32" height="32" viewBox="0 0 569 512" xmlns="http://www.w3.org/2000/svg"><g fill="#087EA4" fillRule="nonzero"><path d="M285.5,201 C255.400481,201 231,225.400481 231,255.5 C231,285.599519 255.400481,310 285.5,310 C315.599519,310 340,285.599519 340,255.5 C340,225.400481 315.599519,201 285.5,201"></path><path d="M568.959856,255.99437 C568.959856,213.207656 529.337802,175.68144 466.251623,150.985214 C467.094645,145.423543 467.85738,139.922107 468.399323,134.521063 C474.621631,73.0415145 459.808523,28.6686204 426.709856,9.5541429 C389.677085,-11.8291748 337.36955,3.69129898 284.479928,46.0162134 C231.590306,3.69129898 179.282771,-11.8291748 142.25,9.5541429 C109.151333,28.6686204 94.3382249,73.0415145 100.560533,134.521063 C101.102476,139.922107 101.845139,145.443621 102.708233,151.02537 C97.4493791,153.033193 92.2908847,155.161486 87.3331099,157.39017 C31.0111824,182.708821 0,217.765415 0,255.99437 C0,298.781084 39.6220545,336.307301 102.708233,361.003527 C101.845139,366.565197 101.102476,372.066633 100.560533,377.467678 C94.3382249,438.947226 109.151333,483.32012 142.25,502.434597 C153.629683,508.887578 166.52439,512.186771 179.603923,511.991836 C210.956328,511.991836 247.567589,495.487529 284.479928,465.972527 C321.372196,495.487529 358.003528,511.991836 389.396077,511.991836 C402.475265,512.183856 415.36922,508.884856 426.75,502.434597 C459.848667,483.32012 474.661775,438.947226 468.439467,377.467678 C467.897524,372.066633 467.134789,366.565197 466.291767,361.003527 C529.377946,336.347457 569,298.761006 569,255.99437 M389.155214,27.1025182 C397.565154,26.899606 405.877839,28.9368502 413.241569,33.0055186 C436.223966,46.2772304 446.540955,82.2775015 441.522965,131.770345 C441.181741,135.143488 440.780302,138.556788 440.298575,141.990165 C414.066922,134.08804 387.205771,128.452154 360.010724,125.144528 C343.525021,103.224055 325.192524,82.7564475 305.214266,63.9661533 C336.586743,39.7116483 366.032313,27.1025182 389.135142,27.1025182 M378.356498,310.205598 C368.204912,327.830733 357.150626,344.919965 345.237759,361.405091 C325.045049,363.479997 304.758818,364.51205 284.459856,364.497299 C264.167589,364.51136 243.888075,363.479308 223.702025,361.405091 C211.820914,344.919381 200.80007,327.83006 190.683646,310.205598 C180.532593,292.629285 171.306974,274.534187 163.044553,255.99437 C171.306974,237.454554 180.532593,219.359455 190.683646,201.783142 C200.784121,184.229367 211.770999,167.201087 223.601665,150.764353 C243.824636,148.63809 264.145559,147.579168 284.479928,147.591877 C304.772146,147.579725 325.051559,148.611772 345.237759,150.68404 C357.109048,167.14607 368.136094,184.201112 378.27621,201.783142 C388.419418,219.363718 397.644825,237.458403 405.915303,255.99437 C397.644825,274.530337 388.419418,292.625022 378.27621,310.205598 M419.724813,290.127366 C426.09516,307.503536 431.324985,325.277083 435.380944,343.334682 C417.779633,348.823635 399.836793,353.149774 381.668372,356.285142 C388.573127,345.871232 395.263781,335.035679 401.740334,323.778483 C408.143291,312.655143 414.144807,301.431411 419.805101,290.207679 M246.363271,390.377981 C258.848032,391.140954 271.593728,391.582675 284.5,391.582675 C297.406272,391.582675 310.232256,391.140954 322.737089,390.377981 C310.880643,404.583418 298.10766,417.997563 284.5,430.534446 C270.921643,417.999548 258.18192,404.585125 246.363271,390.377981 Z M187.311556,356.244986 C169.137286,353.123646 151.187726,348.810918 133.578912,343.334682 C137.618549,325.305649 142.828222,307.559058 149.174827,290.207679 C154.754833,301.431411 160.736278,312.655143 167.239594,323.778483 C173.74291,334.901824 180.467017,345.864539 187.311556,356.285142 M149.174827,221.760984 C142.850954,204.473938 137.654787,186.794745 133.619056,168.834762 C151.18418,163.352378 169.085653,159.013101 187.211197,155.844146 C180.346585,166.224592 173.622478,176.986525 167.139234,188.210257 C160.65599,199.433989 154.734761,210.517173 149.074467,221.760984 M322.616657,121.590681 C310.131896,120.827708 297.3862,120.385987 284.379568,120.385987 C271.479987,120.385987 258.767744,120.787552 246.242839,121.590681 C258.061488,107.383537 270.801211,93.9691137 284.379568,81.4342157 C297.99241,93.9658277 310.765727,107.380324 322.616657,121.590681 Z M401.70019,188.210257 C395.196875,176.939676 388.472767,166.09743 381.527868,155.68352 C399.744224,158.819049 417.734224,163.151949 435.380944,168.654058 C431.331963,186.680673 426.122466,204.426664 419.785029,221.781062 C414.205023,210.55733 408.203506,199.333598 401.720262,188.230335 M127.517179,131.790423 C122.438973,82.3176579 132.816178,46.2973086 155.778503,33.0255968 C163.144699,28.9632474 171.455651,26.9264282 179.864858,27.1225964 C202.967687,27.1225964 232.413257,39.7317265 263.785734,63.9862316 C243.794133,82.7898734 225.448298,103.270812 208.949132,125.204763 C181.761691,128.528025 154.90355,134.14313 128.661281,141.990165 C128.199626,138.556788 127.778115,135.163566 127.456963,131.790423 M98.4529773,182.106474 C101.54406,180.767925 104.695358,179.429376 107.906872,178.090828 C114.220532,204.735668 122.781793,230.7969 133.498624,255.99437 C122.761529,281.241316 114.193296,307.357063 107.8868,334.058539 C56.7434387,313.076786 27.0971497,284.003505 27.0971497,255.99437 C27.0971497,229.450947 53.1907013,202.526037 98.4529773,182.106474 Z M155.778503,478.963143 C132.816178,465.691432 122.438973,429.671082 127.517179,380.198317 C127.838331,376.825174 128.259842,373.431953 128.721497,369.978497 C154.953686,377.878517 181.814655,383.514365 209.009348,386.824134 C225.500295,408.752719 243.832321,429.233234 263.805806,448.042665 C220.069,481.834331 180.105722,492.97775 155.838719,478.963143 M441.502893,380.198317 C446.520883,429.691161 436.203894,465.691432 413.221497,478.963143 C388.974566,493.017906 348.991216,481.834331 305.274481,448.042665 C325.241364,429.232737 343.566681,408.752215 360.050868,386.824134 C387.245915,383.516508 414.107066,377.880622 440.338719,369.978497 C440.820446,373.431953 441.221885,376.825174 441.563109,380.198317 M461.193488,334.018382 C454.869166,307.332523 446.294494,281.231049 435.561592,255.99437 C446.289797,230.744081 454.857778,204.629101 461.173416,177.930202 C512.216417,198.911955 541.942994,227.985236 541.942994,255.99437 C541.942994,284.003505 512.296705,313.076786 461.153344,334.058539"></path></g></svg>}
+    preserveLogoColor
+  >
+    Add agents to your React + Vite app
+  </CardGridItem>
+  <CardGridItem
+    title="SvelteKit"
+    href="/guides/v1/getting-started/sveltekit"
+    logo={<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 107 128"><path d="M94.1566,22.8189c-10.4-14.8851-30.94-19.2971-45.7914-9.8348L22.2825,29.6078A29.9234,29.9234,0,0,0,8.7639,49.6506a31.5136,31.5136,0,0,0,3.1076,20.2318A30.0061,30.0061,0,0,0,7.3953,81.0653a31.8886,31.8886,0,0,0,5.4473,24.1157c10.4022,14.8865,30.9423,19.2966,45.7914,9.8348L84.7167,98.3921A29.9177,29.9177,0,0,0,98.2353,78.3493,31.5263,31.5263,0,0,0,95.13,58.117a30,30,0,0,0,4.4743-11.1824,31.88,31.88,0,0,0-5.4473-24.1157" fill="#ff3e00"/><path d="M45.8171,106.5815A20.7182,20.7182,0,0,1,23.58,98.3389a19.1739,19.1739,0,0,1-3.2766-14.5025,18.1886,18.1886,0,0,1,.6233-2.4357l.4912-1.4978,1.3363.9815a33.6443,33.6443,0,0,0,10.203,5.0978l.9694.2941-.0893.9675a5.8474,5.8474,0,0,0,1.052,3.8781,6.2389,6.2389,0,0,0,6.6952,2.485,5.7449,5.7449,0,0,0,1.6021-.7041L69.27,76.281a5.4306,5.4306,0,0,0,2.4506-3.631,5.7948,5.7948,0,0,0-.9875-4.3712,6.2436,6.2436,0,0,0-6.6978-2.4864,5.7427,5.7427,0,0,0-1.6.7036l-9.9532,6.3449a19.0329,19.0329,0,0,1-5.2965,2.3259,20.7181,20.7181,0,0,1-22.2368-8.2427,19.1725,19.1725,0,0,1-3.2766-14.5024,17.9885,17.9885,0,0,1,8.13-12.0513L55.8833,23.7472a19.0038,19.0038,0,0,1,5.3-2.3287A20.7182,20.7182,0,0,1,83.42,29.6611a19.1739,19.1739,0,0,1,3.2766,14.5025,18.4,18.4,0,0,1-.6233,2.4357l-.4912,1.4978-1.3356-.98a33.6175,33.6175,0,0,0-10.2037-5.1l-.9694-.2942.0893-.9675a5.8588,5.8588,0,0,0-1.052-3.878,6.2389,6.2389,0,0,0-6.6952-2.485,5.7449,5.7449,0,0,0-1.6021.7041L37.73,51.719a5.4218,5.4218,0,0,0-2.4487,3.63,5.7862,5.7862,0,0,0,.9856,4.3717,6.2437,6.2437,0,0,0,6.6978,2.4864,5.7652,5.7652,0,0,0,1.602-.7041l9.9519-6.3425a18.978,18.978,0,0,1,5.2959-2.3278,20.7181,20.7181,0,0,1,22.2368,8.2427,19.1725,19.1725,0,0,1,3.2766,14.5024,17.9977,17.9977,0,0,1-8.13,12.0532L51.1167,104.2528a19.0038,19.0038,0,0,1-5.3,2.3287" fill="#fff"/></svg>}
+    preserveLogoColor
+  >
+Integrate Mastra with SvelteKit
+  </CardGridItem>
+  <CardGridItem
+    title="Astro"
+    href="/guides/v1/getting-started/astro"
+    logo={<svg width="32" height="32" viewBox="0 0 85 107" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M27.5893 91.1365C22.7555 86.7178 21.3443 77.4335 23.3583 70.7072C26.8503 74.948 31.6888 76.2914 36.7005 77.0497C44.4374 78.2199 52.0358 77.7822 59.2231 74.2459C60.0453 73.841 60.8052 73.3027 61.7036 72.7574C62.378 74.714 62.5535 76.6892 62.3179 78.6996C61.7452 83.5957 59.3086 87.3778 55.4332 90.2448C53.8835 91.3916 52.2437 92.4167 50.6432 93.4979C45.7262 96.8213 44.3959 100.718 46.2435 106.386C46.2874 106.525 46.3267 106.663 46.426 107C43.9155 105.876 42.0817 104.24 40.6844 102.089C39.2086 99.8193 38.5065 97.3081 38.4696 94.5909C38.4511 93.2686 38.4511 91.9345 38.2733 90.6309C37.8391 87.4527 36.3471 86.0297 33.5364 85.9478C30.6518 85.8636 28.37 87.6469 27.7649 90.4554C27.7187 90.6707 27.6517 90.8837 27.5847 91.1341L27.5893 91.1365Z" fill="currentColor"/><path d="M0 69.5866C0 69.5866 14.3139 62.6137 28.6678 62.6137L39.4901 29.1204C39.8953 27.5007 41.0783 26.3999 42.4139 26.3999C43.7495 26.3999 44.9325 27.5007 45.3377 29.1204L56.1601 62.6137C73.1601 62.6137 84.8278 69.5866 84.8278 69.5866C84.8278 69.5866 60.5145 3.35233 60.467 3.21944C59.7692 1.2612 58.5911 0 57.0029 0H27.8274C26.2392 0 25.1087 1.2612 24.3634 3.21944C24.3108 3.34983 0 69.5866 0 69.5866Z" fill="currentColor"/></svg>}
+  >
+    Add AI agents to your Astro site
+  </CardGridItem>
+  <CardGridItem
+    title="Express"
+    href="/guides/v1/getting-started/express"
+    logo={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 861.6297 500" width="32" height="32"><path d="M822.05434 464.78529c-23.57102 8.91305-50.08664-1.16881-61.78139-23.49073l-112.4692-155.53981-16.30803-21.72701-130.51543 177.49688c-11.00437 21.35391-36.14786 31.22309-58.7396 23.05618l168.14149-225.57746L453.94772 35.178469c23.20955-8.38407 49.07747.715704 61.98587 21.727011l116.55901 157.4569L749.74175 57.518928c11.0937-21.002063 36.16603-30.356097 58.30506-21.752557l-60.70782 80.543289-82.23033 107.02469c-9.6735 8.63851-9.6735 23.77308 0 32.41158l156.61338 209.03936ZM39.626477 236.19163l13.700796-67.66046C90.953337 34.743916 244.32044-20.928337 349.83703 61.941017 411.61839 110.45615 427.0318 179.1902 424.01558 256.64057H75.94892C70.325459 394.9777 170.14188 478.51165 297.82 435.87559c42.0737-15.33669 73.74401-50.3044 84.17297-93.75842 6.74816-21.72701 17.89283-25.45896 38.29067-19.1709-6.89256 53.65922-37.9963 101.20027-84.40304 129.00732-77.62638 42.45286-173.75024 30.1679-238.204672-30.44338-31.082401-34.94215-49.844311-79.11186-53.49956-125.76104 0-7.66837-2.556118-14.82549-4.345401-21.727-.170408-12.89987-.255612-25.51006-.255612-37.83054zm36.756986-9.35539H391.14389c-1.96821-100.27654-65.2577-171.413323-149.66074-172.077907C147.52023 53.480264 80.294322 123.05782 76.153409 226.40169Z" fill="currentColor"/></svg>}
+  >
+    Create endpoints that call agents and stream responses
+  </CardGridItem>
+</CardGrid>
+
+Mastra works great with agentic UI frameworks like [AI SDK UI](/guides/v1/build-your-ui/ai-sdk-ui), [CopilotKit](/guides/v1/build-your-ui/copilotkit), and [Assistant UI](/guides/v1/build-your-ui/assistant-ui). Use them with any of the frontend frameworks above to stream agent responses, render tools, and build chat interfaces.
+
+## Start from a template
+Have a use case in mind? Start with a pre-built [template](https://mastra.ai/templates) from Mastra or our community.