@mastra/mcp-docs-server 0.13.20 → 0.13.21-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/.docs/organized/changelogs/%40internal%2Fstorage-test-utils.md +8 -8
  2. package/.docs/organized/changelogs/%40internal%2Ftypes-builder.md +2 -0
  3. package/.docs/organized/changelogs/%40mastra%2Fagent-builder.md +8 -0
  4. package/.docs/organized/changelogs/%40mastra%2Fclient-js.md +30 -30
  5. package/.docs/organized/changelogs/%40mastra%2Fcloud.md +13 -13
  6. package/.docs/organized/changelogs/%40mastra%2Fcore.md +51 -51
  7. package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloud.md +29 -29
  8. package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloudflare.md +17 -17
  9. package/.docs/organized/changelogs/%40mastra%2Fdeployer-netlify.md +17 -17
  10. package/.docs/organized/changelogs/%40mastra%2Fdeployer-vercel.md +17 -17
  11. package/.docs/organized/changelogs/%40mastra%2Fdeployer.md +32 -32
  12. package/.docs/organized/changelogs/%40mastra%2Fevals.md +12 -12
  13. package/.docs/organized/changelogs/%40mastra%2Flibsql.md +10 -10
  14. package/.docs/organized/changelogs/%40mastra%2Fmcp-docs-server.md +24 -24
  15. package/.docs/organized/changelogs/%40mastra%2Fmemory.md +10 -10
  16. package/.docs/organized/changelogs/%40mastra%2Fpg.md +10 -10
  17. package/.docs/organized/changelogs/%40mastra%2Fplayground-ui.md +31 -31
  18. package/.docs/organized/changelogs/%40mastra%2Fschema-compat.md +6 -0
  19. package/.docs/organized/changelogs/%40mastra%2Fserver.md +30 -30
  20. package/.docs/organized/changelogs/create-mastra.md +11 -11
  21. package/.docs/organized/changelogs/mastra.md +31 -31
  22. package/.docs/organized/code-examples/agent.md +34 -9
  23. package/.docs/organized/code-examples/ai-sdk-v5.md +16 -14
  24. package/.docs/organized/code-examples/heads-up-game.md +3 -3
  25. package/.docs/raw/auth/clerk.mdx +142 -0
  26. package/.docs/raw/getting-started/installation.mdx +3 -1
  27. package/.docs/raw/getting-started/model-providers.mdx +31 -31
  28. package/.docs/raw/observability/ai-tracing.mdx +123 -24
  29. package/.docs/raw/reference/agents/ChunkType.mdx +857 -0
  30. package/.docs/raw/reference/agents/MastraModelOutput.mdx +321 -0
  31. package/.docs/raw/reference/agents/generateVNext.mdx +519 -0
  32. package/.docs/raw/reference/agents/streamVNext.mdx +6 -20
  33. package/.docs/raw/reference/auth/clerk.mdx +71 -0
  34. package/.docs/raw/reference/scorers/answer-similarity.mdx +179 -0
  35. package/.docs/raw/scorers/off-the-shelf-scorers.mdx +1 -0
  36. package/.docs/raw/server-db/production-server.mdx +27 -2
  37. package/.docs/raw/tools-mcp/mcp-overview.mdx +144 -159
  38. package/.docs/raw/workflows/control-flow.mdx +1 -1
  39. package/.docs/raw/workflows/suspend-and-resume.mdx +5 -0
  40. package/CHANGELOG.md +16 -0
  41. package/dist/stdio.js +11 -4
  42. package/dist/tools/docs.d.ts.map +1 -1
  43. package/package.json +4 -4
  44. /package/.docs/raw/reference/{templates.mdx → templates/overview.mdx} +0 -0
