@mastra/mcp-docs-server 0.13.5-alpha.0 → 0.13.6

package/.docs/raw/reference/storage/mssql.mdx

@@ -0,0 +1,108 @@
+---
+title: "MSSQL Storage | Storage System | Mastra Core"
+description: Documentation for the MSSQL storage implementation in Mastra.
+---
+
+# MSSQL Storage
+
+The MSSQL storage implementation provides a production-ready storage solution using Microsoft SQL Server databases.
+
+## Installation
+
+```bash copy
+npm install @mastra/mssql@latest
+```
+
+## Usage
+
+```typescript copy showLineNumbers
+import { MSSQLStore } from "@mastra/mssql";
+
+const storage = new MSSQLStore({
+  connectionString: process.env.DATABASE_URL,
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "connectionString",
+      type: "string",
+      description:
+        "MSSQL connection string (e.g., mssql://user:pass@host:1433/dbname)",
+      isOptional: false,
+    },
+    {
+      name: "schemaName",
+      type: "string",
+      description:
+        "The name of the schema you want the storage to use. Will use the default schema if not provided.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Constructor Examples
+
+You can instantiate `MSSQLStore` in the following ways:
+
+```ts
+import { MSSQLStore } from "@mastra/mssql";
+
+// Using a connection string only
+const store1 = new MSSQLStore({
+  connectionString: "mssql://user:password@localhost:1433/mydb",
+});
+
+// Using a connection string with a custom schema name
+const store2 = new MSSQLStore({
+  connectionString: "mssql://user:password@localhost:1433/mydb",
+  schemaName: "custom_schema", // optional
+});
+
+// Using individual connection parameters
+const store4 = new MSSQLStore({
+  server: "localhost",
+  port: 1433,
+  database: "mydb",
+  user: "user",
+  password: "password",
+});
+
+// Individual parameters with schemaName
+const store5 = new MSSQLStore({
+  server: "localhost",
+  port: 1433,
+  database: "mydb",
+  user: "user",
+  password: "password",
+  schemaName: "custom_schema", // optional
+});
+```
+
+## Additional Notes
+
+### Schema Management
+
+The storage implementation handles schema creation and updates automatically. It creates the following tables:
+
+- `threads`: Stores conversation threads
+- `messages`: Stores individual messages
+- `metadata`: Stores additional metadata for threads and messages
+
+### Direct Database and Pool Access
+
+`MSSQLStore` exposes the mssql connection pool as public fields:
+
+```typescript
+store.pool // mssql connection pool instance
+```
+
+This enables direct queries and custom transaction management. When using these fields:
+- You are responsible for proper connection and transaction handling.
+- Closing the store (`store.close()`) will destroy the associated connection pool.
+- Direct access bypasses any additional logic or validation provided by MSSQLStore methods.
+
+This approach is intended for advanced scenarios where low-level access is required. 

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

@@ -0,0 +1,67 @@
+---
+title: "Custom API Routes"
+description: "Expose additional HTTP endpoints from your Mastra server."
+---
+
+# Custom API Routes
+
+By default Mastra automatically exposes registered agents and workflows via the server. For additional behavior you can define your own HTTP routes.
+
+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 filename="src/mastra/index.ts" copy showLineNumbers
+import { Mastra } from "@mastra/core/mastra";
+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");
+
+          return c.json({ message: "Custom route" });
+        },
+      }),
+    ],
+  },
+});
+```
+
+Once registered, a custom route will be accessible from the root of the server. For example:
+
+```bash
+curl http://localhost:4111/my-custom-route
+```
+
+Each route's handler receives the Hono `Context`. Within the handler you can access the `Mastra` instance to fetch or call agents and workflows.
+
+To add route-specific middleware pass a `middleware` array when calling `registerApiRoute`.
+
+```typescript filename="src/mastra/index.ts" copy showLineNumbers
+import { Mastra } from "@mastra/core/mastra";
+import { registerApiRoute } from "@mastra/core/server";
+
+export const mastra = new Mastra({
+  // ...
+  server: {
+    apiRoutes: [
+      registerApiRoute("/my-custom-route", {
+        method: "GET",
+        middleware: [
+          async (c, next) => {
+            console.log(`${c.req.method} ${c.req.url}`);
+            await next();
+          }
+        ],
+        handler: async (c) => {
+          return c.json({ message: "Custom route with middleware" });
+        }
+      })
+    ]
+  }
+});
+```

