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

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

@@ -1,6 +1,8 @@
 ---
-title: "Request Context | Server & DB"
+title: "Request Context | Server"
 description: Learn how to use Mastra's RequestContext to provide dynamic, request-specific configuration to agents.
+packages:
+  - "@mastra/core"
 ---
 
 # Request Context
@@ -9,7 +11,7 @@ Agents, tools, and workflows can all accept `RequestContext` as a parameter, mak
 
 ## When to use `RequestContext`
 
-Use `RequestContext` when a primitive’s behavior should change based on runtime conditions. For example, you might switch models or storage backends based on user attributes, or adjust instructions and tool selection based on language.
+Use `RequestContext` when a primitive's behavior should change based on runtime conditions. For example, you might switch models or storage backends based on user attributes, or adjust instructions and tool selection based on language.
 
 :::note
 
@@ -28,7 +30,7 @@ The `.set()` method takes two arguments:
 1. **key**: The name used to identify the value.
 2. **value**: The data to associate with that key.
 
-```typescript showLineNumbers
+```typescript
 import { RequestContext } from "@mastra/core/request-context";
 
 export type UserTier = {
@@ -62,19 +64,17 @@ await run.resume({
   requestContext,
 });
 
-await weatherTool.execute({
-  context: {
-    location: "London",
-  },
-  requestContext,
-});
+await weatherTool.execute(
+  { location: "London" },
+  { requestContext },
+);
 ```
 
 ### Setting values based on request headers
 
 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";
@@ -99,13 +99,17 @@ export const mastra = new Mastra({
 });
 ```
 
-> See [Middleware](/docs/v1/server-db/middleware) for how to use server middleware.
+:::info
+
+Visit [Middleware](/docs/v1/server/middleware) for how to use server middleware.
+
+:::
 
 ## Accessing values with agents
 
 You can access the `requestContext` argument from any supported configuration options in agents. These functions can be sync or `async`. Use the `.get()` method to read values from `requestContext`.
 
-```typescript {7-8,15,18,21} title="src/mastra/agents/weather-agent.ts" showLineNumbers
+```typescript title="src/mastra/agents/weather-agent.ts"
 export type UserTier = {
   "user-tier": "enterprise" | "pro";
 };
@@ -116,32 +120,27 @@ export const weatherAgent = new Agent({
   instructions: async ({ requestContext }) => {
     const userTier = requestContext.get("user-tier") as UserTier["user-tier"];
 
-    if (userTier === "enterprise") {
-      // ...
-    }
-    // ...
-  },
-  model: ({ requestContext }) => {
-    // ...
-  },
-  tools: ({ requestContext }) => {
-    // ...
-  },
-  memory: ({ requestContext }) => {
-    // ...
+    if (userTier === "enterprise") {}
   },
+  model: ({ requestContext }) => {},
+  tools: ({ requestContext }) => {},
+  memory: ({ requestContext }) => {},
 });
 ```
 
 You can also use `requestContext` with other options like `agents`, `workflows`, `scorers`, `inputProcessors`, and `outputProcessors`.
 
-> See [Agent](/reference/v1/agents/agent) for a full list of configuration options.
+:::info
+
+Visit [Agent](/reference/v1/agents/agent) for a full list of configuration options.
+
+:::
 
 ## Accessing values from workflow steps
 
 You can access the `requestContext` argument from a workflow step's `execute` function. This function can be sync or async. Use the `.get()` method to read values from `requestContext`.
 
-```typescript {7-8} title="src/mastra/workflows/weather-workflow.ts" showLineNumbers copy
+```typescript title="src/mastra/workflows/weather-workflow.ts"
 export type UserTier = {
   "user-tier": "enterprise" | "pro";
 };
@@ -151,43 +150,86 @@ const stepOne = createStep({
   execute: async ({ requestContext }) => {
     const userTier = requestContext.get("user-tier") as UserTier["user-tier"];
 
-    if (userTier === "enterprise") {
-      // ...
-    }
-    // ...
+    if (userTier === "enterprise") {}
   },
 });
 ```
 
-> See [createStep()](/reference/v1/workflows/step) for a full list of configuration options.
+:::info
+
+Visit [createStep()](/reference/v1/workflows/step) for a full list of configuration options.
+
+:::
 
 ## Accessing values with tools
 
-You can access the `requestContext` argument from a tool’s `execute` function. This function is `async`. Use the `.get()` method to read values from `requestContext`.
+You can access the `requestContext` argument from a tool's `execute` function. This function is `async`. Use the `.get()` method to read values from `requestContext`.
 
-```typescript {7-8} title="src/mastra/tools/weather-tool.ts" showLineNumbers
+```typescript title="src/mastra/tools/weather-tool.ts"
 export type UserTier = {
   "user-tier": "enterprise" | "pro";
 };
 
 export const weatherTool = createTool({
   id: "weather-tool",
-  execute: async ({ requestContext }) => {
-    const userTier = requestContext.get("user-tier") as UserTier["user-tier"];
+  execute: async (inputData, context) => {
+    const userTier = context?.requestContext?.get("user-tier") as UserTier["user-tier"] | undefined;
 
-    if (userTier === "enterprise") {
-      // ...
-    }
-    // ...
+    if (userTier === "enterprise") {}
   },
 });
 ```
 
-> See [createTool()](/reference/v1/tools/create-tool) for a full list of configuration options.
+:::info
+
+Visit [createTool()](/reference/v1/tools/create-tool) for a full list of configuration options.
+
+:::
+
+## TypeScript support
+
+When you provide a type parameter to `RequestContext`, all methods are fully typed:
+
+```typescript
+import { RequestContext } from "@mastra/core/request-context";
+
+type MyContext = {
+  userId: string;
+  maxTokens: number;
+  isPremium: boolean;
+};
+
+const ctx = new RequestContext<MyContext>();
+
+// set() enforces correct value types
+ctx.set("userId", "user-123");   // ✓ valid
+ctx.set("maxTokens", 4096);      // ✓ valid
+ctx.set("maxTokens", "wrong");   // ✗ TypeScript error: expected number
+
+// get() returns the correct type automatically
+const tokens = ctx.get("maxTokens"); // inferred as number
+const id = ctx.get("userId");        // inferred as string
+
+// keys() returns typed keys
+for (const key of ctx.keys()) {
+  // key is "userId" | "maxTokens" | "isPremium"
+}
+
+// entries() supports type narrowing
+for (const [key, value] of ctx.entries()) {
+  if (key === "maxTokens") {
+    // TypeScript knows value is number here
+    console.log(value.toFixed(2));
+  }
+  if (key === "userId") {
+    // TypeScript knows value is string here
+    console.log(value.toUpperCase());
+  }
+}
+```
 
 ## Related
 
 - [Agent Request Context](/docs/v1/agents/overview#using-requestcontext)
 - [Workflow Request Context](../workflows/overview#using-requestcontext)
-- [Tool Request Context](../mcp/overview#using-requestcontext)
-- [Server Middleware](/docs/v1/server-db/middleware)
+- [Server Middleware](/docs/v1/server/middleware)

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

@@ -1,6 +1,9 @@
 ---
-title: "Server Adapters | Server & DB"
+title: "Server Adapters | Server"
 description: "Manually configure a Mastra server using Hono or Express adapters."
+packages:
+  - "@mastra/express"
+  - "@mastra/hono"
 ---
 
 import Tabs from "@theme/Tabs";
@@ -8,26 +11,36 @@ import TabItem from "@theme/TabItem";
 
 # Server Adapters
 
-Server adapters let you run Mastra with your own HTTP server instead of the Hono server generated by `mastra build`. They provide more control over the server setup, including custom middleware ordering, authentication, logging, and deployment configuration, while still letting you integrate Mastra into any Node.js application without changing how agents or workflows execute.
+Server adapters let you run Mastra with your own HTTP server instead of the Hono server generated by `mastra build`. They provide more control over the server setup, including custom middleware ordering, authentication, logging, and deployment configuration. You can still integrate Mastra into any Node.js application without changing how agents or workflows execute.
 
 ## When to use server adapters
 
-Use server adapters when you want Mastra’s endpoints added automatically to an existing application, when you need direct access to the server instance for custom configuration, or when your team prefers using Express instead of the Hono server created by `mastra build`.
+- You want Mastra’s endpoints added automatically to an existing application
+- You need direct access to the server instance for custom configuration
+- Your team prefers using another server framework instead of the Hono server created by `mastra build`.
 
-:::info
+:::tip
+
+For deployments without custom server requirements, use `mastra build` instead. It configures server setup, registers middleware, and applies deployment settings based on your project configuration. See [Server Configuration](/docs/v1/server/mastra-server).
 
-For simple deployments without custom server requirements, use `mastra build` instead. It configures server setup, registers middleware, and applies deployment settings based on your project configuration. See [Server Configuration](/docs/v1/server-db/mastra-server).
+If you want to use [Studio](/docs/v1/getting-started/studio) with your server adapter, use [`mastra studio`](/reference/v1/cli/mastra#mastra-studio) to only launch the Studio UI.
 
 :::
 
 ## Available adapters
 
-- [@mastra/express](/reference/v1/server/express-adapter): Express framework adapter.
-- [@mastra/hono](/reference/v1/server/hono-adapter): Hono framework adapter.
+Mastra currently provides these official server adapters:
+
+- [@mastra/express](/reference/v1/server/express-adapter)
+- [@mastra/hono](/reference/v1/server/hono-adapter)
+- [@mastra/fastify](/reference/v1/server/fastify-adapter)
+- [@mastra/koa](/reference/v1/server/koa-adapter)
+
+You can build your own adapter, read [custom adapters](/docs/v1/server/custom-adapters) for details.
 
 ## Installation
 
-Install the adapter for the framework you’re using.
+Install the adapter for the framework of your choice.
 
 <Tabs>
   <TabItem value="express" label="Express">
@@ -40,21 +53,33 @@ npm install @mastra/express@beta
 
 ```bash
 npm install @mastra/hono@beta
+```
+  </TabItem>
+  <TabItem value="fastify" label="Fastify">
+
+```bash
+npm install @mastra/fastify@beta
+```
+  </TabItem>
+  <TabItem value="koa" label="Koa">
+
+```bash
+npm install @mastra/koa@beta
 ```
   </TabItem>
 </Tabs>
 
 ## Configuration
 
-Initialize your Express or Hono app as usual, then create a `MastraServer` by passing in the `app` and your main `mastra` instance from `src/mastra`. Calling `init()` automatically registers Mastra middleware and all available endpoints. You can continue adding your own routes as normal, either before or after `init()`, and they’ll run alongside Mastra’s endpoints.
+Initialize your app as usual, then create a `MastraServer` by passing in the `app` and your main `mastra` instance from `src/mastra/index.ts`. Calling `init()` automatically registers Mastra middleware and all available endpoints. You can continue adding your own routes as normal, either before or after `init()`, and they’ll run alongside Mastra’s endpoints.
 
 <Tabs>
   <TabItem value="express" label="Express">
 
-```typescript {8} title="express-server.ts" showLineNumbers
+```typescript {8} title="src/express-server.ts"
 import express from "express";
 import { MastraServer } from "@mastra/express";
-import { mastra } from "./mastra"; // src/mastra/index.ts
+import { mastra } from "./mastra";
 
 const app = express();
 app.use(express.json());
@@ -68,14 +93,20 @@ app.listen(4111, () => {
 });
 ```
 
+:::info
+
+See the [Express Adapter](/reference/v1/server/express-adapter) documentation for full configuration options.
+
+:::
+
   </TabItem>
   <TabItem value="hono" label="Hono">
 
-```typescript {8} title="hono-server.ts" showLineNumbers
+```typescript {8} title="src/hono-server.ts"
 import { Hono } from "hono";
 import { serve } from "@hono/node-server";
 import { HonoBindings, HonoVariables, MastraServer } from "@mastra/hono";
-import { mastra } from "./mastra"; // src/mastra/index.ts
+import { mastra } from "./mastra";
 
 const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>();
 
@@ -88,11 +119,87 @@ serve({ fetch: app.fetch, port: 4111 }, () => {
 });
 ```
 
+:::info
+
+See the [Hono Adapter](/reference/v1/server/hono-adapter) documentation for full configuration options.
+
+:::
+
   </TabItem>
-</Tabs>
+  <TabItem value="fastify" label="Fastify">
+
+```typescript {6} title="src/fastify-server.ts"
+import Fastify from 'fastify';
+import { MastraServer } from '@mastra/fastify';
+import { mastra } from './mastra';
 
-> See the [Express Adapter](/reference/v1/server/express-adapter) or [Hono Adapter](/reference/v1/server/hono-adapter)  docs for full configuration options.
+const app = Fastify();
+const server = new MastraServer({ app, mastra });
 
+await server.init();
+
+app.get('/health', async request => {
+  const mastraInstance = request.mastra;
+  const agents = Object.keys(mastraInstance.listAgents());
+  return { status: 'ok', agents };
+});
+
+const port = 4111;
+
+app.listen({ port }, () => {
+  console.log(`Server running on http://localhost:${port}`);
+  console.log(`Try: curl http://localhost:${port}/api/agents`);
+});
+```
+
+:::info
+
+See the [Fastify Adapter](/reference/v1/server/fastify-adapter) documentation for full configuration options.
+
+:::
+
+  </TabItem>
+  <TabItem value="koa" label="Koa">
+
+```typescript {9} title="src/koa-server.ts"
+import Koa from 'koa';
+import bodyParser from 'koa-bodyparser';
+import { MastraServer } from '@mastra/koa';
+import { mastra } from './mastra';
+
+const app = new Koa();
+app.use(bodyParser()); // Required for body parsing
+
+const server = new MastraServer({ app, mastra });
+
+await server.init();
+
+app.use(async (ctx, next) => {
+  if (ctx.path === '/health' && ctx.method === 'GET') {
+    const mastraInstance = ctx.state.mastra;
+    const agents = Object.keys(mastraInstance.listAgents());
+    ctx.body = { status: 'ok', agents };
+    return;
+  }
+  await next();
+});
+
+const port = 4111;
+
+app.listen(port, () => {
+  console.log(`Server running on http://localhost:${port}`);
+  console.log(`Try: curl http://localhost:${port}/api/agents`);
+});
+```
+
+:::info
+
+See the [Koa Adapter](/reference/v1/server/koa-adapter) documentation for full configuration options.
+
+:::
+
+  </TabItem>
+</Tabs>
 
 ## Initialization flow
 
@@ -106,7 +213,7 @@ Calling `init()` runs three steps in order. Understanding this flow helps when y
 
 For custom middleware ordering, call each method separately instead of `init()`. This is useful when you need middleware that runs before Mastra's context is set up, or when you need to insert logic between the initialization steps.
 
-```typescript title="server.ts" copy showLineNumbers
+```typescript title="server.ts"
 const server = new MastraServer({ app, mastra });
 
 // Your middleware first
@@ -137,14 +244,17 @@ You can add your own routes to the app alongside Mastra's routes.
 - Routes added **before** `init()` won't have Mastra context available.
 - Routes added **after** `init()` have access to the Mastra context (the Mastra instance, request context, authenticated user, etc.).
 
-> See adding custom routes for [Express](/reference/v1/server/express-adapter#adding-custom-routes) and [Hono](/reference/v1/server/hono-adapter#adding-custom-routes) for more information.
+:::info
 
+Visit "Adding custom routes" for [Express](/reference/v1/server/express-adapter#adding-custom-routes) and [Hono](/reference/v1/server/hono-adapter#adding-custom-routes) for more information.
+
+:::
 
 ## Route prefixes
 
-By default, Mastra routes are registered at `/api/agents`, `/api/workflows`, etc. Use the `prefix` option to change this, which is useful for API versioning or when integrating with an existing app that has its own `/api` routes.
+By default, Mastra routes are registered at `/api/agents`, `/api/workflows`, etc. Use the `prefix` option to change this. This is useful for API versioning or when integrating with an existing app that has its own `/api` routes.
 
-```typescript showLineNumbers copy
+```typescript
 const server = new MastraServer({
   app,
   mastra,
@@ -158,7 +268,7 @@ With this prefix, Mastra routes become `/api/v2/agents`, `/api/v2/workflows`, et
 
 Mastra can generate an OpenAPI specification for all registered routes. This is useful for documentation, client generation, or integration with API tools. Enable it by setting the `openapiPath` option:
 
-```typescript showLineNumbers copy
+```typescript
 const server = new MastraServer({
   app,
   mastra,
@@ -181,7 +291,7 @@ This redaction happens at the HTTP boundary, so internal callbacks like `onStepF
 
 By default, redaction is enabled. Configure this behavior via `streamOptions`. Set `redact: false` only for internal services or debugging scenarios where you need access to the full request data in stream responses.
 
-```typescript showLineNumbers copy
+```typescript
 const server = new MastraServer({
   app,
   mastra,
@@ -191,7 +301,11 @@ const server = new MastraServer({
 });
 ```
 
-> See [MastraServer](/reference/v1/server/mastra-server) for full configuration options.
+:::info
+
+See [MastraServer](/reference/v1/server/mastra-server) for full configuration options.
+
+:::
 
 ## Per-route auth overrides
 
@@ -199,29 +313,36 @@ When authentication is configured on your Mastra instance, all routes require au
 
 Use `customRouteAuthConfig` to override authentication behavior for specific routes. Keys follow the format `METHOD:PATH` where method is `GET`, `POST`, `PUT`, `DELETE`, or `ALL`. Paths support wildcards (`*`) for matching multiple routes. Setting a value to `false` makes the route public, while `true` requires authentication.
 
-```typescript showLineNumbers copy
+```typescript
 const server = new MastraServer({
   app,
   mastra,
   customRouteAuthConfig: new Map([
-    ['GET:/api/health', false],       // Public health check
-    ['GET:/api/openapi.json', false], // Public API spec
-    ['POST:/api/webhooks/*', false],  // Public webhook endpoints
-    ['POST:/api/admin/reset', true],  // Require auth even if globally disabled
-    ['ALL:/api/internal/*', true],    // Protect all methods on internal routes
+    // Public health check
+    ['GET:/api/health', false],
+    // Public API spec
+    ['GET:/api/openapi.json', false],
+    // Public webhook endpoints
+    ['POST:/api/webhooks/*', false],
+    // Require auth even if globally disabled
+    ['POST:/api/admin/reset', true],
+    // Protect all methods on internal routes
+    ['ALL:/api/internal/*', true],
   ]),
 });
 ```
 
+:::info
 
+See [MastraServer](/reference/v1/server/mastra-server) for full configuration options.
 
-> See [MastraServer](/reference/v1/server/mastra-server) for full configuration options.
+:::
 
 ## Accessing the app
 
 After creating the adapter, you may still need access to the underlying framework app. This is useful when passing it to a platform’s `serve` function or when adding routes from another module.
 
-```typescript showLineNumbers copy
+```typescript
 // Via the MastraServer instance
 const app = server.getApp();
 
@@ -282,8 +403,8 @@ See [MCP](/docs/v1/mcp/overview) for configuration details and how to set up MCP
 
 - [Hono Adapter](/reference/v1/server/hono-adapter) - Hono-specific setup
 - [Express Adapter](/reference/v1/server/express-adapter) - Express-specific setup
-- [Custom Adapters](/docs/v1/server-db/custom-adapters) - Building adapters for other frameworks
-- [Server Configuration](/docs/v1/server-db/mastra-server) - Using `mastra build` instead
-- [Authentication](/docs/v1/auth) - Configuring auth for your server
+- [Custom Adapters](/docs/v1/server/custom-adapters) - Building adapters for other frameworks
+- [Server Configuration](/docs/v1/server/mastra-server) - Using `mastra build` instead
+- [Authentication](/docs/v1/server/auth) - Configuring auth for your server
 - [MastraServer Reference](/reference/v1/server/mastra-server) - Full API reference
 - [createRoute() Reference](/reference/v1/server/create-route) - Creating type-safe custom routes

package/.docs/raw/streaming/events.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Streaming Events | Streaming"
 description: "Learn about the different types of streaming events in Mastra, including text deltas, tool calls, step events, and how to handle them in your applications."
+packages:
+  - "@mastra/core"
 ---
 
 # Streaming Events
@@ -44,7 +46,7 @@ When using `agent.network()` for multi-agent collaboration, additional event typ
 
 Iterate over the `stream` with a `for await` loop to inspect all emitted event chunks.
 
-```typescript {3,7} showLineNumbers copy
+```typescript
 const testAgent = mastra.getAgent("testAgent");
 
 const stream = await testAgent.stream([
@@ -56,7 +58,11 @@ for await (const chunk of stream) {
 }
 ```
 
-> See [Agent.stream()](/reference/v1/streaming/agents/stream) for more information.
+:::info
+
+Visit [Agent.stream()](/reference/v1/streaming/agents/stream) for more information.
+
+:::
 
 ### Example agent output
 
@@ -91,7 +97,7 @@ Below is an example of events that may be emitted. Each event always includes a
 
 Iterate over the `stream` with a `for await` loop to inspect all emitted event chunks.
 
-```typescript {5,11} showLineNumbers copy
+```typescript {5,11}
 const testWorkflow = mastra.getWorkflow("testWorkflow");
 
 const run = await testWorkflow.createRun();
@@ -136,7 +142,7 @@ Below is an example of events that may be emitted. Each event always includes a
 
 When using multi-agent collaboration with `agent.network()`, iterate over the stream to track how tasks are delegated and executed across agents, workflows, and tools.
 
-```typescript {3,5} showLineNumbers copy
+```typescript {3,5}
 const networkAgent = mastra.getAgent("networkAgent");
 
 const networkStream = await networkAgent.network(
@@ -148,7 +154,11 @@ for await (const chunk of networkStream) {
 }
 ```
 
-> See [Agent.network()](/reference/v1/agents/network) for more information.
+:::info
+
+Visit [Agent.network()](/reference/v1/agents/network) for more information.
+
+:::
 
 ### Example network output
 
@@ -195,14 +205,13 @@ Network streams emit events that track the orchestration flow. Each iteration be
     }
   }
 }
-// ...more events
 ```
 
 ### Filtering network events
 
 You can filter events by type to track specific aspects of the network execution:
 
-```typescript {5-8,11-13,16-18} showLineNumbers copy
+```typescript {5-8,11-13,16-18}
 const networkStream = await networkAgent.network(
   "Analyze data and create visualization",
 );