@mastra/mcp-docs-server 1.0.0-beta.1 → 1.0.0-beta.3

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

@@ -1,6 +1,6 @@
 ---
-title: "Integrate CopilotKit with Mastra | Frameworks | Mastra Docs"
-description: "Learn how Mastra leverages the CopilotKit's AGUI library and how you can leverage it to build user experiences"
+title: "Using CopilotKit | Frameworks"
+description: "Learn how to integrate CopilotKit with Mastra"
 ---
 
 import Tabs from "@theme/Tabs";
@@ -8,125 +8,99 @@ import TabItem from "@theme/TabItem";
 import Steps from "@site/src/components/Steps";
 import StepItem from "@site/src/components/StepItem";
 
-# Integrate CopilotKit with Mastra
+# Using CopilotKit
 
-CopilotKit provides React components to quickly integrate customizable AI copilots into your application. Combined with Mastra, you can build sophisticated AI apps featuring bidirectional state synchronization and interactive UIs.
+[CopilotKit](https://www.copilotkit.ai/) provides React components to quickly integrate customizable AI copilots into your application. Combined with Mastra, you can build sophisticated AI apps featuring bidirectional state synchronization and interactive UIs.
 
 Visit the [CopilotKit documentation](https://docs.copilotkit.ai/) to learn more about CopilotKit concepts, components, and advanced usage patterns.
 
-This guide shows two distinct integration approaches:
+:::info
 
-1. Integrate CopilotKit in your Mastra server with a separate React frontend.
-2. Integrate CopilotKit in your Next.js app
+For a full-stack integration approach where Mastra runs directly in your Next.js API routes, see the [CopilotKit Quickstart](https://docs.copilotkit.ai/mastra/quickstart) guide.
 
-<Tabs>
-<TabItem value="mastra-server" label="Mastra Server">
+:::
 
-  <Steps>
+:::tip
 
-  <StepItem>
+Visit Mastra's [**"UI Dojo"**](https://ui-dojo.mastra.ai/) to see real-world examples of CopilotKit integrated with Mastra.
 
-In your React frontend, install the required CopilotKit packages:
+:::
 
-<Tabs>
-<TabItem value="npm" label="npm">
+## Integration Guide
 
-```bash copy
-npm install @copilotkit/react-core @copilotkit/react-ui
-```
-
-</TabItem>
-<TabItem value="yarn" label="yarn">
-
-```bash copy
-yarn add @copilotkit/react-core @copilotkit/react-ui
-```
+Run Mastra as a standalone server and connect your Next.js frontend (with CopilotKit) to its API endpoints.
 
-</TabItem>
-<TabItem value="pnpm" label="pnpm">
-
-```bash copy
-pnpm add @copilotkit/react-core @copilotkit/react-ui
-```
-
-</TabItem>
-</Tabs>
-
-</StepItem>
+<Steps>
 
 <StepItem>
 
-Create a CopilotKit component in your React frontend:
+Set up your directory structure. A possible directory structure could look like this:
 
-```tsx title="components/copilotkit-component.tsx" copy
-import { CopilotChat } from "@copilotkit/react-ui";
-import { CopilotKit } from "@copilotkit/react-core";
-import "@copilotkit/react-ui/styles.css";
-
-export function CopilotKitComponent({ runtimeUrl }: { runtimeUrl: string }) {
-  return (
-    <CopilotKit runtimeUrl={runtimeUrl} agent="weatherAgent">
-      <CopilotChat
-        labels={{
-          title: "Your Assistant",
-          initial: "Hi! 👋 How can I assist you today?",
-        }}
-      />
-    </CopilotKit>
-  );
-}
+```shell
+project-root
+├── mastra-server
+│   ├── src
+│   │   └── mastra
+│   └── package.json
+└── my-copilot-app
+    └── package.json
 ```
 
-</StepItem>
-
-<StepItem>
+Bootstrap your Mastra server:
 
-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.
+```bash copy
+npx create-mastra@latest
+```
 
-In your Mastra server, install additional packages for CopilotKit integration:
+This command will launch an interactive wizard to help you scaffold a new Mastra project, including prompting you for a project name and setting up basic configurations. Follow the prompts to create your server project.
 
-<Tabs>
-<TabItem value="npm" label="npm">
+Navigate to your newly created Mastra server directory:
 
 ```bash copy
-npm install @copilotkit/runtime @ag-ui/mastra@beta
+cd mastra-server # Replace with the actual directory name you provided
 ```
 
-</TabItem>
-<TabItem value="yarn" label="yarn">
+You now have a basic Mastra server project ready. You should have the following files and folders:
 
-```bash copy
-yarn add @copilotkit/runtime @ag-ui/mastra@beta
+```shell
+src
+└── mastra
+    ├── agents
+    │   └── weather-agent.ts
+    ├── scorers
+    │   └── weather-scorer.ts
+    ├── tools
+    │   └── weather-tool.ts
+    ├── workflows
+    │   └── weather-workflow.ts
+    └── index.ts
 ```
 
-</TabItem>
-<TabItem value="pnpm" label="pnpm">
+:::note
 
-```bash copy
-pnpm add @copilotkit/runtime @ag-ui/mastra@beta
-```
+Ensure that you have set the appropriate environment variables for your LLM provider in the `.env` file.
 
-</TabItem>
-</Tabs>
+:::
 
 </StepItem>
 
 <StepItem>
 
-Configure your Mastra instance to include CopilotKit's runtime endpoint:
+Create a chat route for the CopilotKit frontend by using the `registerCopilotKit()` helper from `@ag-ui/mastra`. Add it to your Mastra project (and its peer dependencies):
+
+```bash copy
+npm install --legacy-peer-deps @ag-ui/mastra @copilotkit/runtime @ag-ui/core @ag-ui/client @ag-ui/encoder @ag-ui/langgraph @ag-ui/proto
+```
 
-```typescript title="src/mastra/index.ts" copy {2,5-8,12-28}
-import { Mastra } from "@mastra/core";
-import { registerCopilotKit } from "@ag-ui/mastra/copilotkit";
-import { weatherAgent } from "./agents/weather-agent";
+In your `src/mastra/index.ts` file, register the chat route:
 
-type WeatherRequestContext = {
-  "user-id": string;
-  "temperature-scale": "celsius" | "fahrenheit";
-};
+```typescript copy title="src/mastra/index.ts" {2,7-19}
+import { Mastra } from '@mastra/core/mastra';
+import { registerCopilotKit } from '@ag-ui/mastra/copilotkit';
+// Rest of the imports...
 
 export const mastra = new Mastra({
-  agents: { weatherAgent },
+  // Rest of the configuration...
   server: {
     cors: {
       origin: "*",
@@ -134,99 +108,78 @@ export const mastra = new Mastra({
       allowHeaders: ["*"],
     },
     apiRoutes: [
-      registerCopilotKit<WeatherRequestContext>({
-        path: "/copilotkit",
-        resourceId: "weatherAgent",
-        setContext: (c, requestContext) => {
-          requestContext.set(
-            "user-id",
-            c.req.header("X-User-ID") || "anonymous",
-          );
-          requestContext.set("temperature-scale", "celsius");
-        },
-      }),
-    ],
-  },
+      registerCopilotKit({
+        path: '/chat',
+        resourceId: 'weatherAgent'
+      })
+    ]
+  }
 });
 ```
 
+This will make the `weatherAgent` available at `/chat` in a CopilotKit-compatible format. You have to add the CORS configuration to allow the CopilotKit frontend to access the Mastra server. For production deployments, make sure to restrict the CORS origins to only your frontend domain.
+
 </StepItem>
 
 <StepItem>
 
-Use the component in your React app with your Mastra server URL:
-
-```tsx title="App.tsx" copy {5}
-import { CopilotKitComponent } from "./components/copilotkit-component";
-
-function App() {
-  return <CopilotKitComponent runtimeUrl="http://localhost:4111/copilotkit" />;
-}
+Run the Mastra server using the following command:
 
-export default App;
+```bash copy
+npm run dev
 ```
 
-Now start both the Mastra server and your frontend.
+By default, the Mastra server will run on `http://localhost:4111`. Keep this server running for the next steps where we'll set up the CopilotKit frontend to connect to it.
 
 </StepItem>
 
-  </Steps>
- </TabItem>
-
-  <TabItem value="nextjs" label="Next.js">
-
-  <Steps>
-
 <StepItem>
 
-In your Next.js app, install the required packages:
-
-<Tabs>
-<TabItem value="npm" label="npm">
+Go up one directory to your project root.
 
 ```bash copy
-npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @ag-ui/mastra@beta
+cd ..
 ```
 
-</TabItem>
-<TabItem value="yarn" label="yarn">
+Create a new Next.js project with the name `my-copilot-app`:
 
 ```bash copy
-yarn add @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @ag-ui/mastra@beta
+npx create-next-app@latest my-copilot-app
 ```
 
-</TabItem>
-<TabItem value="pnpm" label="pnpm">
+Navigate to your newly created Next.js project directory:
 
 ```bash copy
-pnpm add @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @ag-ui/mastra@beta
+cd my-copilot-app
 ```
 
-</TabItem>
-</Tabs>
-
 </StepItem>
 
 <StepItem>
 
-Create a CopilotKit component:
+Install the CopilotKit UI packages which you'll use to display a chat interface:
+
+```bash copy
+npm install @copilotkit/react-ui @copilotkit/react-core
+```
+
+Open the home route of the Next.js app (usually `app/page.tsx` or `src/app/page.tsx`) and replace the existing contents with the following code to set up a basic CopilotKit chat interface:
 
-```tsx title="components/copilotkit-component.tsx" copy
-'use client';
+```typescript copy title="app/page.tsx"
 import { CopilotChat } from "@copilotkit/react-ui";
 import { CopilotKit } from "@copilotkit/react-core";
 import "@copilotkit/react-ui/styles.css";
 
-export function CopilotKitComponent({ runtimeUrl }: { runtimeUrl: string}) {
+export default function Home() {
   return (
     <CopilotKit
-      runtimeUrl={runtimeUrl}
+      runtimeUrl="http://localhost:4111/chat"
       agent="weatherAgent"
     >
       <CopilotChat
         labels={{
-          title: "Your Assistant",
-          initial: "Hi! 👋 How can I assist you today?",
+          title: "Weather Agent",
+          initial: "Hi! 👋 Ask me about the weather, forecasts, and climate.",
         }}
       />
     </CopilotKit>
@@ -238,145 +191,16 @@ export function CopilotKitComponent({ runtimeUrl }: { runtimeUrl: string}) {
 
 <StepItem>
 
-There are two approaches for the API route determined by how you're integrating Mastra in your Next.js application.
-
-1. For a full-stack Next.js app with an instance of Mastra integrated into the app.
-2. For a Next.js app with a separate Mastra server and the Mastra Client SDK.
-
-<Tabs>
-  <TabItem value="mastra-instance" label="With a Mastra instance">
-
-Create an API route that connects to local Mastra agents.
-
-```typescript title="app/api/copilotkit/route.ts" copy {1-7,11-26}
-import { mastra } from "../../mastra";
-import {
-  CopilotRuntime,
-  ExperimentalEmptyAdapter,
-  copilotRuntimeNextJSAppRouterEndpoint,
-} from "@copilotkit/runtime";
-import { MastraAgent } from "@ag-ui/mastra";
-import { NextRequest } from "next/server";
-
-export const POST = async (req: NextRequest) => {
-  const mastraAgents = MastraAgent.getLocalAgents({
-    mastra,
-    agentId: "weatherAgent",
-  });
-
-  const runtime = new CopilotRuntime({
-    agents: mastraAgents,
-  });
-
-  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
-    runtime,
-    serviceAdapter: new ExperimentalEmptyAdapter(),
-    endpoint: "/api/copilotkit",
-  });
-
-  return handleRequest(req);
-};
-```
-
-  </TabItem>
-  <TabItem value="mastra-client" label="With the Mastra Client SDK">
-
-Install the Mastra Client SDK.
-
-<Tabs>
-<TabItem value="npm" label="npm">
-
-```bash copy
-npm install @mastra/client-js@beta
-```
-
-</TabItem>
-<TabItem value="yarn" label="yarn">
-
-```bash copy
-yarn add @mastra/client-js@beta
-```
-
-</TabItem>
-<TabItem value="pnpm" label="pnpm">
+You're ready to connect the pieces! Make sure both the Mastra server and the CopilotKit frontend are running. Start the Next.js development server:
 
 ```bash copy
-pnpm add @mastra/client-js@beta
+npm run dev
 ```
 
-</TabItem>
-</Tabs>
-
-Create an API route that connects to remote Mastra agents:
-
-```typescript title="app/api/copilotkit/route.ts" copy {1-7,12-26}
-import { MastraClient } from "@mastra/client-js";
-import {
-  CopilotRuntime,
-  ExperimentalEmptyAdapter,
-  copilotRuntimeNextJSAppRouterEndpoint,
-} from "@copilotkit/runtime";
-import { MastraAgent } from "@ag-ui/mastra";
-import { NextRequest } from "next/server";
-
-export const POST = async (req: NextRequest) => {
-  const baseUrl = process.env.MASTRA_BASE_URL || "http://localhost:4111";
-  const mastraClient = new MastraClient({ baseUrl });
-
-  const mastraAgents = await MastraAgent.getRemoteAgents({ mastraClient });
-
-  const runtime = new CopilotRuntime({
-    agents: mastraAgents,
-  });
-
-  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
-    runtime,
-    serviceAdapter: new ExperimentalEmptyAdapter(),
-    endpoint: "/api/copilotkit",
-  });
-
-  return handleRequest(req);
-};
-```
-
-  </TabItem>
-</Tabs>
+You should now be able to chat with your agent in the browser.
 
 </StepItem>
 
-<StepItem>
-
-Use the component with the local API endpoint:
-
-```tsx title="App.tsx" copy {5}
-import { CopilotKitComponent } from "./components/copilotkit-component";
-
-function App() {
-  return <CopilotKitComponent runtimeUrl="/api/copilotkit" />;
-}
-
-export default App;
-```
-
-</StepItem>
-
-  </Steps>
-  </TabItem>
-</Tabs>
-
-Start building the future!
-
-<br />
-
-<img
-  className="rounded-lg"
-  src="/img/copilotkit/cpkoutput.jpg"
-  alt="CopilotKit output"
-  style={{ maxWidth: "700px", width: "100%" }}
-/>
-
-## Next Steps
+</Steps>
 
-- [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/v1/frameworks/web-frameworks/next-js) - Full-stack Next.js setup guide
+Congratulations! You have successfully integrated Mastra with CopilotKit using a separate server approach. Your CopilotKit frontend now communicates with a standalone Mastra agent server.

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

@@ -1,14 +1,14 @@
 ---
-title: "Use OpenRouter with Mastra | Frameworks | Mastra Docs"
+title: "Using OpenRouter | Frameworks"
 description: "Learn how to integrate OpenRouter with Mastra"
 ---
 
 import Steps from "@site/src/components/Steps";
 import StepItem from "@site/src/components/StepItem";
 
-# Use OpenRouter with Mastra
+# Using OpenRouter
 
-Integrate OpenRouter with Mastra to leverage the numerous models available on OpenRouter.
+Integrate [OpenRouter](https://openrouter.ai/) with Mastra to leverage the numerous models available on OpenRouter.
 
 <Steps>
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Integrate Mastra in your Express project | Frameworks | Mastra Docs"
+title: "Integrate Mastra in your Express project | Frameworks"
 description: A step-by-step guide to integrating Mastra with an Express backend.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Integrate Mastra in your Astro project | Frameworks | Mastra Docs"
+title: "Integrate Mastra in your Astro project | Frameworks"
 description: A step-by-step guide to integrating Mastra with Astro.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Integrate Mastra in your Next.js project | Frameworks | Mastra Docs"
+title: "Integrate Mastra in your Next.js project | Frameworks"
 description: A step-by-step guide to integrating Mastra with Next.js.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Integrate Mastra in your SvelteKit project | Frameworks | Mastra Docs"
+title: "Integrate Mastra in your SvelteKit project | Frameworks"
 description: A step-by-step guide to integrating Mastra with SvelteKit.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Integrate Mastra in your Vite/React project | Frameworks | Mastra Docs"
+title: "Integrate Mastra in your Vite/React project | Frameworks"
 description: A step-by-step guide to integrating Mastra with Vite and React.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Mastra Docs Server | Getting Started | Mastra Docs"
+title: "Mastra Docs Server | Getting Started"
 description: "Learn how to use the Mastra MCP documentation server in your IDE to turn it into an agentic Mastra expert."
 ---
 
@@ -31,7 +31,7 @@ If there are no specific instructions for your tool below, you may be able to ad
     "mastra": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@mastra/mcp-docs-server"]
+      "args": ["-y", "@mastra/mcp-docs-server@beta"]
     }
   }
 }
@@ -42,7 +42,7 @@ If there are no specific instructions for your tool below, you may be able to ad
 Install using the terminal command:
 
 ```bash copy
-claude mcp add mastra -- npx -y @mastra/mcp-docs-server
+claude mcp add mastra -- npx -y @mastra/mcp-docs-server@beta
 ```
 
 [More info on using MCP servers with Claude Code](https://docs.claude.com/en/docs/claude-code/mcp)
@@ -52,7 +52,7 @@ claude mcp add mastra -- npx -y @mastra/mcp-docs-server
 1. Register it from the terminal:
 
    ```bash copy
-   codex mcp add mastra-docs -- npx -y @mastra/mcp-docs-server
+   codex mcp add mastra-docs -- npx -y @mastra/mcp-docs-server@beta
    ```
 
 2. Run `codex mcp list` to confirm the server shows as `enabled`.
@@ -86,7 +86,7 @@ If you followed the automatic installation, you'll see a popup when you open cur
        "mastra": {
          "type": "stdio",
          "command": "npx",
-         "args": ["-y", "@mastra/mcp-docs-server"]
+         "args": ["-y", "@mastra/mcp-docs-server@beta"]
        }
      }
    }
@@ -135,7 +135,7 @@ After starting the MCP server, click the tools button in the Copilot pane to see
      "mcpServers": {
        "mastra": {
          "command": "npx",
-         "args": ["-y", "@mastra/mcp-docs-server"]
+         "args": ["-y", "@mastra/mcp-docs-server@beta"]
        }
      }
    }

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

@@ -1,5 +1,5 @@
 ---
-title: "Project Structure | Getting Started | Mastra Docs"
+title: "Project Structure | Getting Started"
 description: Guide on organizing folders and files in Mastra, including best practices and recommended structures.
 ---
 

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

@@ -0,0 +1,27 @@
+---
+title: "Quickstart | Getting Started"
+description: Choose how to get started with Mastra - standalone server or Next.js integration.
+---
+
+import { CardGrid, CardGridItem } from "@site/src/components/cards/card-grid";
+
+# Quickstart
+
+Choose how you want to get started with Mastra:
+
+<CardGrid columns={2}>
+  <CardGridItem
+    title="Standalone Server (Recommended)"
+    href="/guides/v1/quickstarts/standalone-server"
+  >
+    The fastest way to get started - spin up a standalone Mastra server and interact with your agents in Studio
+  </CardGridItem>
+  <CardGridItem
+    title="Next.js"
+    href="/guides/v1/quickstarts/nextjs"
+  >
+    Integrate Mastra into a Next.js app and use the AI SDK UI to build an in-app chat interface for your agents
+  </CardGridItem>
+</CardGrid>
+
+For more control over setup, or to add Mastra to an existing project, see the [manual installation guide](/guides/v1/guide/manual-install). You can also use [`mastra init`](/reference/v1/cli/mastra#mastra-init) for existing projects.

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

@@ -1,5 +1,5 @@
 ---
-title: "Studio | Getting Started | Mastra Docs"
+title: "Studio | Getting Started"
 description: Guide on installing Mastra and setting up the necessary prerequisites for running it with various LLM providers.
 ---
 
@@ -73,7 +73,7 @@ Visualize your workflow as a graph and run it step by step with a custom input.
 
 <VideoPlayer src="https://res.cloudinary.com/mastra-assets/video/upload/v1751406027/local-dev-workflows-playground_100_rbc466.mp4" />
 
-When running a workflow, you can also view detailed traces showing tool calls, raw JSON outputs, and any errors that might have occured along the way.
+When running a workflow, you can also view detailed traces showing tool calls, raw JSON outputs, and any errors that might have occurred along the way.
 
 ### Tools
 
@@ -99,7 +99,7 @@ The Scorers tab displays the results of your agent's scorers as they run. When m
 
 ## REST API
 
-The local development server exposes a complete set of REST API routes, allowing you to programmatically interact with your agents, workflows, and tools during development. This is particularly helpful if you plan to deploy the Mastra server, since the local development server uses the exact same API routes as the [production server](/docs/v1/server-db/production-server), allowing you to develop and test against it with full parity.
+The local development server exposes a complete set of REST API routes, allowing you to programmatically interact with your agents, workflows, and tools during development. This is particularly helpful if you plan to deploy the Mastra server, since the local development server uses the exact same API routes as the [Mastra Server](/docs/v1/server-db/mastra-server), allowing you to develop and test against it with full parity.
 
 You can explore all available endpoints in the OpenAPI specification at http://localhost:4111/openapi.json, which details every endpoint and its request and response schemas.
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Templates | Getting Started | Mastra Docs"
+title: "Templates | Getting Started"
 description: Pre-built project structures that demonstrate common Mastra use cases and patterns
 ---
 

package/.docs/raw/guides/guide/ai-recruiter.mdx

@@ -16,7 +16,7 @@ You'll create a workflow that gathers information from a candidate's resume, the
 
 - Node.js `v22.13.0` or later installed
 - An API key from a supported [Model Provider](/models/v1)
-- An existing Mastra project (Follow the [installation guide](/docs/v1/getting-started/installation) to set up a new project)
+- An existing Mastra project (Follow the [installation guide](/guides/v1/quickstarts/standalone-server) to set up a new project)
 
 ## Building the Workflow
 

package/.docs/raw/guides/guide/chef-michel.mdx

@@ -19,7 +19,7 @@ You'll learn how to create the agent and register it with Mastra. Next, you'll i
 
 - Node.js `v22.13.0` or later installed
 - An API key from a supported [Model Provider](/models/v1)
-- An existing Mastra project (Follow the [installation guide](/docs/v1/getting-started/installation) to set up a new project)
+- An existing Mastra project (Follow the [installation guide](/guides/v1/quickstarts/standalone-server) to set up a new project)
 
 ## Creating the Agent