@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.
- package/.docs/organized/changelogs/%40internal%2Fstorage-test-utils.md +8 -8
- package/.docs/organized/changelogs/%40internal%2Ftypes-builder.md +2 -0
- package/.docs/organized/changelogs/%40mastra%2Fagent-builder.md +8 -0
- package/.docs/organized/changelogs/%40mastra%2Fclient-js.md +30 -30
- package/.docs/organized/changelogs/%40mastra%2Fcloud.md +13 -13
- package/.docs/organized/changelogs/%40mastra%2Fcore.md +51 -51
- package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloud.md +29 -29
- package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloudflare.md +17 -17
- package/.docs/organized/changelogs/%40mastra%2Fdeployer-netlify.md +17 -17
- package/.docs/organized/changelogs/%40mastra%2Fdeployer-vercel.md +17 -17
- package/.docs/organized/changelogs/%40mastra%2Fdeployer.md +32 -32
- package/.docs/organized/changelogs/%40mastra%2Fevals.md +12 -12
- package/.docs/organized/changelogs/%40mastra%2Flibsql.md +10 -10
- package/.docs/organized/changelogs/%40mastra%2Fmcp-docs-server.md +24 -24
- package/.docs/organized/changelogs/%40mastra%2Fmemory.md +10 -10
- package/.docs/organized/changelogs/%40mastra%2Fpg.md +10 -10
- package/.docs/organized/changelogs/%40mastra%2Fplayground-ui.md +31 -31
- package/.docs/organized/changelogs/%40mastra%2Fschema-compat.md +6 -0
- package/.docs/organized/changelogs/%40mastra%2Fserver.md +30 -30
- package/.docs/organized/changelogs/create-mastra.md +11 -11
- package/.docs/organized/changelogs/mastra.md +31 -31
- package/.docs/organized/code-examples/agent.md +34 -9
- package/.docs/organized/code-examples/ai-sdk-v5.md +16 -14
- package/.docs/organized/code-examples/heads-up-game.md +3 -3
- package/.docs/raw/auth/clerk.mdx +142 -0
- package/.docs/raw/getting-started/installation.mdx +3 -1
- package/.docs/raw/getting-started/model-providers.mdx +31 -31
- package/.docs/raw/observability/ai-tracing.mdx +123 -24
- package/.docs/raw/reference/agents/ChunkType.mdx +857 -0
- package/.docs/raw/reference/agents/MastraModelOutput.mdx +321 -0
- package/.docs/raw/reference/agents/generateVNext.mdx +519 -0
- package/.docs/raw/reference/agents/streamVNext.mdx +6 -20
- package/.docs/raw/reference/auth/clerk.mdx +71 -0
- package/.docs/raw/reference/scorers/answer-similarity.mdx +179 -0
- package/.docs/raw/scorers/off-the-shelf-scorers.mdx +1 -0
- package/.docs/raw/server-db/production-server.mdx +27 -2
- package/.docs/raw/tools-mcp/mcp-overview.mdx +144 -159
- package/.docs/raw/workflows/control-flow.mdx +1 -1
- package/.docs/raw/workflows/suspend-and-resume.mdx +5 -0
- package/CHANGELOG.md +16 -0
- package/dist/stdio.js +11 -4
- package/dist/tools/docs.d.ts.map +1 -1
- package/package.json +4 -4
- /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
|
|
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
|
-
##
|
|
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)
|
|
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
|
|
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
|
-
|
|
14
|
+
Mastra currently supports two MCP classes:
|
|
15
15
|
|
|
16
|
-
|
|
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
|
-
|
|
19
|
+
## Getting started
|
|
19
20
|
|
|
20
|
-
|
|
21
|
+
To use MCP, install the required dependency:
|
|
21
22
|
|
|
22
|
-
```bash
|
|
23
|
+
```bash
|
|
23
24
|
npm install @mastra/mcp@latest
|
|
24
25
|
```
|
|
25
26
|
|
|
26
|
-
|
|
27
|
+
## Configuring `MCPClient`
|
|
27
28
|
|
|
28
|
-
|
|
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
|
-
```
|
|
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
|
|
34
|
+
export const testMcpClient = new MCPClient({
|
|
35
|
+
id: "test-mcp-client",
|
|
47
36
|
servers: {
|
|
48
|
-
|
|
49
|
-
sequential: {
|
|
37
|
+
wikipedia: {
|
|
50
38
|
command: "npx",
|
|
51
|
-
args: ["-y", "
|
|
39
|
+
args: ["-y", "wikipedia-mcp"]
|
|
52
40
|
},
|
|
53
|
-
// HTTP example
|
|
54
41
|
weather: {
|
|
55
|
-
url: new URL(
|
|
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
|
-
|
|
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
|
-
|
|
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()`)
|
|
73
|
-
| :---------------- |
|
|
74
|
-
| **Use Case** | Single-user, static config (e.g., CLI tool)
|
|
75
|
-
| **Configuration**
|
|
76
|
-
| **Credentials** | Shared across all uses | Can vary per user/request
|
|
77
|
-
| **Agent Setup** | Tools added in `Agent` constructor | Tools passed in
|
|
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
|
-
|
|
80
|
-
|
|
136
|
+
export const testAgent = new Agent({
|
|
137
|
+
// ...
|
|
138
|
+
tools: await testMcpClient.getTools()
|
|
139
|
+
});
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Dynamic tools
|
|
81
143
|
|
|
82
|
-
|
|
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
|
-
|
|
87
|
-
|
|
88
|
-
|
|
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
|
-
|
|
93
|
-
[Reference: `getToolsets()`](/reference/tools/mcp-client#gettoolsets)
|
|
164
|
+
const agent = mastra.getAgent("testAgent");
|
|
94
165
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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/
|
|
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
|