@mastra/mcp 1.15.0 → 1.15.1-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/CHANGELOG.md +18 -0
- package/dist/client/client.d.ts +3 -0
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/configuration.d.ts +13 -0
- package/dist/client/configuration.d.ts.map +1 -1
- package/dist/docs/SKILL.md +3 -2
- package/dist/docs/assets/SOURCE_MAP.json +2 -55
- package/dist/docs/references/docs-mcp-mcp-apps.md +1 -1
- package/dist/docs/references/docs-mcp-overview.md +9 -9
- package/dist/docs/references/docs-server-auth-fga.md +9 -6
- package/dist/docs/references/reference-editor-tools.md +100 -0
- package/dist/docs/references/reference-tools-mcp-client.md +15 -15
- package/dist/docs/references/reference-tools-mcp-server.md +21 -21
- package/dist/index.cjs +25999 -36504
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +25910 -36456
- package/dist/index.js.map +1 -1
- package/dist/server/server.d.ts.map +1 -1
- package/package.json +12 -11
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
# @mastra/mcp
|
|
2
2
|
|
|
3
|
+
## 1.15.1-alpha.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Fixed concurrent MCP tool calls failing while the client reconnects after a dropped connection. ([#20530](https://github.com/mastra-ai/mastra/pull/20530))
|
|
8
|
+
|
|
9
|
+
- Updated dependencies [[`82201f7`](https://github.com/mastra-ai/mastra/commit/82201f75fae8e050a8de2df08b74875ee74c6b83), [`fb18da5`](https://github.com/mastra-ai/mastra/commit/fb18da56fc35689ae370621a8f10b5b0d8606e20), [`fb18da5`](https://github.com/mastra-ai/mastra/commit/fb18da56fc35689ae370621a8f10b5b0d8606e20), [`0a6598b`](https://github.com/mastra-ai/mastra/commit/0a6598bde80bde008986ad6616bed9632b9294cb), [`9e1dad8`](https://github.com/mastra-ai/mastra/commit/9e1dad8f7b1cab2bb7ade90e5b7561f24577b88a), [`2f43145`](https://github.com/mastra-ai/mastra/commit/2f4314504c03cbba280414ac81ba3197448ee6b0), [`34d34d8`](https://github.com/mastra-ai/mastra/commit/34d34d8c811df512fef4dd5459f79b7821be1866)]:
|
|
10
|
+
- @mastra/core@1.56.0-alpha.6
|
|
11
|
+
|
|
12
|
+
## 1.15.1-alpha.0
|
|
13
|
+
|
|
14
|
+
### Patch Changes
|
|
15
|
+
|
|
16
|
+
- Speed up MCP discovery when an `MCPClient` is configured with multiple servers. `listTools()`, `listToolsets()`, `resources.list()`, `resources.templates()`, and `prompts.list()` now query all configured servers concurrently instead of one at a time, so total discovery time is roughly the slowest single server rather than the sum of all of them, and one slow or unresponsive server no longer stalls discovery for the rest. Tool, resource, and prompt ordering and per-server error reporting are unchanged. ([#19919](https://github.com/mastra-ai/mastra/pull/19919))
|
|
17
|
+
|
|
18
|
+
- Updated dependencies [[`4844167`](https://github.com/mastra-ai/mastra/commit/4844167cff2d5ec5004e94edd34970833040fa3f), [`5faf93f`](https://github.com/mastra-ai/mastra/commit/5faf93f03e19daea394b9e2a923f2e4f833407f2), [`80ad891`](https://github.com/mastra-ai/mastra/commit/80ad891f8cd10379aa5b5af7510c763783b2ab56), [`a1cb98d`](https://github.com/mastra-ai/mastra/commit/a1cb98d11990b560b98482292a1f34aa1a2d9092), [`598ad82`](https://github.com/mastra-ai/mastra/commit/598ad82d41c41389a686338a1d0e50b7400e1938), [`1fd6aad`](https://github.com/mastra-ai/mastra/commit/1fd6aad1ea4a9d32f65efa832307c35e981a4c0a)]:
|
|
19
|
+
- @mastra/core@1.56.0-alpha.4
|
|
20
|
+
|
|
3
21
|
## 1.15.0
|
|
4
22
|
|
|
5
23
|
### Minor Changes
|
package/dist/client/client.d.ts
CHANGED
|
@@ -159,6 +159,8 @@ export declare class InternalMastraMCPClient extends MastraBase {
|
|
|
159
159
|
*/
|
|
160
160
|
finishAuth(authorizationCode: string): Promise<void>;
|
|
161
161
|
private isConnected;
|
|
162
|
+
private reconnectPromise;
|
|
163
|
+
private lifecycleGeneration;
|
|
162
164
|
/**
|
|
163
165
|
* Connects to the MCP server using the configured transport.
|
|
164
166
|
*
|
|
@@ -206,6 +208,7 @@ export declare class InternalMastraMCPClient extends MastraBase {
|
|
|
206
208
|
* @internal
|
|
207
209
|
*/
|
|
208
210
|
forceReconnect(): Promise<void>;
|
|
211
|
+
private reconnectAfterTransportFailure;
|
|
209
212
|
listResources(): Promise<ListResourcesResult>;
|
|
210
213
|
readResource(uri: string): Promise<ReadResourceResult>;
|
|
211
214
|
subscribeResource(uri: string): Promise<EmptyResult>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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"}
|
|
@@ -731,6 +731,19 @@ export declare class MCPClient extends MastraBase {
|
|
|
731
731
|
toolsets: Record<string, Record<string, Tool<any, any, any, any>>>;
|
|
732
732
|
errors: Record<string, string>;
|
|
733
733
|
}>;
|
|
734
|
+
/**
|
|
735
|
+
* Runs a per-server discovery `operation` against every configured server
|
|
736
|
+
* concurrently, isolating and logging per-server failures. Results are
|
|
737
|
+
* returned in configuration order (`Object.keys(serverConfigs)`) so callers
|
|
738
|
+
* fold them back deterministically.
|
|
739
|
+
*
|
|
740
|
+
* Mirrors the parallel teardown in `disconnect()`: each server is bounded by
|
|
741
|
+
* its own request timeout, so total time is the slowest single server rather
|
|
742
|
+
* than the sum, and one slow or unresponsive server never stalls the others.
|
|
743
|
+
* Backs `listTools`/`listToolsets`, `resources.list`/`templates`, and
|
|
744
|
+
* `prompts.list`.
|
|
745
|
+
*/
|
|
746
|
+
private discoverAcrossServers;
|
|
734
747
|
/**
|
|
735
748
|
* Creates MCPServerBase-compatible proxy objects for each server connection
|
|
736
749
|
* in this MCPClient. The returned record can be spread directly into
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../../src/client/configuration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,oBAAoB,EACpB,MAAM,EACN,QAAQ,EACR,gBAAgB,EACjB,MAAM,oCAAoC,CAAC;AAK5C,OAAO,KAAK,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;
|
|
1
|
+
{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../../src/client/configuration.ts"],"names":[],"mappings":"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"}
|
package/dist/docs/SKILL.md
CHANGED
|
@@ -3,7 +3,7 @@ name: mastra-mcp
|
|
|
3
3
|
description: Documentation for @mastra/mcp. Use when working with @mastra/mcp APIs, configuration, or implementation.
|
|
4
4
|
metadata:
|
|
5
5
|
package: "@mastra/mcp"
|
|
6
|
-
version: "1.15.
|
|
6
|
+
version: "1.15.1-alpha.1"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## When to use
|
|
@@ -17,11 +17,12 @@ Read the individual reference documents for detailed explanations and code examp
|
|
|
17
17
|
### Docs
|
|
18
18
|
|
|
19
19
|
- [MCP Apps](references/docs-mcp-mcp-apps.md) - Serve interactive HTML UIs from MCP tools using the MCP Apps extension.
|
|
20
|
-
- [MCP overview](references/docs-mcp-overview.md) - Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient
|
|
20
|
+
- [MCP overview](references/docs-mcp-overview.md) - Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient and connect to registries, plus share your own tools using MCPServer.
|
|
21
21
|
- [Fine-Grained Authorization (FGA)](references/docs-server-auth-fga.md) - Add resource-level authorization to your Mastra application with FGA providers.
|
|
22
22
|
|
|
23
23
|
### Reference
|
|
24
24
|
|
|
25
|
+
- [Reference: Tool configuration](references/reference-editor-tools.md) - Reference for Editor tool sources, providers, descriptions, conditions, MCP clients, and resolution order.
|
|
25
26
|
- [Reference: MCPClient](references/reference-tools-mcp-client.md) - API Reference for MCPClient - A class for managing multiple Model Context Protocol servers and their tools.
|
|
26
27
|
- [Reference: MCPServer](references/reference-tools-mcp-server.md) - API Reference for MCPServer - A class for exposing Mastra tools and capabilities as a Model Context Protocol server.
|
|
27
28
|
|
|
@@ -1,59 +1,6 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version": "1.15.
|
|
2
|
+
"version": "1.15.1-alpha.1",
|
|
3
3
|
"package": "@mastra/mcp",
|
|
4
|
-
"exports": {
|
|
5
|
-
"UnauthorizedError": {
|
|
6
|
-
"types": "dist/index.d.ts",
|
|
7
|
-
"implementation": "dist/auth.js"
|
|
8
|
-
},
|
|
9
|
-
"auth": {
|
|
10
|
-
"types": "dist/index.d.ts",
|
|
11
|
-
"implementation": "dist/auth.js"
|
|
12
|
-
},
|
|
13
|
-
"buildDiscoveryUrls": {
|
|
14
|
-
"types": "dist/index.d.ts",
|
|
15
|
-
"implementation": "dist/auth.js"
|
|
16
|
-
},
|
|
17
|
-
"discoverAuthorizationServerMetadata": {
|
|
18
|
-
"types": "dist/index.d.ts",
|
|
19
|
-
"implementation": "dist/auth.js"
|
|
20
|
-
},
|
|
21
|
-
"discoverOAuthMetadata": {
|
|
22
|
-
"types": "dist/index.d.ts",
|
|
23
|
-
"implementation": "dist/auth.js"
|
|
24
|
-
},
|
|
25
|
-
"discoverOAuthProtectedResourceMetadata": {
|
|
26
|
-
"types": "dist/index.d.ts",
|
|
27
|
-
"implementation": "dist/auth.js"
|
|
28
|
-
},
|
|
29
|
-
"exchangeAuthorization": {
|
|
30
|
-
"types": "dist/index.d.ts",
|
|
31
|
-
"implementation": "dist/auth.js"
|
|
32
|
-
},
|
|
33
|
-
"extractResourceMetadataUrl": {
|
|
34
|
-
"types": "dist/index.d.ts",
|
|
35
|
-
"implementation": "dist/auth.js"
|
|
36
|
-
},
|
|
37
|
-
"parseErrorResponse": {
|
|
38
|
-
"types": "dist/index.d.ts",
|
|
39
|
-
"implementation": "dist/auth.js"
|
|
40
|
-
},
|
|
41
|
-
"refreshAuthorization": {
|
|
42
|
-
"types": "dist/index.d.ts",
|
|
43
|
-
"implementation": "dist/auth.js"
|
|
44
|
-
},
|
|
45
|
-
"registerClient": {
|
|
46
|
-
"types": "dist/index.d.ts",
|
|
47
|
-
"implementation": "dist/auth.js"
|
|
48
|
-
},
|
|
49
|
-
"selectResourceURL": {
|
|
50
|
-
"types": "dist/index.d.ts",
|
|
51
|
-
"implementation": "dist/auth.js"
|
|
52
|
-
},
|
|
53
|
-
"startAuthorization": {
|
|
54
|
-
"types": "dist/index.d.ts",
|
|
55
|
-
"implementation": "dist/auth.js"
|
|
56
|
-
}
|
|
57
|
-
},
|
|
4
|
+
"exports": {},
|
|
58
5
|
"modules": {}
|
|
59
6
|
}
|
|
@@ -85,7 +85,7 @@ Visit [MCPServer reference](https://mastra.ai/reference/tools/mcp-server) for th
|
|
|
85
85
|
|
|
86
86
|
## Connecting MCP Apps to agents
|
|
87
87
|
|
|
88
|
-
Agents consume tools
|
|
88
|
+
Agents consume tools, they don't need to know about MCP servers. Pass tools to the agent's `tools` config, and register the MCP server at the Mastra level so Studio can resolve app resources.
|
|
89
89
|
|
|
90
90
|
```typescript
|
|
91
91
|
import { Agent } from '@mastra/core/agent'
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# MCP overview
|
|
4
4
|
|
|
5
|
-
Mastra supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open standard for connecting AI agents to external tools and resources. It
|
|
5
|
+
Mastra supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open standard for connecting AI agents to external tools and resources. It's a universal plugin system, enabling agents to call tools regardless of language or hosting environment.
|
|
6
6
|
|
|
7
7
|
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.
|
|
8
8
|
|
|
@@ -64,7 +64,7 @@ export const testMcpClient = new MCPClient({
|
|
|
64
64
|
|
|
65
65
|
Visit [MCPClient](https://mastra.ai/reference/tools/mcp-client) for a full list of configuration options.
|
|
66
66
|
|
|
67
|
-
> **Authentication:** For connecting to OAuth-protected MCP servers
|
|
67
|
+
> **Authentication:** For connecting to OAuth-protected MCP servers, including completing the browser-based authorization flow with `authenticate()`, see the [OAuth Authentication](https://mastra.ai/reference/tools/mcp-client) section.
|
|
68
68
|
|
|
69
69
|
## Using `MCPClient` with an agent
|
|
70
70
|
|
|
@@ -84,7 +84,7 @@ export const testAgent = new Agent({
|
|
|
84
84
|
- US National Weather Service
|
|
85
85
|
|
|
86
86
|
Answer questions using the information you find using the MCP Servers.`,
|
|
87
|
-
model: 'openai/gpt-5.
|
|
87
|
+
model: 'openai/gpt-5.6-sol',
|
|
88
88
|
tools: await testMcpClient.listTools(),
|
|
89
89
|
})
|
|
90
90
|
```
|
|
@@ -106,7 +106,7 @@ export const mcp = new MCPClient({
|
|
|
106
106
|
})
|
|
107
107
|
```
|
|
108
108
|
|
|
109
|
-
You can also pass a function to decide
|
|
109
|
+
You can also pass a function to decide per runtime-call. See the [MCPClient reference](https://mastra.ai/reference/tools/mcp-client) for the full API.
|
|
110
110
|
|
|
111
111
|
## Configuring `MCPServer`
|
|
112
112
|
|
|
@@ -147,14 +147,14 @@ export const mastra = new Mastra({
|
|
|
147
147
|
})
|
|
148
148
|
```
|
|
149
149
|
|
|
150
|
-
## Static and
|
|
150
|
+
## Static and runtime tools
|
|
151
151
|
|
|
152
152
|
`MCPClient` offers two approaches to retrieving tools from connected servers, suitable for different application architectures:
|
|
153
153
|
|
|
154
154
|
| Feature | Static Configuration (`await mcp.listTools()`) | Dynamic Configuration (`await mcp.listToolsets()`) |
|
|
155
155
|
| ----------------- | ---------------------------------------------- | ---------------------------------------------------- |
|
|
156
|
-
| **Use Case** | Single-user, static config (e.g., CLI tool) | Multi-user,
|
|
157
|
-
| **Configuration** | Fixed at agent initialization | Per-request,
|
|
156
|
+
| **Use Case** | Single-user, static config (e.g., CLI tool) | Multi-user, runtime config (e.g., SaaS app) |
|
|
157
|
+
| **Configuration** | Fixed at agent initialization | Per-request, runtime |
|
|
158
158
|
| **Credentials** | Shared across all uses | Can vary per user/request |
|
|
159
159
|
| **Agent Setup** | Tools added in `Agent` constructor | Tools passed in `.generate()` or `.stream()` options |
|
|
160
160
|
|
|
@@ -257,7 +257,7 @@ const mcp = new MCPClient({
|
|
|
257
257
|
})
|
|
258
258
|
```
|
|
259
259
|
|
|
260
|
-
> **
|
|
260
|
+
> **Requirement:** Treat the mcp.run SSE URL like a password. Store it securely, for example, in an environment variable.
|
|
261
261
|
>
|
|
262
262
|
> ```bash
|
|
263
263
|
> MCP_RUN_SSE_URL=https://www.mcp.run/api/mcp/sse?nonce=...
|
|
@@ -410,7 +410,7 @@ As an alternative to MCP, Ampersand's AI SDK also has an adapter for Mastra, so
|
|
|
410
410
|
|
|
411
411
|
## MCP Apps
|
|
412
412
|
|
|
413
|
-
MCP servers can serve interactive HTML UIs via the MCP Apps extension. Tools with associated `ui://` resources render sandboxed iframes in Studio
|
|
413
|
+
MCP servers can serve interactive HTML UIs via the MCP Apps extension. Tools with associated `ui://` resources render sandboxed iframes in Studio, both on tool detail pages and inline in agent chat. The app iframe can call server tools and inject messages into the conversation. Visit [MCP Apps](https://mastra.ai/docs/mcp/mcp-apps) for setup instructions and the app bridge API.
|
|
414
414
|
|
|
415
415
|
## Related
|
|
416
416
|
|
|
@@ -74,10 +74,10 @@ resourceMapping: {
|
|
|
74
74
|
|
|
75
75
|
`deriveId()` receives:
|
|
76
76
|
|
|
77
|
-
- `user
|
|
78
|
-
- `resourceId
|
|
79
|
-
- `requestContext
|
|
80
|
-
- `metadata
|
|
77
|
+
- `user`: the authenticated user
|
|
78
|
+
- `resourceId`: the owning Mastra resource ID when available (for example, a thread's `resourceId`)
|
|
79
|
+
- `requestContext`: the current request context for advanced tenant resolution
|
|
80
|
+
- `metadata`: provider-specific metadata for the attempted action
|
|
81
81
|
|
|
82
82
|
Return `undefined` from `deriveId()` to fall back to the original Mastra resource ID.
|
|
83
83
|
|
|
@@ -254,6 +254,8 @@ class MyFGAProvider implements IFGAProvider {
|
|
|
254
254
|
}
|
|
255
255
|
```
|
|
256
256
|
|
|
257
|
+
> **Note:** See the [`IFGAProvider` reference](https://mastra.ai/reference/auth/fga) for every method, parameter, and the `ActorSignal` type.
|
|
258
|
+
|
|
257
259
|
## System actors
|
|
258
260
|
|
|
259
261
|
Autonomous and scheduled agents run without an end user. Mark these calls with an actor signal so FGA can tell them apart from user requests:
|
|
@@ -261,7 +263,7 @@ Autonomous and scheduled agents run without an end user. Mark these calls with a
|
|
|
261
263
|
- `true` or `{ actorKind: 'system' }` identifies an anonymous system actor.
|
|
262
264
|
- The object form can also carry `agentId`, `permissions`, and `scope` to identify and constrain the acting agent.
|
|
263
265
|
|
|
264
|
-
By default, a trusted actor skips the user-centric `require()` check after a tenant-scope check. To enforce per-agent least privilege, implement the optional `requireActor` method on your provider. It receives the actor and the same `FGACheckParams` as `require`, and throws `FGADeniedError` to deny. When your provider doesn't implement `requireActor`, the trusted-actor bypass is preserved, so adding it
|
|
266
|
+
By default, a trusted actor skips the user-centric `require()` check after a tenant-scope check. To enforce per-agent least privilege, implement the optional `requireActor` method on your provider. It receives the actor and the same `FGACheckParams` as `require`, and throws `FGADeniedError` to deny. When your provider doesn't implement `requireActor`, the trusted-actor bypass is preserved, so adding it's backward compatible.
|
|
265
267
|
|
|
266
268
|
```typescript
|
|
267
269
|
import { FGADeniedError } from '@mastra/core/auth/ee'
|
|
@@ -291,10 +293,11 @@ The actor signal is trusted input, so construct it server-side:
|
|
|
291
293
|
- Establish tenant scope server-side. Built-in agent HTTP routes ignore a client-supplied `organizationId` in the request context, and the trusted-actor path requires an `organizationId` to be set.
|
|
292
294
|
- Durable resume keeps its existing request-context recovery and merge behavior. This doesn't make a persisted actor trusted for a later workflow segment.
|
|
293
295
|
- The tenant-scope check confirms that a trusted `organizationId` exists. It doesn't verify that `actor.agentId` belongs to that organization. When that relationship matters, verify it in `requireActor` using authoritative provider data.
|
|
294
|
-
- Treat `actor.permissions` as
|
|
296
|
+
- Treat `actor.permissions` as an unverified claim. Resolve authoritative grants from a trusted source. A provider that enforces least privilege resolves the agent's authoritative permissions from a trusted source, for example a manifest or your FGA backend keyed by `agentId`, rather than trusting the inline values.
|
|
295
297
|
- Once a provider implements `requireActor`, errors from that method stop execution. Mastra doesn't fall back to organization-only authorization.
|
|
296
298
|
|
|
297
299
|
## Related
|
|
298
300
|
|
|
301
|
+
- [`IFGAProvider` reference](https://mastra.ai/reference/auth/fga)
|
|
299
302
|
- [Authentication overview](https://mastra.ai/docs/server/auth)
|
|
300
303
|
- [WorkOS authentication](https://mastra.ai/docs/server/auth/workos)
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
|
|
2
|
+
|
|
3
|
+
# Tool configuration
|
|
4
|
+
|
|
5
|
+
Editor stores tool selections as part of an agent version. A stored configuration can add registered tools, tools from integration providers, and tools from Model Context Protocol (MCP) clients.
|
|
6
|
+
|
|
7
|
+
See [Editor tools](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.
|
|
8
|
+
|
|
9
|
+
## Tool sources
|
|
10
|
+
|
|
11
|
+
| Source | Description |
|
|
12
|
+
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
|
|
13
|
+
| Registered tools | Tools registered in the Mastra runtime tool registry |
|
|
14
|
+
| MCP clients | Tools exposed by stored local or remote MCP server configurations |
|
|
15
|
+
| Integration tools | Tools resolved by legacy integration-provider configuration |
|
|
16
|
+
| [Tool providers](https://mastra.ai/reference/editor/tool-provider) | Tools resolved by providers registered on `MastraEditor`, such as Composio or Arcade |
|
|
17
|
+
|
|
18
|
+
Code-defined agents keep their existing tools. The [`editor` override setting](https://mastra.ai/reference/agents/agent) controls whether Editor can add and remove tools or only change descriptions.
|
|
19
|
+
|
|
20
|
+
## Description overrides
|
|
21
|
+
|
|
22
|
+
Each selected tool can store an agent-specific description. The description changes what the model sees without modifying the original tool definition.
|
|
23
|
+
|
|
24
|
+
In description-only mode, Editor applies overrides only to tools that already exist on the code-defined agent. For MCP tools, an agent-level description takes priority over the description stored on the MCP client.
|
|
25
|
+
|
|
26
|
+
If two sources resolve the same tool ID, the later source replaces the complete earlier tool, including its description. See [Resolution order](#resolution-order).
|
|
27
|
+
|
|
28
|
+
## Conditional tool sets
|
|
29
|
+
|
|
30
|
+
Editor can store conditional variants for the `tools`, `mcpClients`, `integrationTools`, and `toolProviders` fields. At runtime, matching variants are shallow-merged based on request-context values.
|
|
31
|
+
|
|
32
|
+
The rule language uses the same operators and nesting behavior as [prompt block display conditions](https://mastra.ai/reference/editor/prompt-blocks).
|
|
33
|
+
|
|
34
|
+
Conditions apply to a tool field variant or MCP client reference. Per-tool `rules` values in stored tool entries aren't evaluated by the current Editor resolver.
|
|
35
|
+
|
|
36
|
+
## Stored MCP clients
|
|
37
|
+
|
|
38
|
+
The `editor.mcp` namespace manages reusable MCP client configurations. See the [`mcp` namespace](https://mastra.ai/reference/editor/mastra-editor) for CRUD method signatures.
|
|
39
|
+
|
|
40
|
+
`@mastra/mcp` is an optional peer dependency of `@mastra/editor`. Install it before configuring stored MCP clients so Editor can load their tools at runtime:
|
|
41
|
+
|
|
42
|
+
**npm**:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
npm install @mastra/mcp
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**pnpm**:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
pnpm add @mastra/mcp
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
**Yarn**:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
yarn add @mastra/mcp
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
**Bun**:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
bun add @mastra/mcp
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Transports
|
|
67
|
+
|
|
68
|
+
| Transport | Stored configuration |
|
|
69
|
+
| --------- | ---------------------------------------------------- |
|
|
70
|
+
| `stdio` | `command` with optional `args`, `env`, and `timeout` |
|
|
71
|
+
| HTTP | `url` with optional `timeout` |
|
|
72
|
+
|
|
73
|
+
Stored HTTP definitions don't accept arbitrary headers. When the reserved `mastra__authToken` value is present in request context, Editor forwards it as an `Authorization: Bearer` header.
|
|
74
|
+
|
|
75
|
+
### Filtering
|
|
76
|
+
|
|
77
|
+
MCP tools can be allowlisted at two levels:
|
|
78
|
+
|
|
79
|
+
1. **Server level**: The stored server's `tools` map limits tools for every agent that uses the client.
|
|
80
|
+
2. **Agent level**: The agent's MCP client reference limits the remaining tools for that agent.
|
|
81
|
+
|
|
82
|
+
Agent-level tool names can use namespaced or bare names. An explicit empty `tools` map selects all tools. With the current resolver, omitting `tools` from an agent-level MCP reference selects none.
|
|
83
|
+
|
|
84
|
+
### Namespacing
|
|
85
|
+
|
|
86
|
+
MCP tools use `serverName_toolName` IDs to avoid conflicts. A `search` tool from the `docs` server becomes `docs_search`.
|
|
87
|
+
|
|
88
|
+
## Resolution order
|
|
89
|
+
|
|
90
|
+
Editor merges tool records in the following order. Later records replace earlier records with the same ID.
|
|
91
|
+
|
|
92
|
+
1. Code-defined tools
|
|
93
|
+
2. Registered stored tools
|
|
94
|
+
3. MCP tools
|
|
95
|
+
4. Legacy integration tools
|
|
96
|
+
5. V1 tool-provider tools
|
|
97
|
+
|
|
98
|
+
Standalone stored agents use the same order without code-defined tools. Static code-agent overrides stop after legacy integration tools.
|
|
99
|
+
|
|
100
|
+
Use unique tool IDs across sources when possible. A collision replaces the complete earlier tool rather than merging its fields.
|
|
@@ -125,7 +125,7 @@ const mcp = new MCPClient({
|
|
|
125
125
|
})
|
|
126
126
|
```
|
|
127
127
|
|
|
128
|
-
Per the MCP specification
|
|
128
|
+
Per the MCP specification: **clients MUST consider tool annotations to be untrusted unless they come from trusted servers**. Annotations are advisory hints and provide no security boundary. A malicious or buggy server can claim a tool is read-only when it isn't. Only use annotations to relax approval requirements for servers you trust.
|
|
129
129
|
|
|
130
130
|
The same annotations are also exposed on the tools returned by `listTools()` and `listToolsets()` under `tool.mcp.annotations`, so you can inspect them when wiring tools into an agent.
|
|
131
131
|
|
|
@@ -182,7 +182,7 @@ console.log(errors)
|
|
|
182
182
|
|
|
183
183
|
### `listToolsets()`
|
|
184
184
|
|
|
185
|
-
Returns an object mapping namespaced tool names (in the format `serverName.toolName`) to their tool implementations. Intended to be passed
|
|
185
|
+
Returns an object mapping namespaced tool names (in the format `serverName.toolName`) to their tool implementations. Intended to be passed at runtime into the generate or stream method.
|
|
186
186
|
|
|
187
187
|
```typescript
|
|
188
188
|
const res = await agent.stream(prompt, {
|
|
@@ -227,9 +227,9 @@ getServerAuthState(serverName: string): 'needs-auth' | 'authorized' | undefined
|
|
|
227
227
|
|
|
228
228
|
### `cancelAuthentication()`
|
|
229
229
|
|
|
230
|
-
Cancels an in-progress `authenticate()` flow for a server, so an abandoned browser authorization
|
|
230
|
+
Cancels an in-progress `authenticate()` flow for a server, so an abandoned browser authorization doesn't leave the client waiting indefinitely. It aborts the flow (including its setup phase, before the callback server binds), closes the local callback server if one is listening, and the pending `authenticate()` call rejects. Returns `true` if a flow was cancelled, or `false` when no flow was in progress.
|
|
231
231
|
|
|
232
|
-
The resulting `getServerAuthState()` depends on how far the flow
|
|
232
|
+
The resulting `getServerAuthState()` depends on how far the flow progressed. A flow cancelled after a `401` rejection stays at `'needs-auth'` and can be retried immediately. Cancellation during setup leaves the state unchanged (typically `undefined`) if no connection was attempted.
|
|
233
233
|
|
|
234
234
|
```typescript
|
|
235
235
|
async cancelAuthentication(serverName: string): Promise<boolean>
|
|
@@ -324,7 +324,7 @@ for (const serverName in templatesByServer) {
|
|
|
324
324
|
|
|
325
325
|
#### `resources.read(serverName: string, uri: string)`
|
|
326
326
|
|
|
327
|
-
Reads the content of a specific resource from a
|
|
327
|
+
Reads the content of a specific resource from a server.
|
|
328
328
|
|
|
329
329
|
```typescript
|
|
330
330
|
async read(serverName: string, uri: string): Promise<ReadResourceResult>
|
|
@@ -342,7 +342,7 @@ console.log('Current weather:', content.contents[0].text)
|
|
|
342
342
|
|
|
343
343
|
#### `resources.subscribe(serverName: string, uri: string)`
|
|
344
344
|
|
|
345
|
-
Subscribes to updates for a specific resource on a
|
|
345
|
+
Subscribes to updates for a specific resource on a server.
|
|
346
346
|
|
|
347
347
|
```typescript
|
|
348
348
|
async subscribe(serverName: string, uri: string): Promise<object>
|
|
@@ -356,7 +356,7 @@ await mcpClient.resources.subscribe('myWeatherServer', 'weather://current')
|
|
|
356
356
|
|
|
357
357
|
#### `resources.unsubscribe(serverName: string, uri: string)`
|
|
358
358
|
|
|
359
|
-
Unsubscribes from updates for a specific resource on a
|
|
359
|
+
Unsubscribes from updates for a specific resource on a server.
|
|
360
360
|
|
|
361
361
|
```typescript
|
|
362
362
|
async unsubscribe(serverName: string, uri: string): Promise<object>
|
|
@@ -388,7 +388,7 @@ mcpClient.resources.onUpdated('myWeatherServer', params => {
|
|
|
388
388
|
|
|
389
389
|
#### `resources.onListChanged(serverName: string, handler: () => void)`
|
|
390
390
|
|
|
391
|
-
Sets a notification handler that will be called when the
|
|
391
|
+
Sets a notification handler that will be called when the list of available resources changes on a specific server.
|
|
392
392
|
|
|
393
393
|
```typescript
|
|
394
394
|
async onListChanged(serverName: string, handler: () => void): Promise<void>
|
|
@@ -847,7 +847,7 @@ Give each server its own `MCPOAuthClientProvider` instance. A provider holds per
|
|
|
847
847
|
|
|
848
848
|
### Interactive browser authentication
|
|
849
849
|
|
|
850
|
-
When a server rejects a connection because authorization is required, the client records a `'needs-auth'` state instead of failing outright. Calling `authenticate()`
|
|
850
|
+
When a server rejects a connection because authorization is required, the client records a `'needs-auth'` state instead of failing outright. Calling `authenticate()` completes the flow. It starts a one-shot callback server on the provider's loopback redirect URL, falling back to the next sequential ports when it's in use. The SDK then performs discovery and client registration at runtime. `onRedirectToAuthorization` receives the authorization URL so your application can open it in the user's browser. The token exchange finishes after the browser returns the authorization code:
|
|
851
851
|
|
|
852
852
|
```typescript
|
|
853
853
|
import { MCPClient, MCPOAuthClientProvider } from '@mastra/mcp'
|
|
@@ -884,9 +884,9 @@ try {
|
|
|
884
884
|
}
|
|
885
885
|
```
|
|
886
886
|
|
|
887
|
-
Concurrent `authenticate()` calls for the same server join the pending flow
|
|
887
|
+
Concurrent `authenticate()` calls for the same server join the pending flow. Different servers authenticate independently. With valid stored tokens the call reconnects without opening a browser.
|
|
888
888
|
|
|
889
|
-
Hosts that drive the flow themselves can capture the authorization code with the exported `createOAuthCallbackServer` helper, which binds a one-shot loopback server, validates the OAuth `state` parameter, and resolves with the code. It creates a plain HTTP server, so it
|
|
889
|
+
Hosts that drive the flow themselves can capture the authorization code with the exported `createOAuthCallbackServer` helper, which binds a one-shot loopback server, validates the OAuth `state` parameter, and resolves with the code. It creates a plain HTTP server, so it's only for local loopback redirects. Web applications that use an HTTPS redirect URL must host their own callback endpoint and drive the provider directly rather than using this helper:
|
|
890
890
|
|
|
891
891
|
```typescript
|
|
892
892
|
import { createOAuthCallbackServer, getCallbackUrlCandidates } from '@mastra/mcp'
|
|
@@ -1013,7 +1013,7 @@ const agent = new Agent({
|
|
|
1013
1013
|
id: 'multi-tool-agent',
|
|
1014
1014
|
name: 'Multi-tool Agent',
|
|
1015
1015
|
instructions: 'You have access to multiple tool servers.',
|
|
1016
|
-
model: 'openai/gpt-5.
|
|
1016
|
+
model: 'openai/gpt-5.6-sol',
|
|
1017
1017
|
tools: await mcp.listTools(),
|
|
1018
1018
|
})
|
|
1019
1019
|
|
|
@@ -1064,7 +1064,7 @@ const agent = new Agent({
|
|
|
1064
1064
|
id: 'multi-tool-agent',
|
|
1065
1065
|
name: 'Multi-tool Agent',
|
|
1066
1066
|
instructions: 'You help users check stocks and weather.',
|
|
1067
|
-
model: 'openai/gpt-5.
|
|
1067
|
+
model: 'openai/gpt-5.6-sol',
|
|
1068
1068
|
})
|
|
1069
1069
|
|
|
1070
1070
|
// Later, configure MCP with user-specific settings
|
|
@@ -1139,9 +1139,9 @@ MCPClient handles server connections gracefully:
|
|
|
1139
1139
|
2. Graceful server shutdown to prevent error messages during development
|
|
1140
1140
|
3. Proper cleanup of resources when disconnecting
|
|
1141
1141
|
|
|
1142
|
-
## Using custom fetch for
|
|
1142
|
+
## Using custom fetch for runtime-defined authentication
|
|
1143
1143
|
|
|
1144
|
-
For HTTP servers, you can provide a custom `fetch` function to handle
|
|
1144
|
+
For HTTP servers, you can provide a custom `fetch` function to handle runtime-defined authentication or request interception. It can also handle other custom behavior. This is particularly useful when you need to refresh tokens on each request or forward user credentials from the incoming request to the MCP server.
|
|
1145
1145
|
|
|
1146
1146
|
The custom `fetch` function receives an optional third `requestContext` parameter, which provides access to request-scoped data (e.g., authentication cookies, bearer tokens) set by middleware or passed during agent/tool execution. The `requestContext` is `null` during the initial connection handshake.
|
|
1147
1147
|
|