@mastra/mcp-docs-server 1.0.0-beta.11 → 1.0.0-beta.13

package/.docs/raw/{deployment/cloud-providers → guides/deployment}/aws-lambda.mdx

@@ -29,11 +29,8 @@ Before deploying to AWS Lambda, ensure you have:
 
 ## Memory Configuration
 
-:::note
-AWS Lambda uses an ephemeral file system,
-meaning that any files written to the file system are short-lived and may be lost.
-Avoid using a Mastra storage provider that uses the file system,
-such as `LibSQLStore` with a file URL.
+:::warning
+AWS Lambda uses an ephemeral file system, meaning that any files written to the file system are short-lived and may be lost. Remove any usage of [LibSQLStore](/docs/v1/memory/storage/overview) with file URLs from your Mastra configuration. Use in-memory storage (`:memory:`) or external storage providers like Turso, PostgreSQL, or Upstash.
 :::
 
 Lambda functions have limitations with file system storage. Configure your Mastra application to use either in-memory or external storage providers:
@@ -216,7 +213,7 @@ Once deployed, test your Lambda function:
 2. Visit the URL in your browser to see your Mastra's server home screen
 3. Test your agents and workflows using the generated API endpoints
 
-For more information about available API endpoints, see the [Server documentation](/docs/v1/deployment/building-mastra).
+For more information about available API endpoints, see the [Server documentation](/docs/v1/deployment/mastra-server).
 
 ## Connecting your client
 

package/.docs/raw/{deployment/cloud-providers → guides/deployment}/azure-app-services.mdx

@@ -17,6 +17,10 @@ For more information on how to create a new Mastra application,
 refer to our [getting started guide](/guides/v1/getting-started/quickstart)
 :::
 