@@ -0,0 +1,179 @@
1
+ ---
2
+ title: "Reference: Answer Similarity | Scorers | Mastra Docs"
3
+ description: Documentation for the Answer Similarity Scorer in Mastra, which compares agent outputs against ground truth answers for CI/CD testing.
4
+ ---
5
+
6
+ # Answer Similarity Scorer
7
+
8
+ The `createAnswerSimilarityScorer()` function creates a scorer that evaluates how similar an agent's output is to a ground truth answer. This scorer is specifically designed for CI/CD testing scenarios where you have expected answers and want to ensure consistency over time.
9
+
10
+ For usage examples, see the [Answer Similarity Examples](/examples/scorers/answer-similarity).
11
+
12
+ ## Parameters
13
+
14
+ <PropertiesTable
15
+ content={[
16
+ {
17
+ name: "model",
18
+ type: "LanguageModel",
19
+ required: true,
20
+ description: "The language model used to evaluate semantic similarity between outputs and ground truth.",
21
+ },
22
+ {
23
+ name: "options",
24
+ type: "AnswerSimilarityOptions",
25
+ required: false,
26
+ description: "Configuration options for the scorer.",
27
+ },
28
+ ]}
29
+ />
30
+
31
+ ### AnswerSimilarityOptions
32
+
33
+ <PropertiesTable
34
+ content={[
35
+ {
36
+ name: "requireGroundTruth",
37
+ type: "boolean",
38
+ required: false,
39
+ defaultValue: "true",
40
+ description: "Whether to require ground truth for evaluation. If false, missing ground truth returns score 0.",
41
+ },
42
+ {
43
+ name: "semanticThreshold",
44
+ type: "number",
45
+ required: false,
46
+ defaultValue: "0.8",
47
+ description: "Weight for semantic matches vs exact matches (0-1).",
48
+ },
49
+ {
50
+ name: "exactMatchBonus",
51
+ type: "number",
52
+ required: false,
53
+ defaultValue: "0.2",
54
+ description: "Additional score bonus for exact matches (0-1).",
55
+ },
56
+ {
57
+ name: "missingPenalty",
58
+ type: "number",
59
+ required: false,
60
+ defaultValue: "0.15",
61
+ description: "Penalty per missing key concept from ground truth.",
62
+ },
63
+ {
64
+ name: "contradictionPenalty",
65
+ type: "number",
66
+ required: false,
67
+ defaultValue: "1.0",
68
+ description: "Penalty for contradictory information. High value ensures wrong answers score near 0.",
69
+ },
70
+ {
71
+ name: "extraInfoPenalty",
72
+ type: "number",
73
+ required: false,
74
+ defaultValue: "0.05",
75
+ description: "Mild penalty for extra information not present in ground truth (capped at 0.2).",
76
+ },
77
+ {
78
+ name: "scale",
79
+ type: "number",
80
+ required: false,
81
+ defaultValue: "1",
82
+ description: "Score scaling factor.",
83
+ },
84
+ ]}
85
+ />
86
+
87
+ This function returns an instance of the MastraScorer class. The `.run()` method accepts the same input as other scorers (see the [MastraScorer reference](./mastra-scorer)), but **requires ground truth** to be provided in the run object.
88
+
89
+ ## .run() Returns
90
+
91
+ <PropertiesTable
92
+ content={[
93
+ {
94
+ name: "runId",
95
+ type: "string",
96
+ description: "The id of the run (optional).",
97
+ },
98
+ {
99
+ name: "score",
100
+ type: "number",
101
+ description: "Similarity score between 0-1 (or 0-scale if custom scale used). Higher scores indicate better similarity to ground truth.",
102
+ },
103
+ {
104
+ name: "reason",
105
+ type: "string",
106
+ description: "Human-readable explanation of the score with actionable feedback.",
107
+ },
108
+ {
109
+ name: "preprocessStepResult",
110
+ type: "object",
111
+ description: "Extracted semantic units from output and ground truth.",
112
+ },
113
+ {
114
+ name: "analyzeStepResult",
115
+ type: "object",
116
+ description: "Detailed analysis of matches, contradictions, and extra information.",
117
+ },
118
+ {
119
+ name: "preprocessPrompt",
120
+ type: "string",
121
+ description: "The prompt used for semantic unit extraction.",
122
+ },
123
+ {
124
+ name: "analyzePrompt",
125
+ type: "string",
126
+ description: "The prompt used for similarity analysis.",
127
+ },
128
+ {
129
+ name: "generateReasonPrompt",
130
+ type: "string",
131
+ description: "The prompt used for generating the explanation.",
132
+ },
133
+ ]}
134
+ />
135
+
136
+ ## Usage with runExperiment
137
+
138
+ This scorer is designed for use with `runExperiment` for CI/CD testing:
139
+
140
+ ```typescript
141
+ import { runExperiment } from '@mastra/core/scores';
142
+ import { createAnswerSimilarityScorer } from '@mastra/evals/scorers/llm';
143
+
144
+ const scorer = createAnswerSimilarityScorer({ model });
145
+
146
+ await runExperiment({
147
+ data: [
148
+ {
149
+ input: "What is the capital of France?",
150
+ groundTruth: "Paris is the capital of France"
151
+ }
152
+ ],
153
+ scorers: [scorer],
154
+ target: myAgent,
155
+ onItemComplete: ({ scorerResults }) => {
156
+ // Assert similarity score meets threshold
157
+ expect(scorerResults['Answer Similarity Scorer'].score).toBeGreaterThan(0.8);
158
+ }
159
+ });
160
+ ```
161
+
162
+ ## Key Features
163
+
164
+ - **Semantic Analysis**: Uses LLM to extract and compare semantic units rather than simple string matching
165
+ - **Contradiction Detection**: Identifies factually incorrect information and scores it near 0
166
+ - **Flexible Matching**: Supports exact, semantic, partial, and missing match types
167
+ - **CI/CD Ready**: Designed for automated testing with ground truth comparison
168
+ - **Actionable Feedback**: Provides specific explanations of what matched and what needs improvement
169
+
170
+ ## Scoring Algorithm
171
+
172
+ The scorer uses a multi-step process:
173
+
174
+ 1. **Extract**: Breaks down output and ground truth into semantic units
175
+ 2. **Analyze**: Compares units and identifies matches, contradictions, and gaps
176
+ 3. **Score**: Calculates weighted similarity with penalties for contradictions
177
+ 4. **Reason**: Generates human-readable explanation
178
+
179
+ Score calculation: `max(0, base_score - contradiction_penalty - missing_penalty - extra_info_penalty) × scale`
@@ -14,6 +14,7 @@ Mastra provides a comprehensive set of built-in scorers for evaluating AI output
14
14
  These scorers evaluate how correct, truthful, and complete your agent's answers are:
