@mastra/mcp-docs-server 1.0.0-beta.9 → 1.0.0

package/.docs/raw/{server-db → server}/custom-adapters.mdx

@@ -1,6 +1,13 @@
 ---
-title: "Custom Adapters | Server & DB"
+title: "Custom Adapters | Server"
 description: "Create a custom server adapter for frameworks other than Hono or Express."
+packages:
+  - "@mastra/core"
+  - "@mastra/express"
+  - "@mastra/hono"
+  - "@mastra/server"
+  - "@mastra/fastify"
+  - "@mastra/koa"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
@@ -13,25 +20,31 @@ A custom adapter translates between Mastra's route definitions and your framewor
 
 :::info
 
-For Hono or Express, use the provided adapters instead:
+Use any of these prebuilt server adapters:
+
 - [@mastra/hono](/reference/v1/server/hono-adapter)
 - [@mastra/express](/reference/v1/server/express-adapter)
+- [@mastra/fastify](/reference/v1/server/fastify-adapter)
+- [@mastra/koa](/reference/v1/server/koa-adapter)
 
 :::
 
 ## Abstract class
 
-The `MastraServer` abstract class from `@mastra/server` provides the foundation for all adapters. It handles route registration logic, parameter validation, and other shared functionality. Your custom adapter extends this class and implements the framework-specific parts.
+The `MastraServer` abstract class from `@mastra/server/server-adapter` provides the foundation for all adapters. It handles route registration logic, parameter validation, and other shared functionality. Your custom adapter extends this class and implements the framework-specific parts.
 
 The class takes three type parameters that represent your framework's types:
 
-```typescript title="my-framework-adapter.ts" copy showLineNumbers
-import { MastraServer } from '@mastra/server';
+```typescript title="my-framework-adapter.ts"
+import { MastraServer } from '@mastra/server/server-adapter';
 
 export class MyFrameworkServer extends MastraServer<
-  MyApp,      // Your framework's app type (e.g., FastifyInstance)
-  MyRequest,  // Your framework's request type (e.g., FastifyRequest)
-  MyResponse  // Your framework's response type (e.g., FastifyReply)
+  // Your framework's app type (e.g., FastifyInstance)
+  MyApp,
+  // Your framework's request type (e.g., FastifyRequest)
+  MyRequest,
+  // Your framework's response type (e.g., FastifyReply)
+  MyResponse
 > {
   // Implement abstract methods
 }
@@ -45,9 +58,9 @@ You must implement these six abstract methods. Each handles a specific part of t
 
 ### registerContextMiddleware()
 
-This method runs first and attaches Mastra context to every incoming request. Route handlers need access to the Mastra instance, tools, and other context to function. How you attach this context depends on your framework—Express uses `res.locals`, Hono uses `c.set()`, and other frameworks have their own patterns.
+This method runs first and attaches Mastra context to every incoming request. Route handlers need access to the Mastra instance, tools, and other context to function. How you attach this context depends on your framework — Express uses `res.locals`, Hono uses `c.set()`, and other frameworks have their own patterns.
 