package/.docs/raw/server-db/production-server.mdx

@@ -0,0 +1,66 @@
+---
+title: "Create A Mastra Production Server"
+description: "Learn how to configure and deploy a production-ready Mastra server with custom settings for APIs, CORS, and more"
+---
+
+# Create a Mastra Production Server
+
+When deploying your Mastra application to production, it runs as an HTTP server that exposes your agents, workflows, and other functionality as API endpoints. This page covers how to configure and customize the server for a production environment.
+
+## 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
+- API endpoints for all registered workflows
+- Custom API route support
+- Custom middleware support
+- Configuration of timeout
+- Configuration of port
+- Configuration of body limit
+
+See the [Middleware](/docs/server-db/middleware) and
+[Custom API Routes](/docs/server-db/custom-api-routes) pages for details on
+adding additional server behaviour.
+
+## Server configuration
+
+You can configure server `port` and `timeout` in the Mastra instance.
+
+```typescript filename="src/mastra/index.ts" copy showLineNumbers
+import { Mastra } from "@mastra/core/mastra";
+
+export const mastra = new Mastra({
+  // ...
+  server: {
+    port: 3000, // Defaults to 4111
+    timeout: 10000, // Defaults to 30000 (30s)
+  },
+});
+```
+
+The `method` option can be one of `"GET"`, `"POST"`, `"PUT"`,
+`"DELETE"` or `"ALL"`. Using `"ALL"` will cause the handler to be
+invoked for any HTTP method that matches the path.
+
+## Custom CORS Config
+
+Mastra allows you to configure CORS (Cross-Origin Resource Sharing) settings for your server.
+
+```typescript filename="src/mastra/index.ts" copy showLineNumbers
+import { Mastra } from "@mastra/core/mastra";
+
+export const mastra = new Mastra({
+  // ...
+  server: {
+    cors: {
+      origin: ["https://example.com"], // Allow specific origins or '*' for all
+      allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+      allowHeaders: ["Content-Type", "Authorization"],
+      credentials: false,
+    },
+  },
+});
+```

package/.docs/raw/tools-mcp/mcp-overview.mdx

@@ -122,7 +122,30 @@ The tabs help users understand how to connect to various MCP server providers an
 Each tab shows the specific URL patterns and configuration needed for that registry service.
 */}
 