15
15
 
16
16
  - [`answer-relevancy`](/reference/scorers/answer-relevancy): Evaluates how well responses address the input query (`0-1`, higher is better)
17
+ - [`answer-similarity`](/reference/scorers/answer-similarity): Compares agent outputs against ground truth answers for CI/CD testing using semantic analysis (`0-1`, higher is better)
17
18
  - [`faithfulness`](/reference/scorers/faithfulness): Measures how accurately responses represent provided context (`0-1`, higher is better)
18
19
  - [`hallucination`](/reference/scorers/hallucination): Detects factual contradictions and unsupported claims (`0-1`, lower is better)
19
20
  - [`completeness`](/reference/scorers/completeness): Checks if responses include all necessary information (`0-1`, higher is better)
@@ -7,7 +7,7 @@ description: "Learn how to configure and deploy a production-ready Mastra server
7
7
 
8
8
  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.
9
9
 
10
- ## Server Architecture
10
+ ## Server architecture
11
11
 
12
12
  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.
13
13
 
@@ -45,7 +45,32 @@ The `method` option can be one of `"GET"`, `"POST"`, `"PUT"`,
45
45
  `"DELETE"` or `"ALL"`. Using `"ALL"` will cause the handler to be
46
46
  invoked for any HTTP method that matches the path.
47
47
 
48
- ## Custom CORS Config
48
+ ## TypeScript configuration
49
+
50
+ Mastra requires `module` and `moduleResolution` values that support modern Node.js versions. Older settings like `CommonJS` or `node` are incompatible with Mastra’s packages and will cause resolution errors.
51
+
52
+ ```json {4-5} filename="tsconfig.json" copy
53
+ {
54
+ "compilerOptions": {
55
+ "target": "ES2022",
56
+ "module": "ES2022",
57
+ "moduleResolution": "bundler",
58
+ "esModuleInterop": true,
59
+ "forceConsistentCasingInFileNames": true,
60
+ "strict": true,
61
+ "skipLibCheck": true,
62
+ "noEmit": true,
63
+ "outDir": "dist"
64
+ },
65
+ "include": [
66
+ "src/**/*"
67
+ ]
68
+ }
69
+ ```
70
+
71
+ > This TypeScript configuration is optimized for Mastra projects, using modern module resolution and strict type checking.
72
+
73
+ ## CORS configuration
49
74
 