-```typescript copy showLineNumbers
+```typescript
 registerContextMiddleware(): void {
   this.app.use('*', (req, res, next) => {
     // Attach context to your framework's request/response
@@ -74,7 +87,7 @@ Context to attach:
 
 Register authentication and authorization middleware. This method should check if authentication is configured on the Mastra instance and skip registration entirely if not. When auth is configured, you'll typically register two middleware functions: one for authentication (validating tokens and setting the user) and one for authorization (checking if the user can access the requested resource).
 
-```typescript copy showLineNumbers
+```typescript
 registerAuthMiddleware(): void {
   const authConfig = this.mastra.getServer()?.auth;
   if (!authConfig) return;
@@ -110,7 +123,7 @@ registerAuthMiddleware(): void {
 
 Register a single route with your framework. This method is called once for each Mastra route during initialization. It receives a `ServerRoute` object containing the path, HTTP method, handler function, and Zod schemas for validation. Your implementation should wire this up to your framework's routing system.
 
-```typescript copy showLineNumbers
+```typescript
 async registerRoute(
   app: MyApp,
   route: ServerRoute,
@@ -157,7 +170,7 @@ async registerRoute(
 
 Extract URL parameters, query parameters, and request body from the incoming request. Different frameworks expose these values in different ways—Express uses `req.params`, `req.query`, and `req.body`, while other frameworks may use different property names or require method calls. This method normalizes the extraction for your framework.
 
-```typescript copy showLineNumbers
+```typescript
 async getParams(
   route: ServerRoute,
   request: MyRequest
@@ -167,9 +180,12 @@ async getParams(
   body: unknown;
 }> {
   return {
-    urlParams: request.params,        // From route path (e.g., :agentId)
-    queryParams: request.query,       // From URL query string
-    body: request.body,               // From request body
+    // From route path (e.g., :agentId)
+    urlParams: request.params,
+    // From URL query string
+    queryParams: request.query,
+    // From request body
+    body: request.body,
   };
 }
 ```
@@ -178,7 +194,7 @@ async getParams(
 
 Send the response back to the client based on the route's response type. Mastra routes can return different response types: JSON for most API responses, streams for agent generation, and special types for MCP transports. Your implementation should handle each type appropriately for your framework.
 
-```typescript copy showLineNumbers
+```typescript
 async sendResponse(
   route: ServerRoute,
   response: MyResponse,
@@ -213,7 +229,7 @@ async sendResponse(
 
 Handle streaming responses for agent generation. When an agent generates a response, it produces a stream of chunks that should be sent to the client as they become available. This method reads from the stream, optionally applies redaction to hide sensitive data, and writes chunks to the response in the appropriate format (SSE or newline-delimited JSON).
 
-```typescript copy showLineNumbers
+```typescript
 async stream(
   route: ServerRoute,
   response: MyResponse,
@@ -276,7 +292,7 @@ The `parse*` methods use Zod schemas defined on each route to validate input and
 
 Your adapter's constructor should accept the same options as the base class and pass them to `super()`. You can add additional framework-specific options if needed:
 
-```typescript copy showLineNumbers
+```typescript
 constructor(options: {
   app: MyApp;
   mastra: Mastra;
@@ -290,14 +306,14 @@ constructor(options: {
 }
 ```
 
-See [Server Adapters](/docs/v1/server-db/server-adapters#constructor-options) for full documentation on each option.
+See [Server Adapters](/docs/v1/server/server-adapters) for full documentation on each option.
 
 ## Full example
 
 Here's a skeleton implementation showing all the required methods. This uses pseudocode for framework-specific parts—replace with your framework's actual APIs:
 
-```typescript title="my-framework-adapter.ts" copy showLineNumbers
-import { MastraServer, ServerRoute } from '@mastra/server';
+```typescript title="my-framework-adapter.ts"
+import { MastraServer, ServerRoute } from '@mastra/server/server-adapter';
 import type { Mastra } from '@mastra/core';
 
 export class MyFrameworkServer extends MastraServer<MyApp, MyRequest, MyResponse> {
@@ -353,7 +369,7 @@ export class MyFrameworkServer extends MastraServer<MyApp, MyRequest, MyResponse
 
 Once your adapter is implemented, use it the same way as the provided adapters:
 
-```typescript title="server.ts" copy showLineNumbers
+```typescript title="server.ts"
 import { MyFrameworkServer } from './my-framework-adapter';
 import { mastra } from './mastra';
 
@@ -373,7 +389,7 @@ The existing [@mastra/hono](https://github.com/mastra-ai/mastra/blob/main/server
 
 ## Related
 
-- [Server Adapters](/docs/v1/server-db/server-adapters) - Overview and shared concepts
+- [Server Adapters](/docs/v1/server/server-adapters) - Overview and shared concepts
 - [Hono Adapter](/reference/v1/server/hono-adapter) - Reference implementation
 - [Express Adapter](/reference/v1/server/express-adapter) - Reference implementation
 - [MastraServer Reference](/reference/v1/server/mastra-server) - Full API reference

package/.docs/raw/{server-db → server}/custom-api-routes.mdx

@@ -1,6 +1,8 @@
 ---
-title: "Custom API Routes | Server & DB"
+title: "Custom API Routes | Server"
 description: "Expose additional HTTP endpoints from your Mastra server."
+packages:
+  - "@mastra/core"
 ---
 
 # Custom API Routes
@@ -9,19 +11,18 @@ By default, Mastra automatically exposes registered agents and workflows via its
 
 Routes are provided with a helper `registerApiRoute()` from `@mastra/core/server`. Routes can live in the same file as the `Mastra` instance but separating them helps keep configuration concise.
 
-```typescript title="src/mastra/index.ts" copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { registerApiRoute } from "@mastra/core/server";
 
 export const mastra = new Mastra({
-  // ...
   server: {
     apiRoutes: [
       registerApiRoute("/my-custom-route", {
         method: "GET",
         handler: async (c) => {
           const mastra = c.get("mastra");
-          const agents = await mastra.getAgent("my-agent");
+          const agent = await mastra.getAgent("my-agent");
 
           return c.json({ message: "Custom route" });
         },
@@ -41,12 +42,11 @@ Each route's handler receives the Hono `Context`. Within the handler you can acc
 
 To add route-specific middleware pass a `middleware` array when calling `registerApiRoute()`.
 
-```typescript title="src/mastra/index.ts" copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { registerApiRoute } from "@mastra/core/server";
 
 export const mastra = new Mastra({
-  // ...
   server: {
     apiRoutes: [
       registerApiRoute("/my-custom-route", {

package/.docs/raw/{server-db → server}/mastra-client.mdx

@@ -1,6 +1,9 @@
 ---
-title: "Mastra Client SDK | Server & DB"
+title: "Mastra Client SDK | Server"
 description: "Learn how to set up and use the Mastra Client SDK"
+packages:
+  - "@mastra/client-js"
+  - "@mastra/core"
 ---
 
 import Tabs from "@theme/Tabs";
@@ -8,7 +11,7 @@ import TabItem from "@theme/TabItem";
 
 # Mastra Client SDK
 
-The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](/docs/v1/server-db/mastra-server) from your client environment.
+The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](/docs/v1/server/mastra-server) from your client environment.
 
 ## Prerequisites
 
@@ -61,7 +64,7 @@ To use the Mastra Client SDK, install the required dependencies:
 
 Once initialized with a `baseUrl`, `MastraClient` exposes a type-safe interface for calling agents, tools, and workflows.
 
-```typescript title="lib/mastra-client.ts" showLineNumbers copy
+```typescript title="lib/mastra-client.ts"
 import { MastraClient } from "@mastra/client-js";
 
 export const mastraClient = new MastraClient({
@@ -83,23 +86,16 @@ The Mastra Client SDK exposes all resources served by the Mastra Server
 
 ## Generating responses
 
-Call `.generate()` with an array of message objects that include `role` and `content`:
+Call `.generate()` with a string prompt:
 
-```typescript showLineNumbers copy
+```typescript
 import { mastraClient } from "lib/mastra-client";
 
 const testAgent = async () => {
   try {
     const agent = mastraClient.getAgent("testAgent");
 
-    const response = await agent.generate({
-      messages: [
-        {
-          role: "user",
-          content: "Hello",
-        },
-      ],
-    });
+    const response = await agent.generate("Hello");
 
     console.log(response.text);
   } catch (error) {
@@ -108,27 +104,24 @@ const testAgent = async () => {
 };
 ```
 
-> See [.generate()](/reference/v1/client-js/agents#generate-response) for more information.
+:::info
+
+You can also call `.generate()` with an array of message objects that include `role` and `content`. Visit the [.generate() reference](/reference/v1/client-js/agents#generate) for more information.
+
+:::
 
 ## Streaming responses
 
-Use `.stream()` for real-time responses with an array of message objects that include `role` and `content`:
+Use `.stream()` for real-time responses with a string prompt:
 
-```typescript showLineNumbers copy
+```typescript
 import { mastraClient } from "lib/mastra-client";
 
 const testAgent = async () => {
   try {
     const agent = mastraClient.getAgent("testAgent");
 
-    const stream = await agent.stream({
-      messages: [
-        {
-          role: "user",
-          content: "Hello",
-        },
-      ],
-    });
+    const stream = await agent.stream("Hello");
 
     stream.processDataStream({
       onTextPart: (text) => {
@@ -141,17 +134,20 @@ const testAgent = async () => {
 };
 ```
 
-> See [.stream()](/reference/v1/client-js/agents#stream-response) for more information.
+:::info
+
+You can also call `.stream()` with an array of message objects that include `role` and `content`. Visit the [.stream() reference](/reference/v1/client-js/agents#stream) for more information.
+
+:::
 
 ## Configuration options
 
 `MastraClient` accepts optional parameters like `retries`, `backoffMs`, and `headers` to control request behavior. These parameters are useful for controlling retry behavior and including diagnostic metadata.
 
-```typescript title="lib/mastra-client.ts" showLineNumbers copy
+```typescript title="lib/mastra-client.ts"
 import { MastraClient } from "@mastra/client-js";
 
 export const mastraClient = new MastraClient({
-  // ...
   retries: 3,
   backoffMs: 300,
   maxBackoffMs: 5000,
@@ -161,7 +157,11 @@ export const mastraClient = new MastraClient({
 });
 ```
 
-> See [MastraClient](/reference/v1/client-js/mastra-client) for more configuration options.
+:::info
+
+Visit [MastraClient](/reference/v1/client-js/mastra-client) for more configuration options.
+
+:::
 
 ## Adding request cancelling
 
@@ -169,7 +169,7 @@ export const mastraClient = new MastraClient({
 
 Pass an `AbortSignal` to the client constructor to enable cancellation across all requests.
 
-```typescript {3,7} title="lib/mastra-client.ts" showLineNumbers copy
+```typescript {3,7} title="lib/mastra-client.ts"
 import { MastraClient } from "@mastra/client-js";
 
 export const controller = new AbortController();
@@ -184,7 +184,7 @@ export const mastraClient = new MastraClient({
 
 Calling `.abort()` will cancel any ongoing requests tied to that signal.
 
-```typescript {4} showLineNumbers copy
+```typescript {4}
 import { mastraClient, controller } from "lib/mastra-client";
 
 const handleAbort = () => {
@@ -198,7 +198,7 @@ Define tools directly in client-side applications using the `createTool()` funct
 
 This lets agents trigger browser-side functionality such as DOM manipulation, local storage access, or other Web APIs, enabling tool execution in the user's environment rather than on the server.
 
-```typescript {27} showLineNumbers copy
+```typescript {27}
 import { createTool } from "@mastra/client-js";
 import { z } from "zod";
 
@@ -223,8 +223,7 @@ const handleClientTool = async () => {
       },
     });
 
-    const response = await agent.generate({
-      messages: "Change the background to blue",
+    const response = await agent.generate("Change the background to blue", {
       clientTools: { colorChangeTool },
     });
 
@@ -239,7 +238,7 @@ const handleClientTool = async () => {
 
 This is a standard Mastra [agent](../agents/overview#setting-up-agents) configured to return hex color codes, intended to work with the browser-based client tool defined above.
 
-```typescript title="src/mastra/agents/color-agent" showLineNumbers copy
+```typescript title="src/mastra/agents/color-agent"
 import { Agent } from "@mastra/core/agent";
 
 export const colorAgent = new Agent({
@@ -256,13 +255,11 @@ export const colorAgent = new Agent({
 
 You can also use `MastraClient` in server-side environments such as API routes, serverless functions or actions. The usage will broadly remain the same but you may need to recreate the response to your client:
 
-```typescript {8} showLineNumbers
+```typescript {8}
 export async function action() {
   const agent = mastraClient.getAgent("testAgent");
 
-  const stream = await agent.stream({
-    messages: [{ role: "user", content: "Hello" }],
-  });
+  const stream = await agent.stream("Hello");
 
   return new Response(stream.body);
 }

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

@@ -0,0 +1,86 @@
+---
+title: "Server Overview | Server"
+description: "Overview of the Mastra server, covering HTTP endpoints, middleware, authentication, and client integration."
+packages:
+  - "@mastra/core"
+---
+
+# Server Overview
+
+Mastra runs as an HTTP server that exposes your agents, workflows, and other functionality as API endpoints. The server handles request routing, middleware execution, authentication, and streaming responses.
+
+:::info
+
+This page covers the [`server`](/reference/v1/configuration#server-options) configuration options passed to the `Mastra` constructor. For running Mastra with your own HTTP server (Hono, Express, etc.), visit [Server Adapters](/docs/v1/server/server-adapters).
+
+:::
+
+## Server architecture
+
+Mastra uses [Hono](https://hono.dev) as its underlying HTTP server framework. When you build a Mastra application using `mastra build`, it generates a Hono-based HTTP server in the `.mastra` directory.
+
+The server provides:
+
+- API endpoints for all registered agents and workflows
+- Custom API routes and middleware
+- Authentication with multiple providers
+- Request context for dynamic configuration
+- Stream data redaction for secure responses
+
+## Configuration
+
+Configure the server by passing a `server` object to the `Mastra` constructor:
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core";
+
+export const mastra = new Mastra({
+  server: {
+    port: 3000, // Defaults to 4111
+    host: "0.0.0.0", // Defaults to 'localhost'
+  },
+});
+```
+
+:::info
+
+Visit the [configuration reference](/reference/v1/configuration#server-options) for a full list of available server options.
+
+:::
+
+## Server features
+
+- **[Middleware](/docs/v1/server/middleware)**: Intercept requests for authentication, logging, CORS, or injecting request-specific context.
+- **[Custom API Routes](/docs/v1/server/custom-api-routes)**: Extend the server with your own HTTP endpoints that have access to the Mastra instance.
+- **[Request Context](/docs/v1/server/request-context)**: Pass request-specific values to agents, tools, and workflows based on runtime conditions.
+- **[Server Adapters](/docs/v1/server/server-adapters)**: Run Mastra with Express, Hono, or your own HTTP server instead of the generated server.
+- **[Custom Adapters](/docs/v1/server/custom-adapters)**: Build adapters for frameworks not officially supported.
+- **[Mastra Client SDK](/docs/v1/server/mastra-client)**: Type-safe client for calling agents, workflows, and tools from browser or server environments.
+- **[Authentication](/docs/v1/server/auth)**: Secure endpoints with JWT, Clerk, Supabase, Firebase, Auth0, or WorkOS.
+
+## Stream data redaction
+
+When streaming agent responses, the HTTP layer redacts system prompts, tool definitions, API keys, and similar data from each chunk before sending it to clients. This is enabled by default.
+
+This behavior is only configurable by using [server adapters](/docs/v1/server/server-adapters#stream-data-redaction). For server adapters, stream data redaction is enabled by default, too.
+
+## TypeScript configuration
+
+Mastra requires `module` and `moduleResolution` settings compatible with modern Node.js. Legacy options like `CommonJS` or `node` are not supported.
+
+```json {4-5} title="tsconfig.json"
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}
+```

package/.docs/raw/{server-db → server}/middleware.mdx

@@ -1,6 +1,8 @@
 ---
-title: "Middleware | Server & DB"
+title: "Middleware | Server"
 description: "Apply custom middleware functions to intercept requests."
+packages:
+  - "@mastra/core"
 ---
 
 # Middleware
@@ -13,7 +15,7 @@ A middleware receives the [Hono](https://hono.dev) `Context` (`c`) and a `next`
 function. If it returns a `Response` the request is short-circuited. Calling
 `next()` continues processing the next middleware or route handler.
 
-```typescript copy showLineNumbers
+```typescript
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
@@ -44,7 +46,7 @@ export const mastra = new Mastra({
 To attach middleware to a single route pass the `middleware` option to
 `registerApiRoute`:
 
-```typescript copy showLineNumbers
+```typescript
 registerApiRoute("/my-custom-route", {
   method: "GET",
   middleware: [
@@ -68,7 +70,7 @@ registerApiRoute("/my-custom-route", {
 
 You can populate `RequestContext` dynamically in server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { RequestContext } from "@mastra/core/request-context";
 import { testWeatherAgent } from "./agents/test-weather-agent";
@@ -95,7 +97,7 @@ export const mastra = new Mastra({
 
 ### Authentication
 
-```typescript copy
+```typescript
 {
   handler: async (c, next) => {
     const authHeader = c.req.header('Authorization');
@@ -112,7 +114,7 @@ export const mastra = new Mastra({
 
 ### CORS support
 
-```typescript copy
+```typescript
 {
   handler: async (c, next) => {
     c.header('Access-Control-Allow-Origin', '*');
@@ -136,7 +138,7 @@ export const mastra = new Mastra({
 
 ### Request logging
 
-```typescript copy
+```typescript
 {
   handler: async (c, next) => {
     const start = Date.now();
@@ -152,7 +154,7 @@ export const mastra = new Mastra({
 When integrating with Mastra Cloud or custom clients the following headers can
 be inspected by middleware to tailor behavior:
 
-```typescript copy
+```typescript
 {
   handler: async (c, next) => {
     const isFromMastraCloud = c.req.header('x-mastra-cloud') === 'true';
@@ -174,4 +176,4 @@ be inspected by middleware to tailor behavior:
 
 # Related
 
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)