+:::warning
+Azure App Services uses an ephemeral filesystem for some pricing tiers. Remove any usage of [LibSQLStore](/docs/v1/memory/storage/overview) with file URLs from your Mastra configuration. Use in-memory storage (`:memory:`) or external storage providers like Turso, PostgreSQL, or Upstash.
+:::
+
 ## Prerequisites
 
 - An [Azure account](https://azure.microsoft.com/) with an active subscription
@@ -151,12 +155,6 @@ const mastraClient = new MastraClient({
 });
 ```
 
-:::note
-Azure App Services uses an ephemeral file system for some pricing tiers.
-For production applications, avoid using Mastra storage providers that rely on the local file system,
-such as `LibSQLStore` with a file URL. Consider using cloud-based storage solutions instead.
-:::
-
 ## Next steps
 
 - [Mastra Client SDK](/reference/v1/client-js/mastra-client)

package/.docs/raw/{deployment/cloud-providers → guides/deployment}/cloudflare-deployer.mdx

@@ -7,6 +7,10 @@ description: "Learn how to deploy a Mastra application to Cloudflare using the M
 
 The `CloudflareDeployer` class handles deployment of standalone Mastra applications to Cloudflare Workers. It manages configuration, deployment, and extends the base [Deployer](/reference/v1/deployer/) class with Cloudflare specific functionality.
 
+:::warning
+Cloudflare Workers do not support filesystem access. Remove any usage of [LibSQLStore](/docs/v1/memory/storage/overview) with file URLs from your Mastra configuration. Use in-memory storage (`:memory:`) or external storage providers like Turso, PostgreSQL, or Upstash.
+:::
+
 ## Installation
 
 ```bash copy

package/.docs/raw/{deployment/cloud-providers → guides/deployment}/digital-ocean.mdx

@@ -97,11 +97,8 @@ Deployment
 
 You can now access your deployed application at the URL provided by Digital Ocean.
 
-:::note
-The Digital Ocean App Platform uses an ephemeral file system,
-meaning that any files written to the file system are short-lived and may be lost.
-Avoid using a Mastra storage provider that uses the file system,
-such as `LibSQLStore` with a file URL.
+:::warning
+The Digital Ocean App Platform uses an ephemeral file system, meaning that any files written to the file system are short-lived and may be lost. Remove any usage of [LibSQLStore](/docs/v1/memory/storage/overview) with file URLs from your Mastra configuration. Use in-memory storage (`:memory:`) or external storage providers like Turso, PostgreSQL, or Upstash.
 :::
 
   </TabItem>
@@ -220,7 +217,7 @@ Your Mastra application will run on port 4111 by default. Ensure your reverse pr
 
 You can now connect to your Mastra server from your client application using a `MastraClient` from the `@mastra/client-js` package.
 
-Refer to the [`MastraClient` documentation](/docs/v1/server-db/mastra-client) for more information.
+Refer to the [`MastraClient` documentation](/docs/v1/server/mastra-client) for more information.
 
 ```typescript copy showLineNumbers
 import { MastraClient } from "@mastra/client-js";

package/.docs/raw/guides/deployment/index.mdx

@@ -0,0 +1,32 @@
+---
+title: "Cloud Providers | Deployment"
+description: "Deploy your Mastra applications to popular cloud providers."
+---
+
+# Cloud Providers
+
+Standalone Mastra applications can be deployed to popular cloud providers, see one of the following guides for more information:
+
+- [Amazon EC2](/guides/v1/deployment/amazon-ec2)
+- [AWS Lambda](/guides/v1/deployment/aws-lambda)
+- [Azure App Services](/guides/v1/deployment/azure-app-services)
+- [Cloudflare](/guides/v1/deployment/cloudflare-deployer)
+- [Digital Ocean](/guides/v1/deployment/digital-ocean)
+- [Netlify](/guides/v1/deployment/netlify-deployer)
+- [Vercel](/guides/v1/deployment/vercel-deployer)
+
+For self-hosted Node.js server deployment, see the [Creating A Mastra Server](/docs/v1/deployment/mastra-server) guide.
+
+## Prerequisites
+
+Before deploying to a cloud provider, ensure you have:
+
+- A [Mastra application](/guides/v1/getting-started/quickstart)
+- Node.js `v22.13.0` or later
+- A GitHub repository for your application (required for most CI/CD setups)
+- Domain name management access (for SSL and HTTPS)
+- Basic familiarity with server setup (e.g. Nginx, environment variables)
+
+:::warning
+`LibSQLStore` writes to the local filesystem, which is not supported in cloud environments that use ephemeral file systems. If you're deploying to platforms like AWS Lambda, Netlify, Azure App Services, or Digital Ocean App Platform, you must remove all usage of [LibSQLStore](/docs/v1/memory/storage/overview) with file URLs. Use in-memory storage (`:memory:`) or external storage providers like Turso, PostgreSQL, or Upstash.
+:::

package/.docs/raw/{deployment/cloud-providers → guides/deployment}/netlify-deployer.mdx

@@ -7,6 +7,10 @@ description: "Learn how to deploy a Mastra application to Netlify using the Mast
 
 The `NetlifyDeployer` class handles deployment of standalone Mastra applications to Netlify. It manages configuration, deployment, and extends the base [Deployer](/reference/v1/deployer/) class with Netlify specific functionality.
 
+:::warning
+Netlify Functions use an ephemeral filesystem. Remove any usage of [LibSQLStore](/docs/v1/memory/storage/overview) with file URLs from your Mastra configuration. Use in-memory storage (`:memory:`) or external storage providers like Turso, PostgreSQL, or Upstash.
+:::
+
 ## Installation
 
 ```bash copy

package/.docs/raw/{deployment/cloud-providers → guides/deployment}/vercel-deployer.mdx

@@ -7,6 +7,10 @@ description: "Learn how to deploy a Mastra application to Vercel using the Mastr
 
 The `VercelDeployer` class handles deployment of standalone Mastra applications to Vercel. It manages configuration, deployment, and extends the base [Deployer](/reference/v1/deployer/) class with Vercel specific functionality.
 
+:::warning
+Vercel Functions use an ephemeral filesystem. Remove any usage of [LibSQLStore](/docs/v1/memory/storage/overview) with file URLs from your Mastra configuration. Use in-memory storage (`:memory:`) or external storage providers like Turso, PostgreSQL, or Upstash.
+:::
+
 ## Installation
 
 ```bash copy

package/.docs/raw/guides/getting-started/express.mdx

@@ -1,209 +1,128 @@
 ---
-title: "Integrate Mastra in your Express project | Frameworks"
-description: A step-by-step guide to integrating Mastra with an Express backend.
+title: "Express | Frameworks"
+description: "Get started with Mastra and Express"
 ---
 
-# Integrate Mastra in your Express project
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
 
-Mastra integrates with Express, making it easy to:
+# Integrate Mastra in your Express project
 
-- Build flexible APIs to serve AI-powered features
-- Maintain full control over your server logic and routing
-- Scale your backend independently of your frontend
+In this guide, you'll build a tool-calling AI agent using Mastra and Express. Using the [Express server adapter](/reference/v1/server/express-adapter), you can expose your agents as HTTP endpoints without writing the routing yourself or running a separate Mastra server.
 
-Express can invoke Mastra directly so you don't need to run a Mastra server alongside your Express server.
+## Before you begin
 
-In this guide you'll learn how to install the necessary Mastra dependencies, create an example agent, and invoke Mastra from an Express API route.
+- You'll need an API key from a supported [model provider](/models/v1). If you don't have a preference, use [OpenAI](/models/v1/providers/openai).
+- Install Node.js `v22.13.0` or later
 
-## Prerequisites
+## Create a new Express app (optional)
 
-- An existing Express app set up with TypeScript
-- Node.js `v22.13.0` or later
-- An API key from a supported [Model Provider](/models/v1)
+If you already have an Express app, skip to the next step.
 
-## Adding Mastra
+Clone this [boilerplate repository](https://github.com/mastra-ai/express-ts-boilerplate) and install dependencies:
 
-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).
+<Tabs>
+<TabItem value="https" label="HTTPS">
 
 ```bash copy
-npm install mastra@beta @mastra/core@beta @mastra/libsql@beta zod@^3.0.0
-```
-
-If not existent yet, create an `.env` file and add your OpenAI API key:
-
-```bash title=".env" copy
-OPENAI_API_KEY=<your-api-key>
+git clone https://github.com/mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+npm install
 ```
 
-:::note
-
-Each LLM provider uses a different env var. See [Model Providers](/models/v1/providers/) for more information.
-
-:::
-
-Create a Mastra configuration file at `src/mastra/index.ts`:
-
-```ts title="src/mastra/index.ts" copy
-import { Mastra } from "@mastra/core";
+</TabItem>
+<TabItem value="ssh" label="SSH">
 
-export const mastra = new Mastra({});
+```bash copy
+git clone git@github.com:mastra-ai/express-ts-boilerplate.git
+cd express-ts-boilerplate
+npm install
 ```
 
-Create a `weatherTool` that the `weatherAgent` will use at `src/mastra/tools/weather-tool.ts`. It returns a placeholder value inside the `execute()` function (you'd put your API calls in here).
-
-```ts title="src/mastra/tools/weather-tool.ts" copy
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
-
-export const weatherTool = createTool({
-  id: "get-weather",
-  description: "Get current weather for a location",
-  inputSchema: z.object({
-    location: z.string().describe("City name"),
-  }),
-  outputSchema: z.object({
-    output: z.string(),
-  }),
-  execute: async () => {
-    return {
-      output: "The weather is sunny",
-    };
-  },
-});
-```
+</TabItem>
+</Tabs>
 
-Add a `weatherAgent` at `src/mastra/agents/weather-agent.ts`:
-
-```ts title="src/mastra/agents/weather-agent.ts" copy
-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 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
-
-      Use the weatherTool to fetch current weather data.
-`,
-  model: "openai/gpt-5.1",
-  tools: { weatherTool },
-});
-```
+## Initialize Mastra
 
-Lastly, add the `weatherAgent` to `src/mastra/index.ts`:
+Inside your Express project directory, run [`mastra init`](/reference/v1/cli/mastra#mastra-init).
 
-```ts title="src/mastra/index.ts" copy {2, 5}
-import { Mastra } from "@mastra/core";
-import { weatherAgent } from "./agents/weather-agent";
+When prompted, choose a provider (e.g. OpenAI) and enter your key:
 