50
75
  Mastra allows you to configure CORS (Cross-Origin Resource Sharing) settings for your server.
51
76
 
@@ -7,108 +7,177 @@ import { Tabs } from "nextra/components";
7
7
 
8
8
  # MCP Overview
9
9
 
10
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open standard designed to let AI models discover and interact with external tools and resources. Think of it as a universal plugin system for AI agents, allowing them to use tools regardless of the language they were written in or where they are hosted.
10
+ Mastra supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open standard for connecting AI agents to external tools and resources. It serves as a universal plugin system, enabling agents to call tools regardless of language or hosting environment.
11
11
 
12
- Mastra uses MCP to connect agents to external tool servers.
12
+ Mastra can also be used to author MCP servers, exposing agents, tools, and other structured resources via the MCP interface. These can then be accessed by any system or agent that supports the protocol.
13
13
 
14
- ## Use third-party tools with an MCP Client
14
+ Mastra currently supports two MCP classes:
15
15
 
16
- Mastra provides the `MCPClient` class to manage connections to one or more MCP servers and access their tools.
16
+ 1. **`MCPClient`**: Connects to one or many MCP servers to access their tools, resources, prompts, and handle elicitation requests.
17
+ 2. **`MCPServer`**: Exposes Mastra tools, agents, workflows, prompts, and resources to MCP compatible clients.
17
18
 
18
- ### Installation
19
+ ## Getting started
19
20
 
20
- If you haven't already, install the Mastra MCP package:
21
+ To use MCP, install the required dependency:
21
22
 
22
- ```bash npm2yarn copy
23
+ ```bash
23
24
  npm install @mastra/mcp@latest
24
25
  ```
25
26
 
26
- ### Registering the MCPServer
27
+ ## Configuring `MCPClient`
27
28
 
28
- Register your MCP server with Mastra to enable logging and access to configured tools and integrations:
29
+ The `MCPClient` connects Mastra primitives to external MCP servers, which can be local packages (invoked using `npx`) or remote HTTP(S) endpoints. Each server must be configured with either a `command` or a `url`, depending on how it's hosted.
29
30
 
30
- ```ts showLineNumbers filename="src/mastra/index.ts" copy
31
- import { Mastra } from "@mastra/core";
32
- import { myMcpServer } from "./mcpServers";
33
-
34
- export const mastra = new Mastra({
35
- mcpServers: { myMcpServer },
36
- });
37
- ```
38
-
39
- ### Configuring `MCPClient`
40
-
41
- You configure `MCPClient` with a map of servers you want to connect to. It supports connections via subprocess (Stdio) or HTTP (Streamable HTTP with SSE fallback).
42
-
43
- ```typescript
31
+ ```typescript filename="src/mastra/mcp/test-mcp-client.ts" showLineNumbers copy
44
32
  import { MCPClient } from "@mastra/mcp";
45
33
 
46
- const mcp = new MCPClient({
34
+ export const testMcpClient = new MCPClient({
35
+ id: "test-mcp-client",
47
36
  servers: {
48
- // Stdio example
49
- sequential: {
37
+ wikipedia: {
50
38
  command: "npx",
51
- args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
39
+ args: ["-y", "wikipedia-mcp"]
52
40
  },
53
- // HTTP example
54
41
  weather: {
55
- url: new URL("http://localhost:8080/mcp"),
56
- requestInit: {
57
- headers: {
58
- Authorization: "Bearer your-token",
59
- },
60
- },
42
+ url: new URL(`https://server.smithery.ai/@smithery-ai/national-weather-service/mcp?api_key=${process.env.SMITHERY_API_KEY}`)
61
43
  },
62
- },
44
+ }
63
45
  });
