@mastra/mcp-docs-server 0.13.39-alpha.0 → 1.0.0-beta.0

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

@@ -0,0 +1,113 @@
+---
+title: "Running Scorers in CI | Evals | Mastra Docs"
+description: "Learn how to run scorer experiments in your CI/CD pipeline using the runEvals function."
+---
+
+# Running Scorers in CI
+
+Running scorers in your CI pipeline provides quantifiable metrics for measuring agent quality over time. The `runEvals` function processes multiple test cases through your agent or workflow and returns aggregate scores.
+
+## Basic Setup
+
+You can use any testing framework that supports ESM modules, such as [Vitest](https://vitest.dev/), [Jest](https://jestjs.io/), or [Mocha](https://mochajs.org/).
+
+## Creating Test Cases
+
+Use `runEvals` to evaluate your agent against multiple test cases. The function accepts an array of data items, each containing an `input` and optional `groundTruth` for scorer validation.
+
+```typescript copy showLineNumbers title="src/mastra/agents/weather-agent.test.ts"
+import { describe, it, expect } from 'vitest';
+import { createScorer, runEvals } from "@mastra/core/evals";
+import { weatherAgent } from "./weather-agent";
+import { locationScorer } from "../scorers/location-scorer";
+
+describe('Weather Agent Tests', () => {
+  it('should correctly extract locations from queries', async () => {
+    const result = await runEvals({
+      data: [
+        {
+          input: 'weather in Berlin',
+          groundTruth: { expectedLocation: 'Berlin', expectedCountry: 'DE' }
+        },
+        {
+          input: 'weather in Berlin, Maryland',
+          groundTruth: { expectedLocation: 'Berlin', expectedCountry: 'US' }
+        },
+        {
+          input: 'weather in Berlin, Russia',
+          groundTruth: { expectedLocation: 'Berlin', expectedCountry: 'RU' }
+        },
+      ],
+      target: weatherAgent,
+      scorers: [locationScorer]
+    });
+
+    // Assert aggregate score meets threshold
+    expect(result.scores['location-accuracy']).toBe(1);
+    expect(result.summary.totalItems).toBe(3);
+  });
+});
+```
+
+View the full example [here](/examples/v1/evals/running-in-ci)
+
+## Understanding Results
+
+The `runEvals` function returns an object with:
+
+- `scores`: Average scores for each scorer across all test cases
+- `summary.totalItems`: Total number of test cases processed
+
+```typescript
+{
+  scores: {
+    'location-accuracy': 1.0,  // Average score across all items
+    'another-scorer': 0.85
+  },
+  summary: {
+    totalItems: 3
+  }
+}
+```
+
+## Multiple Test Scenarios
+
+Create separate test cases for different evaluation scenarios:
+
+```typescript copy showLineNumbers title="src/mastra/agents/weather-agent.test.ts"
+describe('Weather Agent Tests', () => {
+  const locationScorer = createScorer({ /* ... */ });
+
+  it('should handle location disambiguation', async () => {
+    const result = await runEvals({
+      data: [
+        { input: 'weather in Berlin', groundTruth: { /* ... */ } },
+        { input: 'weather in Berlin, Maryland', groundTruth: { /* ... */ } },
+      ],
+      target: weatherAgent,
+      scorers: [locationScorer]
+    });
+
+    expect(result.scores['location-accuracy']).toBe(1);
+  });
+
+  it('should handle typos and misspellings', async () => {
+    const result = await runEvals({
+      data: [
+        { input: 'weather in Berln', groundTruth: { expectedLocation: 'Berlin', expectedCountry: 'DE' } },
+        { input: 'weather in Parris', groundTruth: { expectedLocation: 'Paris', expectedCountry: 'FR' } },
+      ],
+      target: weatherAgent,
+      scorers: [locationScorer]
+    });
+
+    expect(result.scores['location-accuracy']).toBe(1);
+  });
+});
+```
+
+## Next Steps
+
+- Learn about [creating custom scorers](/docs/v1/evals/custom-scorers)
+- Explore [off-the-shelf scorers](/docs/v1/evals/off-the-shelf-scorers)
+- Read the [runEvals API reference](/reference/v1/evals/run-evals)

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

@@ -18,13 +18,14 @@ When creating agents in Mastra, you can specify any AI SDK-supported model.
 import { Agent } from "@mastra/core/agent";
 
 export const weatherAgent = new Agent({
+  id: "weather-agent",
   name: "Weather Agent",
   instructions: "Instructions for the agent...",
   model: "openai/gpt-4-turbo",
 });
 ```
 
-> See [Using AI SDK with Mastra](/models#use-ai-sdk-with-mastra) for more information.
+> See [Using AI SDK with Mastra](/models/v1#use-ai-sdk-with-mastra) for more information.
 
 ## Streaming
 
@@ -55,10 +56,10 @@ The recommended way of using Mastra and AI SDK together is by installing the `@m
 
 ### `chatRoute()`
 
-When setting up a [custom API route](/docs/server-db/custom-api-routes), use the `chatRoute()` utility to create a route handler that automatically formats the agent stream into an AI SDK-compatible format.
+When setting up a [custom API route](/docs/v1/server-db/custom-api-routes), use the `chatRoute()` utility to create a route handler that automatically formats the agent stream into an AI SDK-compatible format.
 
 ```typescript title="src/mastra/index.ts" copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { chatRoute } from "@mastra/ai-sdk";
 
 export const mastra = new Mastra({
@@ -110,7 +111,7 @@ const { error, status, sendMessage, messages, regenerate, stop } = useChat({
 Use the `workflowRoute()` utility to create a route handler that automatically formats the workflow stream into an AI SDK-compatible format.
 
 ```typescript title="src/mastra/index.ts" copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { workflowRoute } from "@mastra/ai-sdk";
 
 export const mastra = new Mastra({
@@ -149,7 +150,7 @@ const { error, status, sendMessage, messages, regenerate, stop } = useChat({
 Use the `networkRoute()` utility to create a route handler that automatically formats the agent network stream into an AI SDK-compatible format.
 
 ```typescript title="src/mastra/index.ts" copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { networkRoute } from "@mastra/ai-sdk";
 
 export const mastra = new Mastra({
@@ -187,7 +188,7 @@ The `@mastra/ai-sdk` package transforms and emits Mastra streams (e.g workflow,
   - `data-tool-network`: Nested network emitted from within an tool stream.
   - `data-tool-agent`: Nested agent emitted from within an tool stream.
 
-Here's an example: For a [nested agent stream within a tool](/docs/streaming/tool-streaming#tool-using-an-agent), `data-tool-agent` UI message parts will be emitted and can be leveraged on the client as documented below:
+Here's an example: For a [nested agent stream within a tool](/docs/v1/streaming/tool-streaming#tool-using-an-agent), `data-tool-agent` UI message parts will be emitted and can be leveraged on the client as documented below:
 
 ```typescript title="app/page.tsx" copy
 "use client";
@@ -276,7 +277,7 @@ export const testTool = createTool({
 });
 ```
 
-For more information about tool streaming see [Tool streaming documentation](/docs/streaming/tool-streaming)
+For more information about tool streaming see [Tool streaming documentation](/docs/v1/streaming/tool-streaming)
 
 ### Stream Transformations
 
@@ -428,7 +429,7 @@ export async function POST(req: Request) {
 }
 ```
 
-> When using `useChat()` with agent memory, refer to the [Agent Memory section](/docs/agents/agent-memory) for key implementation details.
+> When using `useChat()` with agent memory, refer to the [Agent Memory section](/docs/v1/agents/agent-memory) for key implementation details.
 
 ### Using `useCompletion()`
 
@@ -473,7 +474,7 @@ export async function POST(req: Request) {
 
 ### Passing additional data
 
-`sendMessage()` allows you to pass additional data from the frontend to Mastra. This data can then be used on the server as `RuntimeContext`.
+`sendMessage()` allows you to pass additional data from the frontend to Mastra. This data can then be used on the server as `RequestContext`.
 
 ```typescript {16-26} title="app/test/chat-extra.tsx" copy
 "use client";
@@ -518,41 +519,41 @@ export function ChatExtra() {
 
 ```typescript {8,12} title="app/api/chat-extra/route.ts" copy
 import { mastra } from "../../../mastra";
-import { RuntimeContext } from "@mastra/core/runtime-context";
+import { RequestContext } from "@mastra/core/request-context";
 
 export async function POST(req: Request) {
   const { messages, data } = await req.json();
   const myAgent = mastra.getAgent("weatherAgent");
 
-  const runtimeContext = new RuntimeContext();
+  const requestContext = new RequestContext();
 
   if (data) {
     for (const [key, value] of Object.entries(data)) {
-      runtimeContext.set(key, value);
+      requestContext.set(key, value);
     }
   }
 
   const stream = await myAgent.stream(messages, {
-    runtimeContext,
+    requestContext,
     format: "aisdk",
   });
   return stream.toUIMessageStreamResponse();
 }
 ```
 
-### Handling `runtimeContext` with `server.middleware`
+### Handling `requestContext` with `server.middleware`
 
-You can also populate the `RuntimeContext` by reading custom data in a server middleware:
+You can also populate the `RequestContext` by reading custom data in a server middleware:
 
 ```typescript {8,17} title="mastra/index.ts" copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
   agents: { weatherAgent },
   server: {
     middleware: [
       async (c, next) => {
-        const runtimeContext = c.get("runtimeContext");
+        const requestContext = c.get("requestContext");
 
         if (c.req.method === "POST") {
           try {
@@ -561,7 +562,7 @@ export const mastra = new Mastra({
 
             if (body?.data) {
               for (const [key, value] of Object.entries(body.data)) {
-                runtimeContext.set(key, value);
+                requestContext.set(key, value);
               }
             }
           } catch {}
@@ -573,7 +574,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/server-db/runtime-context) for more details.
+> You can then access this data in your tools via the `requestContext` parameter. See the [Request Context documentation](/docs/v1/server-db/request-context) for more details.
 
 ## Migrating from AI SDK v4 to v5
 
@@ -629,7 +630,7 @@ const weatherTool = createTool({
     temperature: z.number(),
     conditions: z.string(),
   }),
-  execute: async ({ context }) => {
+  execute: async (inputData) => {
     return {
       temperature: 72,
       conditions: "sunny",
@@ -668,7 +669,7 @@ const tools = {
     outputSchema: z.object({
       result: z.number(),
     }),
-    execute: async ({ context }) => {
+    execute: async (inputData) => {
       // implementation...
       return { result: 0 };
     },

package/.docs/raw/frameworks/agentic-uis/copilotkit.mdx

@@ -81,7 +81,7 @@ export function CopilotKitComponent({ runtimeUrl }: { runtimeUrl: string }) {
 
 <StepItem>
 
-If you have not yet set up your Mastra server, follow the [getting started guide](/docs/getting-started/installation) to set up a new Mastra project.
+If you have not yet set up your Mastra server, follow the [getting started guide](/docs/v1/getting-started/installation) to set up a new Mastra project.
 
 In your Mastra server, install additional packages for CopilotKit integration:
 
@@ -116,11 +116,11 @@ pnpm add @copilotkit/runtime @ag-ui/mastra
 Configure your Mastra instance to include CopilotKit's runtime endpoint:
 
 ```typescript title="src/mastra/index.ts" copy {2,5-8,12-28}
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { registerCopilotKit } from "@ag-ui/mastra/copilotkit";
 import { weatherAgent } from "./agents/weather-agent";
 
-type WeatherRuntimeContext = {
+type WeatherRequestContext = {
   "user-id": string;
   "temperature-scale": "celsius" | "fahrenheit";
 };
@@ -134,15 +134,15 @@ export const mastra = new Mastra({
       allowHeaders: ["*"],
     },
     apiRoutes: [
-      registerCopilotKit<WeatherRuntimeContext>({
+      registerCopilotKit<WeatherRequestContext>({
         path: "/copilotkit",
         resourceId: "weatherAgent",
-        setContext: (c, runtimeContext) => {
-          runtimeContext.set(
+        setContext: (c, requestContext) => {
+          requestContext.set(
             "user-id",
             c.req.header("X-User-ID") || "anonymous",
           );
-          runtimeContext.set("temperature-scale", "celsius");
+          requestContext.set("temperature-scale", "celsius");
         },
       }),
     ],
@@ -379,4 +379,4 @@ Start building the future!
 
 - [CopilotKit Documentation](https://docs.copilotkit.ai) - Complete CopilotKit reference
 - [React Hooks with CopilotKit](https://docs.copilotkit.ai/reference/hooks/useCoAgent) - Advanced React integration patterns
-- [Next.js Integration with Mastra](/docs/frameworks/web-frameworks/next-js) - Full-stack Next.js setup guide
+- [Next.js Integration with Mastra](/docs/v1/frameworks/web-frameworks/next-js) - Full-stack Next.js setup guide

package/.docs/raw/frameworks/agentic-uis/openrouter.mdx

@@ -65,6 +65,7 @@ const openrouter = createOpenRouter({
 });
 
 export const assistant = new Agent({
+  id: "assistant",
   name: "assistant",
   instructions: "You are a helpful assistant.",
   model: openrouter("anthropic/claude-sonnet-4"),
@@ -119,6 +120,7 @@ const openrouter = createOpenRouter({
 });
 
 export const assistant = new Agent({
+  id: "assistant",
   name: "assistant",
   instructions: "You are a helpful assistant.",
   model: openrouter("anthropic/claude-sonnet-4"),
@@ -138,6 +140,7 @@ const openrouter = createOpenRouter({
 });
 
 export const assistant = new Agent({
+  id: "assistant",
   name: "assistant",
   instructions: "You are a helpful assistant.",
   model: openrouter("anthropic/claude-sonnet-4", {

package/.docs/raw/frameworks/servers/express.mdx

@@ -18,12 +18,12 @@ In this guide you'll learn how to install the necessary Mastra dependencies, cre
 ## Prerequisites
 
 - An existing Express app set up with TypeScript
-- Node.js `v20.0` or higher
-- An API key from a supported [Model Provider](/models)
+- Node.js `v22.13.0` or later
+- An API key from a supported [Model Provider](/models/v1)
 
 ## Adding Mastra
 
-First, install the necessary Mastra dependencies to run an Agent. This guide uses OpenAI as its model but you can use any supported [model provider](/models).
+First, install the necessary Mastra dependencies to run an Agent. This guide uses OpenAI as its model but you can use any supported [model provider](/models/v1).
 
 ```bash copy
 npm install mastra@latest @mastra/core@latest @mastra/libsql@latest zod@^3.0.0 @ai-sdk/openai@^1.0.0
@@ -44,7 +44,7 @@ Each LLM provider uses a different env var. See [Model Capabilities](https://sdk
 Create a Mastra configuration file at `src/mastra/index.ts`:
 
 ```ts title="src/mastra/index.ts" copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({});
 ```
@@ -80,13 +80,14 @@ import { Agent } from "@mastra/core/agent";
 import { weatherTool } from "../tools/weather-tool";
 
 export const weatherAgent = new Agent({
+  id: "weather-agent",
   name: "Weather Agent",
   instructions: `
       You are a helpful weather assistant that provides accurate weather information.
 
       Your primary function is to help users get weather details for specific locations. When responding:
       - Always ask for a location if none is provided
-      - If the location name isn’t in English, please translate it
+      - If the location name isn't in English, please translate it
       - If giving a location with multiple parts (e.g. "New York, NY"), use the most relevant part (e.g. "New York")
       - Include relevant details like humidity, wind conditions, and precipitation
       - Keep responses concise but informative
@@ -101,7 +102,7 @@ export const weatherAgent = new Agent({
 Lastly, add the `weatherAgent` to `src/mastra/index.ts`:
 
 ```ts title="src/mastra/index.ts" copy {2, 5}
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { weatherAgent } from "./agents/weather-agent";
 
 export const mastra = new Mastra({
@@ -168,11 +169,11 @@ app.listen(port, () => {
 });
 ```
 
-By importing the `src/mastra/index.ts` file you can use methods like [`.getAgent()`](/reference/core/getAgent) to get programmatic access. With [`.generate()`](/reference/agents/generate) you then can interact with the respective agent.
+By importing the `src/mastra/index.ts` file you can use methods like [`.getAgent()`](/reference/v1/core/getAgent) to get programmatic access. With [`.generate()`](/reference/v1/agents/generate) you then can interact with the respective agent.
 
 :::note
 
-Read the [Agent reference docs](/reference/agents/agent) to learn more.
+Read the [Agent reference docs](/reference/v1/agents/agent) to learn more.
 
 :::
 
@@ -190,7 +191,7 @@ The weather in London is currently sunny. If you need more details like humidity
 
 ## Running the Agent Server
 
-In production it's not necessary to run Mastra alongside your Express server. But for development Mastra offers a [Local Development Environment](/docs/getting-started/studio) which you can use to improve and debug your agent.
+In production it's not necessary to run Mastra alongside your Express server. But for development Mastra offers a [Local Development Environment](/docs/v1/getting-started/studio) which you can use to improve and debug your agent.
 
 Add a script to your `package.json`:
 

package/.docs/raw/frameworks/web-frameworks/astro.mdx

@@ -78,7 +78,7 @@ To integrate Mastra into your project, you have two options:
   npx mastra@latest init --default
   ```
 
-  > See [mastra init](/reference/cli/create-mastra) for more information.
+  > See [mastra init](/reference/v1/cli/create-mastra) for more information.
 
 - Use the Interactive CLI
 
@@ -175,7 +175,7 @@ mastra dev:mastra
 </TabItem>
 </Tabs>
 
-> Once running, your agents are available locally. See [Local Development Environment](/docs/getting-started/studio) for more information.
+> Once running, your agents are available locally. See [Local Development Environment](/docs/v1/getting-started/studio) for more information.
 
 </StepItem>
 
@@ -215,7 +215,7 @@ export const server = {
       city: z.string(),
     }),
     handler: async (input) => {
-      const city = input.city;
+      const city = inputData.city;
       const agent = mastra.getAgent("weatherAgent");
 
       const result = await agent.generate(
@@ -371,7 +371,7 @@ To integrate Mastra into your project, you have two options:
   npx mastra@latest init --default
   ```
 
-  > See [mastra init](/reference/cli/create-mastra) for more information.
+  > See [mastra init](/reference/v1/cli/create-mastra) for more information.
 
 - Use the Interactive CLI
 
@@ -468,7 +468,7 @@ mastra dev:mastra
 </TabItem>
 </Tabs>
 
-> Once running, your agents are available locally. See [Local Development Environment](/docs/getting-started/studio) for more information.
+> Once running, your agents are available locally. See [Local Development Environment](/docs/v1/getting-started/studio) for more information.
 
 </StepItem>
 
@@ -598,5 +598,5 @@ Let me know if you need more information!
 
 ## Next Steps
 
-- [Deployment | With Astro on Vercel](/docs/deployment/web-framework#with-astro-on-vercel)
+- [Deployment | With Astro on Vercel](/docs/v1/deployment/web-framework#with-astro-on-vercel)
 - [Monorepo Deployment](../../deployment/monorepo)

package/.docs/raw/frameworks/web-frameworks/next-js.mdx

@@ -41,7 +41,7 @@ To integrate Mastra into your project, you have two options:
   npx mastra@latest init --dir . --components agents,tools --example --llm openai
   ```
 
-  > See [mastra init](/reference/cli/create-mastra) for more information.
+  > See [mastra init](/reference/v1/cli/create-mastra) for more information.
 
 - Use the Interactive CLI
 
@@ -228,7 +228,7 @@ To integrate Mastra into your project, you have two options:
   npx mastra@latest init --dir . --components agents,tools --example --llm openai
   ```
 
-  > See [mastra init](/reference/cli/create-mastra) for more information.
+  > See [mastra init](/reference/v1/cli/create-mastra) for more information.
 
 - Use the Interactive CLI
 
@@ -375,5 +375,5 @@ Let me know if you need more information!
 
 ## Next Steps
 
-- [Deployment | With Next.js on Vercel](/docs/deployment/web-framework#with-nextjs-on-vercel)
+- [Deployment | With Next.js on Vercel](/docs/v1/deployment/web-framework#with-nextjs-on-vercel)
 - [Monorepo Deployment](../../deployment/monorepo)

package/.docs/raw/frameworks/web-frameworks/sveltekit.mdx

@@ -66,7 +66,7 @@ To integrate Mastra into your project, you have two options:
   npx mastra@latest init --default
   ```
 
-  > See [mastra init](/reference/cli/create-mastra) for more information.
+  > See [mastra init](/reference/v1/cli/create-mastra) for more information.
 
 - Use the Interactive CLI
 
@@ -161,7 +161,7 @@ Start the Mastra Dev Server to expose your agents as REST endpoints:
   </TabItem>
 </Tabs>
 
-> Once running, your agents are available locally. See [Local Development Environment](/docs/getting-started/studio) for more information.
+> Once running, your agents are available locally. See [Local Development Environment](/docs/v1/getting-started/studio) for more information.
 
 </StepItem>
 
@@ -297,7 +297,7 @@ To integrate Mastra into your project, you have two options:
   npx mastra@latest init --default
   ```
 
-  > See [mastra init](/reference/cli/create-mastra) for more information.
+  > See [mastra init](/reference/v1/cli/create-mastra) for more information.
 
 - Use the Interactive CLI
 
@@ -392,7 +392,7 @@ Start the Mastra Dev Server to expose your agents as REST endpoints:
   </TabItem>
 </Tabs>
 
-> Once running, your agents are available locally. See [Local Development Environment](/docs/getting-started/studio) for more information.
+> Once running, your agents are available locally. See [Local Development Environment](/docs/v1/getting-started/studio) for more information.
 
 </StepItem>
 

package/.docs/raw/frameworks/web-frameworks/vite-react.mdx

@@ -69,7 +69,7 @@ Run the following command to quickly scaffold the default Weather agent with sen
 npx mastra@latest init --dir . --components agents,tools --example --llm openai
 ```
 
-> See [mastra init](/reference/cli/create-mastra) for more information.
+> See [mastra init](/reference/v1/cli/create-mastra) for more information.
 
 ### 2. Use the Interactive CLI
 
@@ -164,7 +164,7 @@ mastra dev:mastra
 </TabItem>
 </Tabs>
 
-> Once running, your agents are available locally. See [Local Development Environment](/docs/getting-started/studio) for more information.
+> Once running, your agents are available locally. See [Local Development Environment](/docs/v1/getting-started/studio) for more information.
 
 ## Start Vite Dev Server
 

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

@@ -13,12 +13,12 @@ import { VideoPlayer } from "@site/src/components/video-player";
 
 The `create mastra` CLI command is the quickest way to start a new Mastra project. It walks you through setup and creates example agents, workflows, and tools for you to learn from or adapt.
 
-For more control over setup, or to add Mastra to an existing project, see the [manual installation guide](#install-manually). You can also use [`mastra init`](/reference/cli/mastra#mastra-init) for existing projects.
+For more control over setup, or to add Mastra to an existing project, see the [manual installation guide](#install-manually). You can also use [`mastra init`](/reference/v1/cli/mastra#mastra-init) for existing projects.
 
 ## Before you start
 
-- You'll need an API key from a [model provider](/models) to complete setup. We suggest starting with [OpenAI](https://platform.openai.com/api-keys), but if you need a provider that doesn't require a credit card, Google's [Gemini](https://aistudio.google.com/app/api-keys) is also an option.
-- [Install](https://nodejs.org/en/download) Node.js 20 or later.
+- You'll need an API key from a [model provider](/models/v1) to complete setup. We suggest starting with [OpenAI](https://platform.openai.com/api-keys), but if you need a provider that doesn't require a credit card, Google's [Gemini](https://aistudio.google.com/app/api-keys) is also an option.
+- [Install](https://nodejs.org/en/download) Node.js 22.13.0 or later.
 
 ## Install with `create mastra`
 
@@ -59,7 +59,7 @@ bun create mastra@latest
 
 :::note
 
-You can use flags with `create mastra` like `--no-example` to skip the example weather agent or `--template` to start from a specific [template](/docs/getting-started/templates). Read the [CLI reference](/reference/cli/create-mastra) for all options.
+You can use flags with `create mastra` like `--no-example` to skip the example weather agent or `--template` to start from a specific [template](/docs/v1/getting-started/templates). Read the [CLI reference](/reference/v1/cli/create-mastra) for all options.
 
 :::
 
@@ -77,13 +77,13 @@ If you encounter an error, your API key may not be configured correctly. Double-
 
 :::
 
-[Studio](/docs/getting-started/studio) lets you rapidly build and prototype agents without needing to build a UI. Once you're ready, you can integrate your Mastra agent into your application using the guides below.
+[Studio](/docs/v1/getting-started/studio) lets you rapidly build and prototype agents without needing to build a UI. Once you're ready, you can integrate your Mastra agent into your application using the guides below.
 
 ### Next steps
 
-- Read more about [Mastra's features](/docs#why-mastra).
-- Integrate Mastra with your frontend framework: [Next.js](/docs/frameworks/web-frameworks/next-js), [React](/docs/frameworks/web-frameworks/vite-react), or [Astro](/docs/frameworks/web-frameworks/astro).
-- Build an agent from scratch following one of our [guides](/guides).
+- 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).
+- 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)!
 
 ## Install manually
@@ -206,7 +206,7 @@ GOOGLE_GENERATIVE_AI_API_KEY=<your-api-key>
 
 :::note
 
-This guide uses Google Gemini, but you can use any supported [model provider](/models), including OpenAI, Anthropic, and more.
+This guide uses Google Gemini, but you can use any supported [model provider](/models/v1), including OpenAI, Anthropic, and more.
 
 :::
 
@@ -245,7 +245,7 @@ export const weatherTool = createTool({
 
 :::info
 
-We've shortened and simplified the `weatherTool` example here. You can see the complete weather tool under [Giving an Agent a Tool](/docs/agents/using-tools).
+We've shortened and simplified the `weatherTool` example here. You can see the complete weather tool under [Giving an Agent a Tool](/docs/v1/agents/using-tools).
 
 :::
 
@@ -266,6 +266,7 @@ import { Agent } from "@mastra/core/agent";
 import { weatherTool } from "../tools/weather-tool";
 
 export const weatherAgent = new Agent({
+  id: "weather-agent",
   name: "Weather Agent",
   instructions: `
       You are a helpful weather assistant that provides accurate weather information.
@@ -297,7 +298,7 @@ touch src/mastra/index.ts
 Add the following code:
 
 ```ts title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { weatherAgent } from "./agents/weather-agent";
 
 export const mastra = new Mastra({
@@ -309,7 +310,7 @@ export const mastra = new Mastra({
 
 <StepItem>
 
-You can now launch [Studio](/docs/getting-started/studio) and test your agent.
+You can now launch [Studio](/docs/v1/getting-started/studio) and test your agent.
 
 <Tabs>
 <TabItem value="npm" label="npm">

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

@@ -19,7 +19,7 @@ In this guide you'll learn how to add Mastra's MCP server to your AI tooling.
 
 ### create-mastra
 
-During the interactive [create-mastra](/reference/cli/create-mastra) wizard, choose one of your tools in the MCP step.
+During the interactive [create-mastra](/reference/v1/cli/create-mastra) wizard, choose one of your tools in the MCP step.
 
 ### Manual setup