-export const mastra = new Mastra({
-  agents: { weatherAgent },
-});
+```bash copy
+npx mastra@beta init
 ```
 
-Now you're done with setting up the Mastra boilerplate code and are ready to integrate it into your Express routes.
+This creates a `src/mastra` folder with an example weather agent and the following files:
 
-## Using Mastra with Express
+-	`index.ts` - Mastra config, including memory
+- `tools/weather-tool.ts` - a tool to fetch weather for a given location
+-	`agents/weather-agent.ts`- a weather agent with a prompt that uses the tool
 
-Create an `/api/weather` endpoint that expects a `city` query parameter. The `city` parameter will be passed to the `weatherAgent` when asking it through a prompt.
+You'll pass the `src/mastra/index.ts` file to the Express server adapter later.
 
-You might have a file like this in your existing project:
+## Add server adapter
 
-```ts title="src/server.ts" copy
-import express, { Request, Response } from "express";
+Install the Express server adapter package:
 
-const app = express();
-const port = 3456;
-
-app.get("/", (req: Request, res: Response) => {
-  res.send("Hello, world!");
-});
-
-app.listen(port, () => {
-  console.log(`Server is running at http://localhost:${port}`);
-});
+```bash copy
+npm install @mastra/express@beta
 ```
 
-Adding the `/api/weather` endpoint looks like this:
+Open the Express entry file at `src/index.ts` and add the required import and initialization code:
 