64
46
  ```
65
47
 
66
- For detailed configuration options, see the [`MCPClient` reference documentation](/reference/tools/mcp-client).
48
+ > See [MCPClient](../../reference/tools/mcp-client.mdx) for a full list of configuration options.
49
+
50
+ ## Using `MCPClient` with an agent
51
+
52
+ To use tools from an MCP server in an agent, import your `MCPClient` and call `.getTools()` in the `tools` parameter. This loads from the defined MCP servers, making them available to the agent.
67
53
 
68
- ### Static vs Dynamic Tool Configurations
54
+ ```typescript {4,16} filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
55
+ import { openai } from "@ai-sdk/openai";
56
+ import { Agent } from "@mastra/core/agent";
57
+
58
+ import { testMcpClient } from "../mcp/test-mcp-client";
59
+
60
+ export const testAgent = new Agent({
61
+ name: "Test Agent",
62
+ description: "You are a helpful AI assistant",
63
+ instructions: `
64
+ You are a helpful assistant that has access to the following MCP Servers.
65
+ - Wikipedia MCP Server
66
+ - US National Weather Service
67
+
68
+ Answer questions using the information you find using the MCP Servers.`,
69
+ model: openai("gpt-4o-mini"),
70
+ tools: await testMcpClient.getTools()
71
+ });
72
+ ```
73
+ > See the [Agent Class](../../reference/agents/agent.mdx) for a full list of configuration options.
74
+
75
+ ## Configuring `MCPServer`
76
+
77
+ To expose agents, tools, and workflows from your Mastra application to external systems over HTTP(S) use the `MCPServer` class. This makes them accessible to any system or agent that supports the protocol.
78
+
79
+ ```typescript filename="src/mastra/mcp/test-mcp-server.ts" showLineNumbers copy
80
+ import { MCPServer } from "@mastra/mcp";
81
+
82
+ import { testAgent } from "../agents/test-agent";
83
+ import { testWorkflow } from "../workflows/test-workflow";
84
+ import { testTool } from "../tools/test-tool";
85
+
86
+ export const testMcpServer = new MCPServer({
87
+ id: "test-mcp-server",
88
+ name: "Test Server",
89
+ version: "1.0.0",
90
+ agents: { testAgent },
91
+ tools: { testTool },
92
+ workflows: { testWorkflow }
93
+ });
94
+ ```
95
+
96
+ > See [MCPServer](../../reference/tools/mcp-server.mdx) for a full list of configuration options.
97
+
98
+ ## Registering an `MCPServer`
99
+
100
+ To make an MCP server available to other systems or agents that support the protocol, register it in the main `Mastra` instance using `mcpServers`.
101
+
102
+ ```typescript filename="src/mastra/index.ts" showLineNumbers copy
103
+ import { Mastra } from "@mastra/core/mastra";
104
+
105
+ import { testMcpServer } from "./mcp/test-mcp-server";
106
+
107
+ export const mastra = new Mastra({
108
+ // ...
109
+ mcpServers: { testMcpServer }
110
+ });
111
+ ```
112
+
113
+ ## Static and dynamic tools
69
114
 
70
115
  `MCPClient` offers two approaches to retrieving tools from connected servers, suitable for different application architectures:
71
116
 
72
- | Feature | Static Configuration (`await mcp.getTools()`) | Dynamic Configuration (`await mcp.getToolsets()`) |
73
- | :---------------- | :-------------------------------------------- | :------------------------------------------------- |
74
- | **Use Case** | Single-user, static config (e.g., CLI tool) | Multi-user, dynamic config (e.g., SaaS app) |
75
- | **Configuration** | Fixed at agent initialization | Per-request, dynamic |
76
- | **Credentials** | Shared across all uses | Can vary per user/request |
77
- | **Agent Setup** | Tools added in `Agent` constructor | Tools passed in `generate()` or `stream()` options |
117
+ | Feature | Static Configuration (`await mcp.getTools()`) | Dynamic Configuration (`await mcp.getToolsets()`) |
118
+ | :---------------- | :---------------------------------------------| :--------------------------------------------------- |
119
+ | **Use Case** | Single-user, static config (e.g., CLI tool) | Multi-user, dynamic config (e.g., SaaS app) |
120
+ | **Configuration** | Fixed at agent initialization | Per-request, dynamic |
121
+ | **Credentials** | Shared across all uses | Can vary per user/request |
122
+ | **Agent Setup** | Tools added in `Agent` constructor | Tools passed in `.generate()` or `.stream()` options |
123
+
124
+ ### Static tools
125
+
126
+ Use the `.getTools()` method to fetch tools from all configured MCP servers. This is suitable when configuration (such as API keys) is static and consistent across users or requests. Call it once and pass the result to the `tools` property when defining your agent.
127
+
128
+ > See [getTools()](../../reference/tools/mcp-client.mdx#gettools) for more information.
129
+
130
+ ```typescript {8} filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
131
+ import { openai } from "@ai-sdk/openai";
132
+ import { Agent } from "@mastra/core/agent";
133
+
134
+ import { testMcpClient } from "../mcp/test-mcp-client";
78
135
 
