@mastra/mcp 1.17.0-alpha.0 → 1.17.0-alpha.2
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 +100 -0
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/types.d.ts +29 -0
- package/dist/client/types.d.ts.map +1 -1
- package/dist/docs/SKILL.md +3 -3
- package/dist/docs/assets/SOURCE_MAP.json +1 -1
- package/dist/docs/references/{docs-server-auth-fga.md → docs-auth-fga.md} +27 -1
- package/dist/docs/references/{docs-mcp-overview.md → docs-connections-mcp.md} +1 -1
- package/dist/docs/references/docs-connections-overview.md +5 -5
- package/dist/docs/references/reference-editor-tools.md +1 -1
- package/dist/docs/references/reference-tools-mcp-client.md +2 -0
- package/dist/docs/references/reference-tools-mcp-server.md +97 -4
- package/dist/index.cjs +330 -59
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +333 -62
- package/dist/index.js.map +1 -1
- package/dist/server/mrtrElicitation.d.ts +39 -0
- package/dist/server/mrtrElicitation.d.ts.map +1 -0
- package/dist/server/promptActions.d.ts +8 -1
- package/dist/server/promptActions.d.ts.map +1 -1
- package/dist/server/resourceActions.d.ts +8 -1
- package/dist/server/resourceActions.d.ts.map +1 -1
- package/dist/server/server.d.ts +86 -18
- package/dist/server/server.d.ts.map +1 -1
- package/dist/server/toolActions.d.ts +8 -1
- package/dist/server/toolActions.d.ts.map +1 -1
- package/dist/server/types.d.ts +29 -1
- package/dist/server/types.d.ts.map +1 -1
- package/package.json +5 -5
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,105 @@
|
|
|
1
1
|
# @mastra/mcp
|
|
2
2
|
|
|
3
|
+
## 1.17.0-alpha.2
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- Added elicitation support on the `2026-07-28` protocol revision using the spec's multi round-trip mechanism, completing the opt-in `protocolVersion` support. ([#20931](https://github.com/mastra-ai/mastra/pull/20931))
|
|
8
|
+
|
|
9
|
+
**Server** — tools keep the same promise-shaped API on both eras:
|
|
10
|
+
|
|
11
|
+
```typescript
|
|
12
|
+
execute: async (inputData, options) => {
|
|
13
|
+
const answer = await options.mcp.elicitation.sendRequest({
|
|
14
|
+
message: 'What is your favorite color?',
|
|
15
|
+
requestedSchema: { type: 'object', properties: { color: { type: 'string' } } },
|
|
16
|
+
});
|
|
17
|
+
// ...
|
|
18
|
+
};
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
On a `2026-07-28` request, the tool call first returns an `input_required` result. After the client answers, the call retries with the answer attached. The tool function re-executes from the top on each retry, so keep side effects idempotent (or place them after the last elicitation) and keep the order of `sendRequest()` calls deterministic. Legacy connections keep the existing push-based `elicitation/create` flow unchanged.
|
|
22
|
+
|
|
23
|
+
**Client** — a handler registered with `elicitation.onRequest()` now fires on both eras: on `2026-07-28` connections, embedded elicitation requests are dispatched through the same handler and the originating tool call retries automatically. The warning that elicitation only works on legacy connections is removed.
|
|
24
|
+
|
|
25
|
+
- Added opt-in support for the stateless MCP protocol revision `2026-07-28` behind a `protocolVersion` flag on both `MCPServer` and the MCP client. Omitting the flag keeps today's behavior unchanged. ([#20929](https://github.com/mastra-ai/mastra/pull/20929))
|
|
26
|
+
|
|
27
|
+
**Server**
|
|
28
|
+
|
|
29
|
+
```typescript
|
|
30
|
+
const server = new MCPServer({
|
|
31
|
+
name: 'My Server',
|
|
32
|
+
version: '1.0.0',
|
|
33
|
+
tools: { weatherTool },
|
|
34
|
+
protocolVersion: '2026-07-28',
|
|
35
|
+
cacheHints: {
|
|
36
|
+
'tools/list': { ttlMs: 60_000, cacheScope: 'private' },
|
|
37
|
+
},
|
|
38
|
+
});
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
With the flag set:
|
|
42
|
+
|
|
43
|
+
- One HTTP endpoint serves both protocol eras: `2026-07-28` clients are served natively (stateless), and legacy clients are served through an automatic stateless fallback.
|
|
44
|
+
- `startStdio()` serves both eras, selecting the era from the connection's opening exchange.
|
|
45
|
+
- Tool, prompt, and resource change notifications also reach `2026-07-28` clients through `subscriptions/listen`.
|
|
46
|
+
- Tool log messages honor the caller's per-request `logLevel` opt-in.
|
|
47
|
+
- Optional `cacheHints` advertise `ttlMs` / `cacheScope` on cacheable results such as `tools/list`.
|
|
48
|
+
- `startHTTP()` continues to enforce configured host and origin guards. Session and handler-lifetime transport options fail with a clear error instead of being ignored.
|
|
49
|
+
|
|
50
|
+
**Client**
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
const mcp = new MCPClient({
|
|
54
|
+
servers: {
|
|
55
|
+
weather: {
|
|
56
|
+
url: new URL('https://example.com/mcp'),
|
|
57
|
+
protocolVersion: 'auto', // probe, fall back to legacy
|
|
58
|
+
// or '2026-07-28' to pin the revision and fail loudly when unavailable
|
|
59
|
+
},
|
|
60
|
+
},
|
|
61
|
+
});
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Elicitation handlers currently only fire on legacy connections; support for the `2026-07-28` input-required mechanism ships separately.
|
|
65
|
+
|
|
66
|
+
### Patch Changes
|
|
67
|
+
|
|
68
|
+
- Updated dependencies [[`6223446`](https://github.com/mastra-ai/mastra/commit/6223446ddce6166e96e0ba5e00d628b615dee8ca), [`583e235`](https://github.com/mastra-ai/mastra/commit/583e23519c13af16c1746f9c49722d011216611b), [`a77f8d4`](https://github.com/mastra-ai/mastra/commit/a77f8d4740d2178a74c41e4bf678b4fcd8fa0bb2), [`40d358e`](https://github.com/mastra-ai/mastra/commit/40d358e29d55543803e64b49241122f598ffabc7), [`e80cd7e`](https://github.com/mastra-ai/mastra/commit/e80cd7e7683e7d732e1cc6784bcac1d2640d2ce3), [`20504b2`](https://github.com/mastra-ai/mastra/commit/20504b2ecebd0e077acda3d457ab57480a98ed3e)]:
|
|
69
|
+
- @mastra/core@1.60.0-alpha.11
|
|
70
|
+
|
|
71
|
+
## 1.17.0-alpha.1
|
|
72
|
+
|
|
73
|
+
### Minor Changes
|
|
74
|
+
|
|
75
|
+
- MCP tools served over HTTP now see the authenticated caller. When an MCP server runs behind a Mastra server with `server.auth` configured, the resolved user is bridged into `extra.authInfo` automatically, on both the streamable HTTP and SSE transports. Previously `extra.authInfo` was always undefined because the request handed to the MCP transport was rebuilt without the auth data. ([#21689](https://github.com/mastra-ai/mastra/pull/21689))
|
|
76
|
+
|
|
77
|
+
**Custom verification**
|
|
78
|
+
|
|
79
|
+
If your own middleware verifies the caller, build the auth info yourself with the new `server.mcpOptions.setRequestAuth` hook:
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
export const mastra = new Mastra({
|
|
83
|
+
mcpServers: { myServer },
|
|
84
|
+
server: {
|
|
85
|
+
middleware: [verifyBearerToken],
|
|
86
|
+
mcpOptions: {
|
|
87
|
+
setRequestAuth: (req, requestContext) => {
|
|
88
|
+
const payload = requestContext.get('bearerPayload');
|
|
89
|
+
req.auth = { token: payload.token, clientId: payload.sub, scopes: payload.scope.split(' ') };
|
|
90
|
+
},
|
|
91
|
+
},
|
|
92
|
+
},
|
|
93
|
+
});
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Fixes #17291
|
|
97
|
+
|
|
98
|
+
### Patch Changes
|
|
99
|
+
|
|
100
|
+
- Updated dependencies [[`4e7a421`](https://github.com/mastra-ai/mastra/commit/4e7a421dce8a48742f785d1e93ad2f43a572b282), [`242e324`](https://github.com/mastra-ai/mastra/commit/242e3241e73cbd5c9bb86a31ebb49ca0256488d4), [`217e967`](https://github.com/mastra-ai/mastra/commit/217e9672d8b3160eb729d8e9f0044949e88da239), [`d774e89`](https://github.com/mastra-ai/mastra/commit/d774e8930c781df8c9effe3763e6b501c099b6cc), [`9c27a53`](https://github.com/mastra-ai/mastra/commit/9c27a53cd9d3de4f3f025bc387d94ce371c33f95), [`dff25a1`](https://github.com/mastra-ai/mastra/commit/dff25a1103fa72ee082a9b6f805ebeb5ce400753), [`217e967`](https://github.com/mastra-ai/mastra/commit/217e9672d8b3160eb729d8e9f0044949e88da239), [`7f78585`](https://github.com/mastra-ai/mastra/commit/7f785857e401570e2ffb316911f126ed363aa537), [`f2a4afd`](https://github.com/mastra-ai/mastra/commit/f2a4afd7e37e809669001ed17724b341a5c1f45e), [`d438148`](https://github.com/mastra-ai/mastra/commit/d438148e222c1e2fb3c652725ce75680962ebec4), [`ba05fe0`](https://github.com/mastra-ai/mastra/commit/ba05fe0738f70cb686777546e968237d09269142), [`d26a8d4`](https://github.com/mastra-ai/mastra/commit/d26a8d4281f28414715b333c85bedaf70d0b2890), [`677cdc6`](https://github.com/mastra-ai/mastra/commit/677cdc6af564dec29a13464d12b7ab2a4efc22e9), [`a318490`](https://github.com/mastra-ai/mastra/commit/a318490e17da32f338d50929c770d901a9b3dd72), [`763e0c6`](https://github.com/mastra-ai/mastra/commit/763e0c61e04d76ad9a9efd301aa57525ca0cbea9), [`23e0be2`](https://github.com/mastra-ai/mastra/commit/23e0be261381e49534b4ff3101c60ee64a946cbf), [`7fc8806`](https://github.com/mastra-ai/mastra/commit/7fc880627d3cbf995d31ea0e8b807bf15417e651), [`0e02eac`](https://github.com/mastra-ai/mastra/commit/0e02eacdb2e30e1697a41910b41163742a181dc1), [`4df174c`](https://github.com/mastra-ai/mastra/commit/4df174c32bddf093a82f273070b8380aef7c9e90), [`f7c25b5`](https://github.com/mastra-ai/mastra/commit/f7c25b5106ddfb48e591f98df7a51e0f2dd01dba), [`dc09cc1`](https://github.com/mastra-ai/mastra/commit/dc09cc1083d861cde192c1cd235324dc75b8c731), [`36b4649`](https://github.com/mastra-ai/mastra/commit/36b4649045a3a380cbab8ceca866db4086223aff), [`377eb81`](https://github.com/mastra-ai/mastra/commit/377eb81ce43b964e3a6b541df172da74a8ff3716)]:
|
|
101
|
+
- @mastra/core@1.60.0-alpha.8
|
|
102
|
+
|
|
3
103
|
## 1.17.0-alpha.0
|
|
4
104
|
|
|
5
105
|
### Minor Changes
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI/C,OAAO,KAAK,EAAmB,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAUhE,OAAO,KAAK,EAEV,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,2BAA2B,EAE3B,kBAAkB,EAEnB,MAAM,8BAA8B,CAAC;AAKtC,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAGV,kBAAkB,EAClB,eAAe,EAEf,8BAA8B,EAC9B,IAAI,EAEJ,6BAA6B,EAC9B,MAAM,SAAS,CAAC;AASjB,YAAY,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,yBAAyB,EACzB,8BAA8B,EAC9B,IAAI,EACJ,mBAAmB,EACnB,qBAAqB,EACrB,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,SAAS,CAAC;AAQjB;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,YAAY,CAAC;AAkD7D;;;GAGG;AACH,eAAO,MAAM,qBAAqB,eAA2C,CAAC;
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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"}
|
package/dist/client/types.d.ts
CHANGED
|
@@ -260,6 +260,35 @@ export type BaseServerOptions = {
|
|
|
260
260
|
* ```
|
|
261
261
|
*/
|
|
262
262
|
roots?: Root[];
|
|
263
|
+
/**
|
|
264
|
+
* Opt-in MCP protocol version negotiation.
|
|
265
|
+
*
|
|
266
|
+
* - Omitted (default): the plain legacy (2025-era) connect sequence,
|
|
267
|
+
* byte-identical to a client without this option.
|
|
268
|
+
* - `'auto'`: probe the server with `server/discover` at connect time and use
|
|
269
|
+
* the stateless `2026-07-28` revision when the server supports it, with a
|
|
270
|
+
* conservative fallback to the legacy `initialize` handshake.
|
|
271
|
+
* - `'2026-07-28'`: pin to that revision exactly. Connecting to a server that
|
|
272
|
+
* does not offer it fails loudly with a typed error — no fallback.
|
|
273
|
+
*
|
|
274
|
+
* Elicitation handlers work on both eras: on a negotiated `2026-07-28`
|
|
275
|
+
* connection, embedded elicitation requests from `input_required` results are
|
|
276
|
+
* dispatched through the same registered handler and the originating call is
|
|
277
|
+
* retried automatically.
|
|
278
|
+
*
|
|
279
|
+
* @example
|
|
280
|
+
* ```typescript
|
|
281
|
+
* const mcp = new MCPClient({
|
|
282
|
+
* servers: {
|
|
283
|
+
* weather: {
|
|
284
|
+
* url: new URL('https://example/mcp'),
|
|
285
|
+
* protocolVersion: 'auto',
|
|
286
|
+
* },
|
|
287
|
+
* },
|
|
288
|
+
* });
|
|
289
|
+
* ```
|
|
290
|
+
*/
|
|
291
|
+
protocolVersion?: 'auto' | '2026-07-28';
|
|
263
292
|
};
|
|
264
293
|
/**
|
|
265
294
|
* Configuration for MCP servers using stdio (subprocess) transport.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.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.17.0-alpha.
|
|
6
|
+
version: "1.17.0-alpha.2"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## When to use
|
|
@@ -16,9 +16,9 @@ Read the individual reference documents for detailed explanations and code examp
|
|
|
16
16
|
|
|
17
17
|
### Docs
|
|
18
18
|
|
|
19
|
+
- [Fine-Grained Authorization (FGA)](references/docs-auth-fga.md) - Add resource-level authorization to your Mastra application with FGA providers.
|
|
20
|
+
- [MCP](references/docs-connections-mcp.md) - Connect Mastra agents to external MCP servers and expose Mastra tools through MCPServer. You can also build interactive MCP Apps for Studio.
|
|
19
21
|
- [Connections](references/docs-connections-overview.md) - Connect Mastra to remote agents, coding agents, provider software development kit runtimes, and external tools and resources.
|
|
20
|
-
- [MCP](references/docs-mcp-overview.md) - Connect Mastra agents to external MCP servers and expose Mastra tools through MCPServer. You can also build interactive MCP Apps for Studio.
|
|
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
|
|
|
@@ -284,6 +284,32 @@ class MyFGAProvider implements IFGAProvider {
|
|
|
284
284
|
}
|
|
285
285
|
```
|
|
286
286
|
|
|
287
|
+
### Propagating an actor into workflow steps
|
|
288
|
+
|
|
289
|
+
A workflow run's `actor` reaches each step's execute context, but it isn't passed to the agent and tool calls that step makes. Steps that call an agent without an `actor` fall back to user membership resolution, which fails on system runs that have no user.
|
|
290
|
+
|
|
291
|
+
Set `propagate: true` on the actor to have the framework forward it into the agent and tool calls it makes for declarative `.then(agent)` and `.then(tool)` steps in the run:
|
|
292
|
+
|
|
293
|
+
```typescript
|
|
294
|
+
await run.start({
|
|
295
|
+
inputData: { city: 'London' },
|
|
296
|
+
actor: { actorKind: 'system', sourceWorkflow: 'nightly-report', propagate: true },
|
|
297
|
+
})
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
Propagation is opt-in and deliberately narrow:
|
|
301
|
+
|
|
302
|
+
- The `true` shorthand never propagates. Use the object form to opt in.
|
|
303
|
+
- Custom step `execute` functions are never covered. Read `actor` from the step context and pass it explicitly, so a step that acts on a user's behalf can't silently inherit system trust.
|
|
304
|
+
- Pass `actor` when creating the step to override the run actor for that step, including `actor: undefined` to drop back to user authorization mid-run.
|
|
305
|
+
|
|
306
|
+
```typescript
|
|
307
|
+
// Runs as the system actor even though it loads user-supplied data.
|
|
308
|
+
workflow.then(createStep(reportAgent))
|
|
309
|
+
// Explicitly runs as the user instead.
|
|
310
|
+
workflow.then(createStep(summaryAgent, { actor: undefined }))
|
|
311
|
+
```
|
|
312
|
+
|
|
287
313
|
### Trust requirements
|
|
288
314
|
|
|
289
315
|
The actor signal is trusted input, so construct it server-side:
|
|
@@ -299,5 +325,5 @@ The actor signal is trusted input, so construct it server-side:
|
|
|
299
325
|
## Related
|
|
300
326
|
|
|
301
327
|
- [`IFGAProvider` reference](https://mastra.ai/reference/auth/fga)
|
|
302
|
-
- [Authentication overview](https://mastra.ai/docs/
|
|
328
|
+
- [Authentication overview](https://mastra.ai/docs/auth/overview)
|
|
303
329
|
- [WorkOS authentication](https://mastra.ai/integrations/auth/workos)
|
|
@@ -406,7 +406,7 @@ App iframes allow scripts, forms, and popups. They can't access the parent page'
|
|
|
406
406
|
|
|
407
407
|
## Next steps
|
|
408
408
|
|
|
409
|
-
- [Use tools with agents](https://mastra.ai/docs/agents/
|
|
409
|
+
- [Use tools with agents](https://mastra.ai/docs/agents/tools)
|
|
410
410
|
- [`MCPClient` reference](https://mastra.ai/reference/tools/mcp-client)
|
|
411
411
|
- [`MCPServer` reference](https://mastra.ai/reference/tools/mcp-server)
|
|
412
412
|
- [MCP Apps extension specification](https://github.com/modelcontextprotocol/ext-apps)
|
|
@@ -4,10 +4,10 @@
|
|
|
4
4
|
|
|
5
5
|
Connections let Mastra work with remote agents, coding agents, provider software development kit (SDK) runtimes, and external tools and resources. Choose a connection type based on which system owns the agent runtime and what you need to exchange.
|
|
6
6
|
|
|
7
|
-
- [**
|
|
8
|
-
- [**Agent
|
|
9
|
-
- [**
|
|
10
|
-
- [**
|
|
7
|
+
- [**Model Context Protocol (MCP)**](https://mastra.ai/docs/connections/mcp): Connect agents to external tools and resources, or expose Mastra agents, tools, workflows, prompts, and resources to MCP-compatible systems.
|
|
8
|
+
- [**Agent-to-Agent (A2A)**](https://mastra.ai/docs/connections/a2a): Expose or consume remote agents across service, framework, vendor, and language boundaries.
|
|
9
|
+
- [**Agent Client Protocol (ACP)**](https://mastra.ai/docs/connections/acp): Run compatible coding-agent processes, such as Claude Code, Cline, or OpenCode, as Mastra tools or subagents.
|
|
10
|
+
- [**SDK agents**](https://mastra.ai/docs/connections/sdk-agents): Register Claude, Cursor, or OpenAI SDK-backed agents while the provider SDK retains control of the runtime, tools, permissions, and agent loop.
|
|
11
11
|
|
|
12
12
|
## When to use connections
|
|
13
13
|
|
|
@@ -20,7 +20,7 @@ Use connections when you need to:
|
|
|
20
20
|
|
|
21
21
|
## Get started
|
|
22
22
|
|
|
23
|
-
Start with the boundary you need to cross. Use [A2A](https://mastra.ai/docs/
|
|
23
|
+
Start with the boundary you need to cross. Use [A2A](https://mastra.ai/docs/connections/a2a) for remote agent endpoints, [ACP](https://mastra.ai/docs/connections/acp) for coding-agent processes, [SDK agents](https://mastra.ai/docs/connections/sdk-agents) for provider-owned runtimes, or [MCP](https://mastra.ai/docs/connections/mcp) for tools and resources.
|
|
24
24
|
|
|
25
25
|
**A2A**:
|
|
26
26
|
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
Editor stores tool selections as part of an agent version. A stored configuration can add registered tools and tools from integration providers, as well as tools from Model Context Protocol (MCP) clients.
|
|
6
6
|
|
|
7
|
-
See [Editor tools](https://mastra.ai/docs/editor
|
|
7
|
+
See [Editor tools](https://mastra.ai/docs/studio/editor) for the Studio workflow and common uses.
|
|
8
8
|
|
|
9
9
|
## Tool sources
|
|
10
10
|
|
|
@@ -65,6 +65,8 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
|
|
|
65
65
|
|
|
66
66
|
**requireToolApproval** (`boolean | (params: RequireToolApprovalContext) => boolean | Promise<boolean>`): Require human approval before executing tools from this server. When set to true, all tools require approval. When set to a function, the function is called with the tool name, arguments, request context, and any tool annotations advertised by the server to dynamically decide whether approval is needed.
|
|
67
67
|
|
|
68
|
+
**protocolVersion** (`'auto' | '2026-07-28'`): Opt-in MCP protocol version negotiation. Omitted keeps the legacy (2025-era) connect sequence unchanged. 'auto' probes the server at connect time and uses the stateless '2026-07-28' revision when the server supports it, with a safe fallback to the legacy handshake. '2026-07-28' pins that revision exactly and fails with a typed error when the server does not offer it. Elicitation handlers work on both eras: on a '2026-07-28' connection, embedded elicitation requests from input\_required results are dispatched through the same registered handler and the originating call retries automatically.
|
|
69
|
+
|
|
68
70
|
## Tool approval
|
|
69
71
|
|
|
70
72
|
Use `requireToolApproval` on a server definition to require human approval before any tool from that server is executed. This works with the existing [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) approval flow.
|
|
@@ -91,6 +91,35 @@ The constructor accepts an `MCPServerConfig` object with the following propertie
|
|
|
91
91
|
|
|
92
92
|
**appResources** (`AppResources`): A map of ui:// URIs to app resource configurations. Each entry defines an interactive HTML UI served via the MCP Apps extension (SEP-1865). See the MCP Apps section for details.
|
|
93
93
|
|
|
94
|
+
**protocolVersion** (`'2025-11-25' | '2026-07-28'`): Opt-in MCP protocol revision. Omitted (or '2025-11-25') keeps the legacy behavior exactly. Set to '2026-07-28' to serve the stateless MCP revision. See the Protocol versions section for details.
|
|
95
|
+
|
|
96
|
+
**cacheHints** (`MCPServerCacheHints`): Cache hints (ttlMs / cacheScope) advertised on cacheable results of the '2026-07-28' protocol revision, keyed by operation (e.g. 'tools/list'). Only applied when protocolVersion: '2026-07-28' is set.
|
|
97
|
+
|
|
98
|
+
## Protocol versions
|
|
99
|
+
|
|
100
|
+
By default, `MCPServer` speaks the legacy (2025-era) MCP protocol: sessionful streamable HTTP with an `initialize` handshake. Set `protocolVersion: '2026-07-28'` to serve the stateless MCP revision instead:
|
|
101
|
+
|
|
102
|
+
- HTTP and serverless requests go through a dual-era handler: clients that speak `2026-07-28` are served natively (stateless, per-request envelope), and legacy clients are served through a built-in stateless fallback on the same endpoint.
|
|
103
|
+
- `startStdio()` serves both eras: the opening exchange selects the era for the connection.
|
|
104
|
+
- Tool list, prompt list, resource list, and resource update notifications also reach `2026-07-28` clients through `subscriptions/listen`.
|
|
105
|
+
- Tool log messages honor the caller's per-request `logLevel` opt-in instead of the session-level `logging/setLevel`.
|
|
106
|
+
- Configured `cacheHints` are advertised on cacheable results such as `tools/list`.
|
|
107
|
+
- Tool elicitation (`options.mcp.elicitation.sendRequest()`) works on both eras. On `2026-07-28` requests, it uses the protocol's multi round-trip mechanism. The tool call first returns an `input_required` result. After the client answers, the call retries with the answer attached. The `sendRequest()` promise API is unchanged, but the tool function re-executes from the top on each retry, so keep side effects idempotent (or place them after the last elicitation) and keep the order of `sendRequest()` calls deterministic for a given input.
|
|
108
|
+
|
|
109
|
+
```typescript
|
|
110
|
+
const server = new MCPServer({
|
|
111
|
+
name: 'My Server',
|
|
112
|
+
version: '1.0.0',
|
|
113
|
+
tools: { weatherTool },
|
|
114
|
+
protocolVersion: '2026-07-28',
|
|
115
|
+
cacheHints: {
|
|
116
|
+
'tools/list': { ttlMs: 60_000, cacheScope: 'private' },
|
|
117
|
+
},
|
|
118
|
+
})
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Omitting `protocolVersion` keeps the current behavior unchanged.
|
|
122
|
+
|
|
94
123
|
## Exposing agents as tools
|
|
95
124
|
|
|
96
125
|
A powerful feature of `MCPServer` is its ability to automatically expose your Mastra Agents as callable tools. When you provide agents in the `agents` property of the configuration:
|
|
@@ -168,6 +197,51 @@ const fetchUserData = createTool({
|
|
|
168
197
|
})
|
|
169
198
|
```
|
|
170
199
|
|
|
200
|
+
#### Where `authInfo` comes from
|
|
201
|
+
|
|
202
|
+
When an MCP server is served by a Mastra server, `extra.authInfo` is populated from the principal resolved by `server.auth`. Nothing extra is required:
|
|
203
|
+
|
|
204
|
+
```typescript
|
|
205
|
+
export const mastra = new Mastra({
|
|
206
|
+
mcpServers: { myServer },
|
|
207
|
+
server: {
|
|
208
|
+
auth: new MastraJwtAuth({ secret: process.env.JWT_SECRET! }),
|
|
209
|
+
},
|
|
210
|
+
})
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
The authenticated user is mapped to `authInfo` as:
|
|
214
|
+
|
|
215
|
+
| `authInfo` field | Value |
|
|
216
|
+
| ---------------- | -------------------------------------------------------------------------- |
|
|
217
|
+
| `token` | The bearer token or session cookie value used for the request |
|
|
218
|
+
| `clientId` | The first present of `user.id`, `user.sub`, `user.userId`, `user.email` |
|
|
219
|
+
| `scopes` | `user.scopes`, `user.scope`, or `user.permissions`, normalized to an array |
|
|
220
|
+
| `extra.user` | The full user object returned by the auth provider |
|
|
221
|
+
|
|
222
|
+
If your own middleware performs the verification, set `server.mcpOptions.setRequestAuth` to build `authInfo` yourself. The hook replaces the default mapping and applies to both the streamable HTTP and SSE transports:
|
|
223
|
+
|
|
224
|
+
```typescript
|
|
225
|
+
export const mastra = new Mastra({
|
|
226
|
+
mcpServers: { myServer },
|
|
227
|
+
server: {
|
|
228
|
+
middleware: [verifyBearerToken], // stores the payload on the request context
|
|
229
|
+
mcpOptions: {
|
|
230
|
+
setRequestAuth: (req, requestContext) => {
|
|
231
|
+
const payload = requestContext.get('bearerPayload')
|
|
232
|
+
req.auth = {
|
|
233
|
+
token: payload.token,
|
|
234
|
+
clientId: payload.sub,
|
|
235
|
+
scopes: payload.scope.split(' '),
|
|
236
|
+
}
|
|
237
|
+
},
|
|
238
|
+
},
|
|
239
|
+
},
|
|
240
|
+
})
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Leaving `req.auth` unset inside the hook opts the request out of auth info entirely.
|
|
244
|
+
|
|
171
245
|
## Methods
|
|
172
246
|
|
|
173
247
|
These are the functions you can call on an `MCPServer` instance to control its behavior and get information.
|
|
@@ -194,6 +268,8 @@ await server.startStdio()
|
|
|
194
268
|
|
|
195
269
|
### `startSSE()`
|
|
196
270
|
|
|
271
|
+
> **Warning:** The HTTP+SSE transport is deprecated in the MCP specification. Use `startHTTP()` (streamable HTTP) instead.
|
|
272
|
+
|
|
197
273
|
This method helps you integrate the MCP server with an existing web server to use Server-Sent Events (SSE) for communication. You'll call this from your web server's code when it receives a request for the SSE or message paths.
|
|
198
274
|
|
|
199
275
|
```typescript
|
|
@@ -246,6 +322,8 @@ Here are the details for the values needed by the `startSSE` method:
|
|
|
246
322
|
|
|
247
323
|
### `startHonoSSE()`
|
|
248
324
|
|
|
325
|
+
> **Warning:** The HTTP+SSE transport is deprecated in the MCP specification. Use `startHTTP()` (streamable HTTP) instead.
|
|
326
|
+
|
|
249
327
|
This method helps you integrate the MCP server with an existing web server to use Server-Sent Events (SSE) for communication. You'll call this from your web server's code when it receives a request for the SSE or message paths.
|
|
250
328
|
|
|
251
329
|
```typescript
|
|
@@ -316,6 +394,21 @@ async startHTTP({
|
|
|
316
394
|
}): Promise<void>
|
|
317
395
|
```
|
|
318
396
|
|
|
397
|
+
#### Options with `protocolVersion: '2026-07-28'`
|
|
398
|
+
|
|
399
|
+
The `2026-07-28` protocol uses one shared stateless handler instead of a transport configured for each request. `startHTTP()` handles legacy transport options as follows:
|
|
400
|
+
|
|
401
|
+
| Options | Behavior |
|
|
402
|
+
| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
403
|
+
| `serverless: true`, `serverlessStreaming: true`, `sessionIdGenerator: undefined` | Accepted because the modern handler already provides stateless requests and automatic request-scoped streaming. |
|
|
404
|
+
| `allowedHosts`, `allowedOrigins`, `enableDnsRebindingProtection` | Enforced before the request reaches the modern handler. Host and origin lists are active when `enableDnsRebindingProtection` is `true`. |
|
|
405
|
+
| `sessionIdGenerator` with a function, session callbacks, or `eventStore` | Rejected because the modern protocol doesn't create HTTP sessions. |
|
|
406
|
+
| `enableJsonResponse`, `retryInterval`, `keepAliveMs`, or `supportedProtocolVersions` | Rejected because these values configure a shared handler and can't vary between requests. |
|
|
407
|
+
| `serverless: false` or `serverlessStreaming: false` | Rejected because these values request behavior that differs from the modern handler. |
|
|
408
|
+
| Unknown options | Rejected instead of being ignored. |
|
|
409
|
+
|
|
410
|
+
Omit `options` when you don't need request guards or compatibility declarations.
|
|
411
|
+
|
|
319
412
|
Here's an example of how you might use `startHTTP` within an HTTP server request handler. In this example an MCP client could connect to your MCP server at `http://localhost:1234/http`:
|
|
320
413
|
|
|
321
414
|
```typescript
|
|
@@ -338,7 +431,7 @@ httpServer.listen(PORT, () => {
|
|
|
338
431
|
})
|
|
339
432
|
```
|
|
340
433
|
|
|
341
|
-
For **serverless environments** (Supabase Edge Functions, Cloudflare Workers, Vercel Edge, etc.), use `serverless: true` to enable stateless operation:
|
|
434
|
+
For **serverless environments** (Supabase Edge Functions, Cloudflare Workers, Vercel Edge, etc.), use `serverless: true` to enable stateless operation on the legacy protocol path. Servers configured with `protocolVersion: '2026-07-28'` are already stateless and may omit this option.
|
|
342
435
|
|
|
343
436
|
```typescript
|
|
344
437
|
// Supabase Edge Function example
|
|
@@ -412,7 +505,7 @@ serve(async req => {
|
|
|
412
505
|
>
|
|
413
506
|
> This is still stateless: no `mcp-session-id` is required or persisted. It only enables notifications scoped to the current request (such as progress). The session-dependent features below remain unavailable.
|
|
414
507
|
>
|
|
415
|
-
>
|
|
508
|
+
> On the legacy protocol path, the following MCP features require session state or persistent connections and **won't work** in serverless mode (including with `serverlessStreaming: true`):
|
|
416
509
|
>
|
|
417
510
|
> - **Elicitation** - Interactive user input requests during tool execution require session management to route responses back to the correct client
|
|
418
511
|
> - **Resource subscriptions** - `resources/subscribe` and `resources/unsubscribe` need persistent connections to maintain subscription state
|
|
@@ -929,7 +1022,7 @@ Notification methods (`resources.notifyListChanged()`, `prompts.notifyListChange
|
|
|
929
1022
|
|
|
930
1023
|
## Examples
|
|
931
1024
|
|
|
932
|
-
For a practical example of packaging a stdio server, see [Publish a stdio server package](https://mastra.ai/docs/mcp
|
|
1025
|
+
For a practical example of packaging a stdio server, see [Publish a stdio server package](https://mastra.ai/docs/connections/mcp).
|
|
933
1026
|
|
|
934
1027
|
The example at the beginning of this page also demonstrates how to instantiate `MCPServer` with both tools and agents.
|
|
935
1028
|
|
|
@@ -1663,7 +1756,7 @@ const server = new MCPServer({
|
|
|
1663
1756
|
})
|
|
1664
1757
|
```
|
|
1665
1758
|
|
|
1666
|
-
Link a tool to its app resource by setting `mcp._meta.ui.resourceUri` in `createTool()` to the matching `ui://` URI. The server normalizes this metadata for older hosts when listing tools. Visit [MCP Apps](https://mastra.ai/docs/mcp
|
|
1759
|
+
Link a tool to its app resource by setting `mcp._meta.ui.resourceUri` in `createTool()` to the matching `ui://` URI. The server normalizes this metadata for older hosts when listing tools. Visit [MCP Apps](https://mastra.ai/docs/connections/mcp) for the full app bridge API and usage patterns.
|
|
1667
1760
|
|
|
1668
1761
|
## Related information
|
|
1669
1762
|
|