-```ts title="src/server.ts" copy {2, 11-27}
-import express, { Request, Response } from "express";
+```typescript copy {2-3,11-12} title="src/index.ts"
+import express, { type Request, type Response } from "express";
+import { MastraServer } from "@mastra/express";
 import { mastra } from "./mastra";
 
 const app = express();
-const port = 3456;
-
-app.get("/", (req: Request, res: Response) => {
-  res.send("Hello, world!");
-});
-
-app.get("/api/weather", async (req: Request, res: Response) => {
-  const { city } = req.query as { city?: string };
+const PORT = process.env.PORT || 3000;
 
-  if (!city) {
-    return res.status(400).send("Missing 'city' query parameter");
-  }
+// Middleware
+app.use(express.json());
 
-  const agent = mastra.getAgent("weatherAgent");
+const server = new MastraServer({ app, mastra });
+await server.init();
 
-  try {
-    const result = await agent.generate(`What's the weather like in ${city}?`);
-    res.send(result.text);
-  } catch (error) {
-    console.error("Agent error:", error);
-    res.status(500).send("An error occurred while processing your request");
-  }
+// Routes
+app.get("/", (_req: Request, res: Response) => {
+  res.json({ message: "Hello, World!" });
 });
 
-app.listen(port, () => {
-  console.log(`Server is running at http://localhost:${port}`);
+// Start server
+app.listen(PORT, () => {
+  console.log(`Server is running on http://localhost:${PORT}`);
 });
 ```
 
-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.
+The ⁠`MastraServer` is initialized with the existing Express `app` and the root ⁠`mastra` instance. Calling `⁠init()` registers the Mastra middleware and exposes all available Mastra endpoints.
 
-:::note
+## Test your agent
 
-Read the [Agent reference docs](/reference/v1/agents/agent) to learn more.
+By default, Mastra's endpoints are added under the `/api` subpath and use your agent/workflow IDs. The default `weather-agent` created by `mastra init` is available at `/api/agents/weather-agent`.
 
-:::
+Start your Express server:
 
-Start your Express server and visit the `/api/weather` endpoint. For example:
-
-```
-http://localhost:3456/api/weather?city=London
+```bash copy
+npm run start
 ```
 
-You should get a response back similar to this:
+In a separate terminal window, use `curl` to ask the weather agent:
 
-```
-The weather in London is currently sunny. If you need more details like humidity, wind conditions, or precipitation, just let me know!
+```bash copy
+curl -X POST http://localhost:3000/api/agents/weather-agent/generate -H "Content-Type: application/json" -d "{\"messages\":[{\"role\":\"user\",\"content\":\"What is the weather like in Seoul?\"}]}"
 ```
 
-## Running the Agent Server
+## Next steps
 
-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.
+Congratulations on building your Mastra agent with Express! 🎉
 
-Add a script to your `package.json`:
+From here, you can extend the project with your own tools and logic:
 
-```json title="package.json" copy
-{
-  "scripts": {
-    "mastra:dev": "mastra dev"
-  }
-}
-```
+- Learn more about [agents](/docs/v1/agents/overview)
+- Give your agent its own [tools](/docs/v1/agents/using-tools)
+- Add human-like [memory](/docs/v1/agents/agent-memory) to your agent
 
-Start the Mastra dev server:
+When you're ready, read more about how Mastra integrates with Express:
 
-```bash copy
-npm run mastra:dev
-```
+- [Server Adapters](/docs/v1/server/server-adapters)

package/.docs/raw/guides/getting-started/hono.mdx

@@ -0,0 +1,227 @@
+---
+title: "Hono | Frameworks"
+description: "Get started with Mastra and Hono"
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Integrate Mastra in your Hono project
+
+In this guide, you'll build a tool-calling AI agent using Mastra and Hono. Using the [Hono server adapter](/reference/v1/server/hono-adapter), you can expose your agents as HTTP endpoints without writing the routing yourself or running a separate Mastra server.
+
+## Before you begin
+
+- You'll need an API key from a supported [model provider](/models/v1). If you don't have a preference, use [OpenAI](/models/v1/providers/openai).
+- Install Node.js `v22.13.0` or later
+
+## Create a new Hono app (optional)
+
+If you already have a Hono app, skip to the next step.
+
+Run the following command to [create a new Hono app](https://hono.dev/docs/getting-started/basic):
+
+<Tabs groupId="pm">
+<TabItem value="npm" label="npm">
+
+```bash copy
+npm create hono@latest mastra-hono -- --template nodejs --install --pm npm
+```
+
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+
+```bash copy
+pnpm create hono@latest mastra-hono --template nodejs --install --pm pnpm
+```
+
+</TabItem>
+<TabItem value="yarn" label="yarn">
+
+```bash copy
+yarn create hono@latest mastra-hono --template nodejs --install --pm yarn
+```
+
+</TabItem>
+<TabItem value="bun" label="bun">
+
+```bash copy
+bun create hono@latest mastra-hono --template nodejs --install --pm bun
+```
+
+</TabItem>
+</Tabs>
+
+This creates a project called `mastra-hono`, but you can replace it with any name you want.
+
+## Initialize Mastra
+
+Inside your Hono project directory, run [`mastra init`](/reference/v1/cli/mastra#mastra-init).
+
+When prompted, choose a provider (e.g. OpenAI) and enter your key:
+
+<Tabs groupId="pm">
+<TabItem value="npm" label="npm">
+
+```bash copy
+cd mastra-hono
+npx mastra@beta init
+```
+
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+
+```bash copy
+cd mastra-hono
+pnpm dlx mastra@beta init
+```
+
+</TabItem>
+<TabItem value="yarn" label="yarn">
+
+```bash copy
+cd mastra-hono
+yarn dlx mastra@beta init
+```
+
+</TabItem>
+<TabItem value="bun" label="bun">
+
+```bash copy
+cd mastra-hono
+bunx mastra@beta init
+```
+
+</TabItem>
+</Tabs>
+
+This creates a `src/mastra` folder with an example weather agent and the following files:
+
+-	`index.ts` - Mastra config, including memory
+- `tools/weather-tool.ts` - a tool to fetch weather for a given location
+-	`agents/weather-agent.ts`- a weather agent with a prompt that uses the tool
+
+You'll pass the `src/mastra/index.ts` file to the Hono server adapter later.
+
+## Add server adapter
+
+Install the Hono server adapter package:
+
+<Tabs groupId="pm">
+<TabItem value="npm" label="npm">
+
+```bash copy
+npm install @mastra/hono@beta
+```
+
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+
+```bash copy
+pnpm add @mastra/hono@beta
+```
+
+</TabItem>
+<TabItem value="yarn" label="yarn">
+
+```bash copy
+yarn add @mastra/hono@beta
+```
+
+</TabItem>
+<TabItem value="bun" label="bun">
+
+```bash copy
+bun add @mastra/hono@beta
+```
+
+</TabItem>
+</Tabs>
+
+Open the Hono entry file at `src/index.ts` and add the required import and initialization code:
+
+```typescript copy title="src/index.ts" {3-8,10-11,13}
+import { serve } from '@hono/node-server'
+import { Hono } from 'hono'
+import {
+  type HonoBindings,
+  type HonoVariables,
+  MastraServer
+} from '@mastra/hono';
+import { mastra } from './mastra/index.js';
+
+const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>();
+const server = new MastraServer({ app, mastra });
+
+await server.init();
+
+app.get('/', (c) => {
+  return c.text('Hello Hono!')
+})
+
+serve({
+  fetch: app.fetch,
+  port: 3000
+}, (info) => {
+  console.log(`Server is running on http://localhost:${info.port}`)
+})
+```
+
+The ⁠`MastraServer` is initialized with the existing Hono `app` and the root ⁠`mastra` instance. Calling `⁠init()` registers the Mastra middleware and exposes all available Mastra endpoints.
+
+## Test your agent
+
+By default, Mastra's endpoints are added under the `/api` subpath and use your agent/workflow IDs. The default `weather-agent` created by `mastra init` is available at `/api/agents/weather-agent`.
+
+Start your Hono server:
+
+<Tabs groupId="pm">
+<TabItem value="npm" label="npm">
+
+```bash copy
+npm run dev
+```
+
+</TabItem>
+<TabItem value="pnpm" label="pnpm">
+
+```bash copy
+pnpm run dev
+```
+
+</TabItem>
+<TabItem value="yarn" label="yarn">
+
+```bash copy
+yarn run dev
+```
+
+</TabItem>
+<TabItem value="bun" label="bun">
+
+```bash copy
+bun run dev
+```
+
+</TabItem>
+</Tabs>
+
+In a separate terminal window, use `curl` to ask the weather agent:
+
+```bash copy
+curl -X POST http://localhost:3000/api/agents/weather-agent/generate -H "Content-Type: application/json" -d "{\"messages\":[{\"role\":\"user\",\"content\":\"What is the weather like in Seoul?\"}]}"
+```
+
+## Next steps
+
+Congratulations on building your Mastra agent with Hono! 🎉
+
+From here, you can extend the project with your own tools and logic:
+
+- Learn more about [agents](/docs/v1/agents/overview)
+- Give your agent its own [tools](/docs/v1/agents/using-tools)
+- Add human-like [memory](/docs/v1/agents/agent-memory) to your agent
+
+When you're ready, read more about how Mastra integrates with Hono:
+
+- [Server Adapters](/docs/v1/server/server-adapters)