79
- - **Static Configuration (`getTools()`):** Fetches all tools from all configured servers. Best when the tool configuration (like API keys) is static and shared across all users or requests. You typically call this once and pass the result to the `tools` property when defining your `Agent`.
80
- [Reference: `getTools()`](/reference/tools/mcp-client#gettools)
136
+ export const testAgent = new Agent({
137
+ // ...
138
+ tools: await testMcpClient.getTools()
139
+ });
140
+ ```
141
+
142
+ ### Dynamic tools
81
143
 
82
- ```typescript
83
- import { Agent } from "@mastra/core/agent";
84
- // ... mcp client setup
144
+ Use the `.getToolsets()` method when tool configuration may vary by request or user, such as in a multi-tenant system where each user provides their own API key. This method returns toolsets that can be passed to the `toolsets` option in the agent's `.generate()` or `.stream()` calls.
85
145
 
86
- const agent = new Agent({
87
- // ... other agent config
88
- tools: await mcp.getTools(),
146
+ ```typescript {5-16,21} showLineNumbers copy
147
+ import { MCPClient } from "@mastra/mcp";
148
+ import { mastra } from "./mastra";
149
+
150
+ async function handleRequest(userPrompt: string, userApiKey: string) {
151
+ const userMcp = new MCPClient({
152
+ servers: {
153
+ weather: {
154
+ url: new URL("http://localhost:8080/mcp"),
155
+ requestInit: {
156
+ headers: {
157
+ Authorization: `Bearer ${userApiKey}`
158
+ }
159
+ }
160
+ }
161
+ }
89
162
  });
90
- ```
91
163
 
92
- - **Dynamic Configuration (`getToolsets()`):** Designed for scenarios where configuration might change per request or per user (e.g., different API keys for different tenants in a multi-user application). You pass the result of `getToolsets()` to the `toolsets` option in the agent's `generate()` or `stream()` method.
93
- [Reference: `getToolsets()`](/reference/tools/mcp-client#gettoolsets)
164
+ const agent = mastra.getAgent("testAgent");
94
165
 
95
- ```typescript
96
- import { Agent } from "@mastra/core/agent";
97
- // ... agent setup without tools initially
166
+ const response = await agent.generate(userPrompt, {
167
+ toolsets: await userMcp.getToolsets()
168
+ });
169
+
170
+ await userMcp.disconnect();
171
+
172
+ return Response.json({
173
+ data: response.text
174
+ });
175
+ }
176
+ ```
177
+
178
+ > See [getToolsets()](../../reference/tools/mcp-client.mdx#gettoolsets) for more information.
98
179
 
99
- async function handleRequest(userPrompt: string, userApiKey: string) {
100
- const userMcp = new MCPClient({
101
- /* config with userApiKey */
102
- });
103
- const toolsets = await userMcp.getToolsets();
104
180
 
105
- const response = await agent.stream(userPrompt, {
106
- toolsets, // Pass dynamic toolsets
107
- });
108
- // ... handle response
109
- await userMcp.disconnect();
110
- }
111
- ```
112
181
 
113
182
  ## Connecting to an MCP registry
114
183
 
@@ -239,7 +308,7 @@ Each tab shows the specific URL patterns and configuration needed for that regis
239
308
  <Tabs.Tab>
240
309
 
241
310
  [Ampersand](https://withampersand.com?utm_source=mastra-docs) offers an [MCP Server](https://docs.withampersand.com/mcp) that allows you to connect your agent to 150+ integrations with SaaS products like Salesforce, Hubspot, and Zendesk.
242
-
311
+
243
312
 
244
313
  ```typescript
245
314
 
@@ -261,7 +330,7 @@ Each tab shows the specific URL patterns and configuration needed for that regis
261
330
 
262
331
  ```typescript
263
332
  // If you prefer to run the MCP server locally:
264
-
333
+
265
334
  import { MCPClient } from "@mastra/mcp";
266
335
 
267
336
  // MCPClient with Ampersand MCP Server using stdio transport
@@ -294,92 +363,8 @@ Each tab shows the specific URL patterns and configuration needed for that regis
294
363
  </Tabs.Tab>
295
364
  </Tabs>
296
365
 
297
- ## Share your tools with an MCP server
298
-
299
- If you have created your own Mastra tools, you can expose them to any MCP-compatible client using Mastra's `MCPServer` class.
300
-
301
- Similarly, Mastra `Agent` and `Workflow` instances can also be exposed as tools via `MCPServer`. This allows other MCP clients to interact with your agents by "asking" them questions or run your workflows. Each agent provided in the `MCPServer` configuration will be converted into a tool named `ask_<agentKey>`, using the agent's `description` property. Each workflow will be converted into a tool named `run_<workflowKey>`, using its `inputSchema` and `description`.
302
-
303
- This allows others to use your tools, agents, and workflows without needing direct access to your codebase.
304
-
305
- ### Using `MCPServer`
306
-
307
- You initialize `MCPServer` with a name, version, and the Mastra tools, agents, and/or workflows you want to share.
308
-
309
- ```typescript
310
- import { MCPServer } from "@mastra/mcp";
311
- import { Agent } from "@mastra/core/agent";
312
- import { openai } from "@ai-sdk/openai";
313
- import { weatherTool } from "./tools"; // Your Mastra tool
314
- import { weatherAgent } from "./agents"; // Your Mastra Agent
315
- import { dataWorkflow } from "./workflows"; // Your Mastra Workflow
316
-
317
- const server = new MCPServer({
318
- name: "My Custom Server",
319
- version: "1.0.0",
320
- tools: { weatherTool }, // Provide your tool(s) here
321
- agents: { weatherAgent }, // Provide your agent(s) here
322
- workflows: { dataWorkflow }, // Provide your workflow(s) here
323
- });
324
-
325
- // Start the server (e.g., using stdio for a CLI tool)
326
- // await server.startStdio();
327
-
328
- // Or integrate with an HTTP server using startSSE()
329
- // See MCPServer reference for details
330
- ```
331
-
332
- For an agent to be exposed as a tool, it must have a non-empty `description` string. Similarly, for a workflow to be exposed, its `description` must also be a non-empty string. If the description is missing or empty for either, `MCPServer` will throw an error during initialization.
333
- Workflows will use their `inputSchema` for the tool's input.
334
-
335
- ### Tools with Structured Outputs
336
-
337
- 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.
338
-
339
- 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.
340
-
341
- Here's an example of a tool with an `outputSchema`:
342
-
343
- ```typescript filename="src/tools/structured-tool.ts"
344
- import { createTool } from '@mastra/core/tools';
345
- import { z } from 'zod';
346
-
347
- export const structuredTool = createTool({
348
- description: 'A test tool that returns structured data.',
349
- parameters: z.object({
350
- input: z.string().describe('Some input string.'),
351
- }),
352
- outputSchema: z.object({
353
- processedInput: z.string().describe('The processed input string.'),
354
- timestamp: z.string().describe('An ISO timestamp.'),
355
- }),
356
- execute: async ({ input }) => {
357
- // When outputSchema is defined, you must return an object
358
- return {
359
- processedInput: `processed: ${input}`,
360
- timestamp: new Date().toISOString(),
361
- };
362
- },
363
- });
364
- ```
365
-
366
- When this tool is called, the MCP client will receive both the structured data and a text representation of it.
367
-
368
- ```
369
- Tool result
370
-
371
- {
372
- "content": [
373
- {
374
- "type": "text",
375
- "text": "{\"processedInput\": \"hello\", \"timestamp\": \"2025-06-19T16:53:16.472Z\"}"
376
- }
377
- ],
378
- "structuredContent": {
379
- "processedInput": "processed: hello",
380
- "timestamp": "2025-06-19T16:53:16.472Z",
381
- }
382
- }
383
- ```
366
+ ## Related
384
367
 
385
- For detailed usage and examples, see the [`MCPServer` reference documentation](/reference/tools/mcp-server).
368
+ - [Using Tools and MCP](../agents/using-tools-and-mcp.mdx)
369
+ - [MCPClient](../../reference/tools/mcp-client.mdx)
370
+ - [MCPServer](../../reference/tools/mcp-server.mdx)
@@ -55,7 +55,7 @@ This executes `step1` and `step2` concurrently, then continues to `step3` after
55
55
 
56
56
  > See [Parallel Execution with Steps](../../examples/workflows/parallel-steps.mdx) for more information.
57
57
 
58
- > 📹 Watch: How to run steps in parallel and optimize your Mastra workflow → [YouTube (3 minutes)](https://youtu.be/pTSOSWbreE0)
58
+ > 📹 Watch: How to run steps in parallel and optimize your Mastra workflow → [YouTube (3 minutes)](https://youtu.be/GQJxve5Hki4)
59
59
 
60
60
  ## Conditional logic with `.branch()`
61
61
 
@@ -15,6 +15,11 @@ Common scenarios for suspending workflows include:
15
15
  - Rate limiting or throttling expensive operations
16
16
  - Handling event-driven processes with external triggers
17
17
 
18
+ > **New to suspend and resume?** Watch these official video tutorials:
19
+ >
20
+ > - **[Mastering Human-in-the-Loop with Suspend & Resume](https://youtu.be/aORuNG8Tq_k)** - Learn how to suspend workflows and accept user inputs
21
+ > - **[Building Multi-Turn Chat Interfaces with React](https://youtu.be/UMVm8YZwlxc)** - Implement multi-turn human-involved interactions with a React chat interface
22
+
18
23
  ## Workflow status types
19
24
 
20
25
  When running a workflow, its `status` can be one of the following:
package/CHANGELOG.md CHANGED
@@ -1,5 +1,21 @@
1
1
  # @mastra/mcp-docs-server
2
2
 
3
+ ## 0.13.21-alpha.1
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [[`2a6585f`](https://github.com/mastra-ai/mastra/commit/2a6585f7cb71f023f805d521d1c3c95fb9a3aa59), [`3d26e83`](https://github.com/mastra-ai/mastra/commit/3d26e8353a945719028f087cc6ac4b06f0ce27d2), [`56e55d1`](https://github.com/mastra-ai/mastra/commit/56e55d1e9eb63e7d9e41aa46e012aae471256812)]:
8
+ - @mastra/core@0.16.3-alpha.1
9
+
10
+ ## 0.13.21-alpha.0
11
+
12
+ ### Patch Changes
13
+
14
+ - Improve security ([#7648](https://github.com/mastra-ai/mastra/pull/7648))
15
+
16
+ - Updated dependencies [[`b4379f7`](https://github.com/mastra-ai/mastra/commit/b4379f703fd74474f253420e8c3a684f2c4b2f8e), [`dd9119b`](https://github.com/mastra-ai/mastra/commit/dd9119b175a8f389082f75c12750e51f96d65dca), [`d34aaa1`](https://github.com/mastra-ai/mastra/commit/d34aaa1da5d3c5f991740f59e2fe6d28d3e2dd91), [`ce1e580`](https://github.com/mastra-ai/mastra/commit/ce1e580f6391e94a0c6816a9c5db0a21566a262f), [`b2babfa`](https://github.com/mastra-ai/mastra/commit/b2babfa9e75b22f2759179e71d8473f6dc5421ed), [`d8c3ba5`](https://github.com/mastra-ai/mastra/commit/d8c3ba516f4173282d293f7e64769cfc8738d360), [`a566c4e`](https://github.com/mastra-ai/mastra/commit/a566c4e92d86c1671707c54359b1d33934f7cc13), [`af333aa`](https://github.com/mastra-ai/mastra/commit/af333aa30fe6d1b127024b03a64736c46eddeca2), [`3863c52`](https://github.com/mastra-ai/mastra/commit/3863c52d44b4e5779968b802d977e87adf939d8e), [`6424c7e`](https://github.com/mastra-ai/mastra/commit/6424c7ec38b6921d66212431db1e0958f441b2a7), [`db94750`](https://github.com/mastra-ai/mastra/commit/db94750a41fd29b43eb1f7ce8e97ba8b9978c91b), [`a66a371`](https://github.com/mastra-ai/mastra/commit/a66a3716b00553d7f01842be9deb34f720b10fab), [`69fc3cd`](https://github.com/mastra-ai/mastra/commit/69fc3cd0fd814901785bdcf49bf536ab1e7fd975)]:
17
+ - @mastra/core@0.16.3-alpha.0
18
+
3
19
  ## 0.13.20
4
20
 
5
21
  ### Patch Changes