-<Tabs items={["mcp.run", "Composio.dev", "Smithery.ai", "Ampersand"]}>
+<Tabs items={["Klavis AI", "mcp.run", "Composio.dev", "Smithery.ai", "Ampersand"]}>
+  <Tabs.Tab>
+    [Klavis AI](https://klavis.ai) provides hosted, enterprise-authenticated, high-quality MCP servers.
+
+    ```typescript
+    import { MCPClient } from "@mastra/mcp";
+
+    const mcp = new MCPClient({
+      servers: {
+        salesforce: {
+          url: new URL("https://salesforce-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
+        },
+        hubspot: {
+          url: new URL("https://hubspot-mcp-server.klavis.ai/mcp/?instance_id={private-instance-id}"),
+        },
+      },
+    });
+    ```
+
+    Klavis AI offers enterprise-grade authentication and security for production deployments.
+
+    For more details on how to integrate Mastra with Klavis, check out their [documentation](https://docs.klavis.ai/documentation/ai-platform-integration/mastra).
+
+  </Tabs.Tab>
   <Tabs.Tab>
     [mcp.run](https://www.mcp.run/) provides pre-authenticated, managed MCP servers. Tools are grouped into Profiles, each with a unique, signed URL.
 
@@ -313,7 +336,7 @@ Workflows will use their `inputSchema` for the tool's input.
 
 You can define an `outputSchema` for your tools to enforce a specific structure for the tool's output. This is useful for ensuring that the tool returns data in a consistent and predictable format, which can then be validated by the client.
 
-When a tool includes an `outputSchema`, its `execute` function **must** return an object containing a `structuredContent` property. The value of `structuredContent` must conform to the `outputSchema`. Mastra will automatically validate this output on both the server and client sides.
+When a tool includes an `outputSchema`, its `execute` function **must** return an object. The value of the object must conform to the `outputSchema`. Mastra will automatically validate this output on both the server and client sides.
 
 Here's an example of a tool with an `outputSchema`:
 
@@ -331,12 +354,10 @@ export const structuredTool = createTool({
     timestamp: z.string().describe('An ISO timestamp.'),
   }),
   execute: async ({ input }) => {
-    // When outputSchema is defined, you must return a structuredContent object
+    // When outputSchema is defined, you must return an object
     return {
-      structuredContent: {
-        processedInput: `processed: ${input}`,
-        timestamp: new Date().toISOString(),
-      },
+      processedInput: `processed: ${input}`,
+      timestamp: new Date().toISOString(),
     };
   },
 });

package/.docs/raw/workflows/control-flow.mdx

@@ -10,11 +10,13 @@ When you build a workflow, you typically break down operations into smaller task
 - If the schemas match, the `outputSchema` from each step is automatically passed to the `inputSchema` of the next step.
 - If the schemas don't match, use [Input data mapping](./input-data-mapping.mdx) to transform the `outputSchema` into the expected `inputSchema`.
 
-## Sequential
+## Chaining steps with `.then()`
 
-Chain steps to execute in sequence using `.then()`:
+Chain steps to execute sequentially using `.then()`:
 
-```typescript {8-9} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+![Chaining steps with .then()](/image/workflows/workflows-control-flow-then.jpg)
+
+```typescript {8-9,4-5} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -27,31 +29,39 @@ export const testWorkflow = createWorkflow({...})
   .commit();
 ```
 
-## Parallel
+This does what you'd expect: it executes `step1`, then it executes `step2`.
+
+## Simultaneous steps with `.parallel()`
 
-Execute steps in parallel using `.parallel()`:
+Execute steps simultaneously using `.parallel()`:
 
-```typescript {8} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+![Concurrent steps with .parallel()](/image/workflows/workflows-control-flow-parallel.jpg)
+
+```typescript {8,4-5} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
 const step1 = createStep({...});
 const step2 = createStep({...});
+const step3 = createStep({...});
 
 export const testWorkflow = createWorkflow({...})
   .parallel([step1, step2])
+  .then(step3)
   .commit();
 ```
 
-This executes all steps in the array concurrently, then continues to the next step after all parallel steps complete.
+This executes `step1` and `step2` concurrently, then continues to `step3` after both complete.
 
 > See [Parallel Execution with Steps](/examples/workflows/parallel-steps) for more information.
 
-## Branch
+## Conditional logic with `.branch()`
+
+Execute steps conditionally using `.branch()`:
 
-Create conditional branches using `.branch()`:
+![Conditional branching with .branch()](/image/workflows/workflows-control-flow-branch.jpg)
 
-```typescript {8-11} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {8-11,4-5} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
@@ -60,8 +70,8 @@ const greaterThanStep = createStep({...});
 
 export const testWorkflow = createWorkflow({...})
   .branch([
-    [async ({ inputData: { some_value } }) => some_value <= 9, lessThanStep],
-    [async ({ inputData: { some_value } }) => some_value >= 10, greaterThanStep]
+    [async ({ inputData: { value } }) => (value < 9), lessThanStep],
+    [async ({ inputData: { value } }) => (value >= 9), greaterThanStep]
   ])
   .commit();
 ```
@@ -70,19 +80,20 @@ Branch conditions are evaluated sequentially, but steps with matching conditions
 
 > See [Workflow with Conditional Branching](/examples/workflows/conditional-branching) for more information.
 
-## Loops
+## Looping steps
 
 Workflows support two types of loops. When looping a step, or any step-compatible construct like a nested workflow, the initial `inputData` is sourced from the output of the previous step.
 
-To ensure compatibility, the loop’s initial input must either:
+To ensure compatibility, the loop’s initial input must either match the shape of the previous step’s output, or be explicitly transformed using the `map` function.
 
 - Match the shape of the previous step’s output, or
 - Be explicitly transformed using the `map` function.
 
+### Repeating with `.dowhile()`
 
-### Dowhile
+Executes step repeatedly while a condition is true.
 
-Executes a step repeatedly while a condition is true.
+![Repeating with .dowhile()](/image/workflows/workflows-control-flow-dowhile.jpg)
 
 ```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
@@ -95,9 +106,11 @@ export const testWorkflow = createWorkflow({...})
   .commit();
 ```
 
-### Dountil
+### Repeating with `.dountil()`
 
-Executes a step repeatedly until a condition becomes true.
+Executes step repeatedly until a condition becomes true.
+
+![Repeating with .dountil()](/image/workflows/workflows-control-flow-dountil.jpg)
 
 ```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
@@ -110,11 +123,12 @@ export const testWorkflow = createWorkflow({...})
   .commit();
 ```
 
-
-### Foreach
+### Repeating with `.foreach()`
 
 Sequentially executes the same step for each item from the `inputSchema`.
 
+![Repeating with .foreach()](/image/workflows/workflows-control-flow-foreach.jpg)
+
 ```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
@@ -126,132 +140,116 @@ export const testWorkflow = createWorkflow({...})
   .commit();
 ```
 
-### Early exit
+#### Setting concurrency limits
 
-You can bail out of a workflow execution successfully by calling `bail()` in a step. This returns whatever payload is passed to the `bail()` function as the result of the workflow.
+Use `concurrency` to execute steps in parallel with a limit on the number of concurrent executions.
 
 ```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
-const step1 = createStep({
-  id: 'step1',
-  execute: async ({ bail, inputData }) => {
-    return bail({ result: 'bailed' });
-  },
-  inputSchema: z.object({ value: z.string() }),
-  outputSchema: z.object({ result: z.string() }),
-});
+const mapStep = createStep({...})
 
 export const testWorkflow = createWorkflow({...})
-  .then(step1)
+  .foreach(mapStep, { concurrency: 2 })
   .commit();
 ```
 
-Unsuccessful bails happen through throwing an error in the step.
+## Using a nested workflow
 
-```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+Use a nested workflow as a step by passing it to `.then()`. This runs each of its steps in sequence as part of the parent workflow.
+
+```typescript {4,7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
-const step1 = createStep({
-  id: 'step1',
-  execute: async ({ bail, inputData }) => {
-    throw new Error('bailed');
-  },
-  inputSchema: z.object({ value: z.string() }),
-  outputSchema: z.object({ result: z.string() }),
-});
+export const nestedWorkflow = createWorkflow({...})
 
 export const testWorkflow = createWorkflow({...})
-  .then(step1)
+  .then(nestedWorkflow)
   .commit();
 ```
-#### Example Run Instance
-
-The following example demonstrates how to start a run with multiple inputs. Each input will pass through the `mapStep` sequentially.
-
-```typescript {6} filename="src/test-workflow.ts" showLineNumbers copy
-import { mastra } from "./mastra";
-
-const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
-
-const result = await run.start({
-  inputData: [{ number: 10 }, { number: 100 }, { number: 200 }]
-});
-```
-
-To execute this run from your terminal:
-
-```bash copy
-npx tsx src/test-workflow.ts
-```
 
-#### Concurrency
+## Cloning a workflow
 
-Optionally, using `concurrency` allows you to execute steps in parallel with a limit on the number of concurrent executions.
+Use `cloneWorkflow` to duplicate an existing workflow. This lets you reuse its structure while overriding parameters like `id`.
 
-```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
+```typescript {6,10} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep, cloneWorkflow } from "@mastra/core/workflows";
 import { z } from "zod";
 
-const mapStep = createStep({...})
+const step1 = createStep({...});
+const parentWorkflow = createWorkflow({...})
+const clonedWorkflow = cloneWorkflow(parentWorkflow, { id: "cloned-workflow" });
 
 export const testWorkflow = createWorkflow({...})
-  .foreach(mapStep, { concurrency: 2 })
+  .then(step1)
+  .then(clonedWorkflow)
   .commit();
 ```
 
-## Parallel Workflows
+## Exiting early with `bail()`
 
-Workflows themselves can also be executed in parallel.
+Use `bail()` in a step to exit early with a successful result. This returns the provided payload as the step output and ends workflow execution.
 
-```typescript {4-5,8} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
-const workflow1 = createWorkflow({...});
-const workflow2 = createWorkflow({...});
+const step1 = createStep({
+  id: 'step1',
+  execute: async ({ bail }) => {
+    return bail({ result: 'bailed' });
+  },
+  inputSchema: z.object({ value: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+});
 
 export const testWorkflow = createWorkflow({...})
-  .parallel([workflow1, workflow2])
+  .then(step1)
   .commit();
 ```
 
-Parallel steps receive previous step results as input. Their outputs are passed into the next step input as an object where the key is the step `id` and the value is the step `output`.
+## Exiting early with `Error()`
 
-## Nested Workflows
+Use `throw new Error()` in a step to exit with an error.
 
-In the example below, `nestedWorkflow` is used as a step within `testWorkflow`. The `testWorkflow` uses `step1` whilst the `nestedWorkflow` composes `step2` and `step3`
-
-
-```typescript {4,7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {7} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { createWorkflow, createStep } from "@mastra/core/workflows";
 import { z } from "zod";
 
-export const nestedWorkflow = createWorkflow({...})
+const step1 = createStep({
+  id: 'step1',
+  execute: async () => {
+    throw new Error('bailed');
+  },
+  inputSchema: z.object({ value: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+});
 
 export const testWorkflow = createWorkflow({...})
-  .then(nestedWorkflow)
+  .then(step1)
   .commit();
 ```
 
-When using `.branch()` or `.parallel()` to build more complex control flows, executing more than one step requires wrapping those steps in a nested workflow, along with a clear definition of how they should be executed.
+This throws an error from the step and stops workflow execution, returning the error as the result.
 
+## Example Run Instance
 
-## Cloned Workflows
+The following example demonstrates how to start a run with multiple inputs. Each input will pass through the `mapStep` sequentially.
 
-In the example below, `clonedWorkflow` is a clone of `workflow1` and is used as a step within `testWorkflow`. The `clonedWorkflow` is run sequentially after `step1`.
+```typescript {6} filename="src/test-workflow.ts" showLineNumbers copy
+import { mastra } from "./mastra";
 
-```typescript {5,9} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep, cloneWorkflow } from "@mastra/core/workflows";
-import { z } from "zod";
+const run = await mastra.getWorkflow("testWorkflow").createRunAsync();
 
-const step1 = createStep({...});
-const clonedWorkflow = cloneWorkflow(step1, { id: "cloned-workflow" });
+const result = await run.start({
+  inputData: [{ number: 10 }, { number: 100 }, { number: 200 }]
+});
+```
 
-export const testWorkflow = createWorkflow({...})
-  .then(step1)
-  .then(clonedWorkflow)
-  .commit();
+To execute this run from your terminal:
+
+```bash copy
+npx tsx src/test-workflow.ts
 ```