@mastra/mcp 1.8.1 → 1.9.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. package/CHANGELOG.md +77 -0
  2. package/dist/client/client.d.ts +5 -0
  3. package/dist/client/client.d.ts.map +1 -1
  4. package/dist/client/configuration.d.ts +7 -0
  5. package/dist/client/configuration.d.ts.map +1 -1
  6. package/dist/client/types.d.ts +17 -0
  7. package/dist/client/types.d.ts.map +1 -1
  8. package/dist/docs/SKILL.md +2 -1
  9. package/dist/docs/assets/SOURCE_MAP.json +1 -1
  10. package/dist/docs/references/docs-mcp-mcp-apps.md +3 -3
  11. package/dist/docs/references/docs-mcp-overview.md +1 -1
  12. package/dist/docs/references/docs-server-auth-fga.md +258 -0
  13. package/dist/docs/references/reference-tools-mcp-client.md +53 -2
  14. package/dist/docs/references/reference-tools-mcp-server.md +33 -1
  15. package/dist/index.cjs +95 -20
  16. package/dist/index.cjs.map +1 -1
  17. package/dist/index.js +95 -20
  18. package/dist/index.js.map +1 -1
  19. package/dist/server/server.d.ts +3 -0
  20. package/dist/server/server.d.ts.map +1 -1
  21. package/package.json +7 -7
package/CHANGELOG.md CHANGED
@@ -1,5 +1,82 @@
1
1
  # @mastra/mcp
2
2
 
3
+ ## 1.9.0-alpha.1
4
+
5
+ ### Patch Changes
6
+
7
+ - Fixed FGA-enabled MCP servers so OAuth authInfo can be mapped to a Mastra user before tools/list and tools/call authorization. ([#17475](https://github.com/mastra-ai/mastra/pull/17475))
8
+
9
+ - Updated dependencies [[`0c1ed1d`](https://github.com/mastra-ai/mastra/commit/0c1ed1d00c7d87b5ac99ca95896211a2fa9189fa), [`849efb9`](https://github.com/mastra-ai/mastra/commit/849efb9fca6dc976589c1f90a303fea618769109)]:
10
+ - @mastra/core@1.38.0-alpha.8
11
+
12
+ ## 1.9.0-alpha.0
13
+
14
+ ### Minor Changes
15
+
16
+ - Added opt-in MCP server instructions forwarding into agent system prompts. ([#17155](https://github.com/mastra-ai/mastra/pull/17155))
17
+
18
+ When an MCP server advertises instructions during initialization, you can now forward that guidance into the system prompt of agents that use the server's tools. This is **opt-in** — set `forwardInstructions: true` per server to enable it. Forwarded instructions are injected into the agent's system prompt, so only enable this for servers you trust.
19
+
20
+ ```ts
21
+ const mcp = new MCPClient({
22
+ servers: {
23
+ db: {
24
+ url: new URL('http://localhost:4111/mcp'),
25
+ forwardInstructions: true, // opt in; defaults to false
26
+ instructionsMaxLength: 512, // max chars forwarded per server
27
+ },
28
+ },
29
+ });
30
+
31
+ const agent = new Agent({
32
+ id: 'db-agent',
33
+ name: 'DB Agent',
34
+ instructions: 'Help with database changes.',
35
+ model,
36
+ tools: await mcp.listTools(),
37
+ });
38
+ ```
39
+
40
+ You can always inspect cached instructions without forwarding them:
41
+
42
+ ```ts
43
+ const instructions = mcp.getServerInstructions();
44
+ // => { db: 'Always validate before migrating.', other: undefined }
45
+ ```
46
+
47
+ - Added native multimodal tool-result support. Core now converts MCP-style tool results with image and audio `content` parts into model-native media output when building model prompts, without requiring MCP tools to persist duplicate media payloads in `providerMetadata.mastra.modelOutput`. ([#16866](https://github.com/mastra-ai/mastra/pull/16866))
48
+
49
+ ```ts
50
+ return {
51
+ content: [
52
+ { type: 'text', text: 'Screenshot captured' },
53
+ { type: 'image', data: base64Png, mimeType: 'image/png' },
54
+ ],
55
+ };
56
+ ```
57
+
58
+ ### Patch Changes
59
+
60
+ - Support conditional, function-based tool approvals. ([#17337](https://github.com/mastra-ai/mastra/pull/17337))
61
+ - MCP tools that wrap a server-level `requireToolApproval` function are now honored end-to-end. The per-tool approval function was previously dropped when the agent converted MCP tools (it kept only the boolean flag), so conditional approval silently fell back to always-on. `CoreToolBuilder` now preserves a `needsApprovalFn` attached directly to a tool instance.
62
+ - The global `requireToolApproval` option on `agent.stream`/`agent.generate` now accepts a function in addition to a boolean. It is evaluated per tool call with the tool name, arguments, and request context, enabling policies such as regex allowlists on tool names. Returning `true` requires approval for that call; `false` allows it. On error the call defaults to requiring approval. When a function policy is set, tool calls run sequentially so approval suspensions don't race. Durable agents and stored agents continue to accept only a boolean (a function degrades to requiring approval for every call, since their options must be serializable).
63
+
64
+ ```ts
65
+ // Approve only tool calls whose name is not on an allowlist.
66
+ const allowlist = /^(get|list|search)_/;
67
+ await agent.generate('...', {
68
+ requireToolApproval: ({ toolName }) => !allowlist.test(toolName),
69
+ });
70
+ ```
71
+
72
+ - Precedence is unchanged from before: a per-tool approval function (`createTool({ requireApproval: fn })` or an MCP-derived `needsApprovalFn`) is authoritative for that tool and overrides the global setting, so a tool can still opt out of approval by returning `false` even when the global option is on. The only new behavior is that the global option may now be a function in addition to a boolean.
73
+ - The previously implicit, runtime-attached per-tool approval predicate is now a typed contract: `@mastra/core` exports `NeedsApprovalFn` and declares the optional `needsApprovalFn` property on the `Tool` class. The MCP client and the agent runtime now share this typed contract instead of reaching through `any`. This is additive — no public API changes.
74
+
75
+ - Close the stale MCP transport before reconnecting so SSE connections no longer leak orphaned EventSource instances and accumulate server-side sessions on implicit reconnect. ([#17326](https://github.com/mastra-ai/mastra/pull/17326))
76
+
77
+ - Updated dependencies [[`8ace89d`](https://github.com/mastra-ai/mastra/commit/8ace89df77f762e622d3b9f7f65ad7524350d050), [`fa63872`](https://github.com/mastra-ai/mastra/commit/fa6387280954e6b667bec5714b55ba082bc627ff), [`f07b646`](https://github.com/mastra-ai/mastra/commit/f07b64604ab7d25391179790b7fd4823df9e2dff), [`d8838ae`](https://github.com/mastra-ai/mastra/commit/d8838ae80b69780361693d27098f7f6684af12fe), [`40f9297`](https://github.com/mastra-ai/mastra/commit/40f9297003b921c62373d3e8d3a4bda76c9f6de3), [`0f0d1ba`](https://github.com/mastra-ai/mastra/commit/0f0d1ba67bfcb2204e571401662f1eceefc03357), [`8c31bcd`](https://github.com/mastra-ai/mastra/commit/8c31bcdb00e597880d5939b1b7d7566fbe5dacae), [`95b14cd`](https://github.com/mastra-ai/mastra/commit/95b14cdd820e86d97ac05fe568424c513a252e31), [`aa36be2`](https://github.com/mastra-ai/mastra/commit/aa36be23aa513b7dc53cb8ca16b7fab8f20e43ad), [`212c635`](https://github.com/mastra-ai/mastra/commit/212c635203e61d036ab41db8ff86c3893dc795b3), [`d8838ae`](https://github.com/mastra-ai/mastra/commit/d8838ae80b69780361693d27098f7f6684af12fe), [`9aa5a73`](https://github.com/mastra-ai/mastra/commit/9aa5a73e7e110f6e9365eec69364a33d5f03bb56), [`f73c789`](https://github.com/mastra-ai/mastra/commit/f73c789e8ef21561580395d2c410119cab5848c8), [`8bd16da`](https://github.com/mastra-ai/mastra/commit/8bd16da73a4cb874d739373643dbd6a6e7f88684), [`c8630f8`](https://github.com/mastra-ai/mastra/commit/c8630f80d4f40cb5d22e60ab162b618b1907167a), [`47f71dc`](https://github.com/mastra-ai/mastra/commit/47f71dc6fbcbd12d71e21a979e676e20a02bd77d), [`50ceae2`](https://github.com/mastra-ai/mastra/commit/50ceae270878e2f8fb2b2c6c2faab09df0007c8a), [`8cdde58`](https://github.com/mastra-ai/mastra/commit/8cdde5875bbba6702d9df226f2b20232b8d75d6c), [`847ff1e`](https://github.com/mastra-ai/mastra/commit/847ff1e0d94368d94b2e173e4e0908e115568ef3), [`259d409`](https://github.com/mastra-ai/mastra/commit/259d409a514174299dbde1ff5e1121209b3ba850), [`9e16c68`](https://github.com/mastra-ai/mastra/commit/9e16c6818b6485ccb43df28aba6f3a2219d28662), [`cefca33`](https://github.com/mastra-ai/mastra/commit/cefca33ae666e69810c935fedf95a929c173d1d7), [`d00e8c5`](https://github.com/mastra-ai/mastra/commit/d00e8c50daebe5bce5bf2f48bde39c86fc3d2fe4), [`36fa7e2`](https://github.com/mastra-ai/mastra/commit/36fa7e24d14e58a1eb46147097b32f583e5b8775), [`87e9774`](https://github.com/mastra-ai/mastra/commit/87e97741c1e493cd6d62f478eb810b49bda4d57c), [`65a72e7`](https://github.com/mastra-ai/mastra/commit/65a72e70c25eedea8ff985a6624b96be2850236b), [`0f77241`](https://github.com/mastra-ai/mastra/commit/0f7724108806703799a8ba80ad0f09414afd5066), [`92ff509`](https://github.com/mastra-ai/mastra/commit/92ff5098ef8a990438ca038077021a5f7541ec1d), [`3fce5e7`](https://github.com/mastra-ai/mastra/commit/3fce5e70d011d289043e75003ef3336ed4aa43c3), [`a763592`](https://github.com/mastra-ai/mastra/commit/a763592c3db46963ef1011cfe16fe372816e775e), [`80c7737`](https://github.com/mastra-ai/mastra/commit/80c7737e32d7917b5f356957d67c169d01744fd3), [`3f1cf47`](https://github.com/mastra-ai/mastra/commit/3f1cf476f74c1e4cc2df908837e05853a5347e31)]:
78
+ - @mastra/core@1.38.0-alpha.3
79
+
3
80
  ## 1.8.1
4
81
 
5
82
  ### Patch Changes
package/dist/client/client.d.ts CHANGED
@@ -29,6 +29,7 @@ export declare class InternalMastraMCPClient extends MastraBase {
29
29
  private exitHookUnsubscribe?;
30
30
  private sigTermHandler?;
31
31
  private sigHupHandler?;
32
+ private serverInstructions?;
32
33
  private _roots;
33
34
  private readonly requireToolApproval;
34
35
  /** Provides access to resource operations (list, read, subscribe, etc.) */
@@ -122,6 +123,10 @@ export declare class InternalMastraMCPClient extends MastraBase {
122
123
  * @internal
123
124
  */
124
125
  get stderr(): Stream | null;
126
+ get instructions(): string | undefined;
127
+ get forwardInstructions(): boolean;
128
+ get instructionsMaxLength(): number;
129
+ private refreshServerInstructions;
125
130
  disconnect(): Promise<void>;
126
131
  /**
127
132
  * Forces a reconnection to the MCP server by disconnecting and reconnecting.
package/dist/client/client.d.ts.map CHANGED
@@ -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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"}
package/dist/client/configuration.d.ts CHANGED
@@ -533,6 +533,13 @@ export declare class MCPClient extends MastraBase {
533
533
  * ```
534
534
  */
535
535
  reconnectServer(serverName: string): Promise<void>;
536
+ /**
537
+ * Returns instructions advertised by connected MCP servers during initialize.
538
+ *
539
+ * Servers that have not connected yet, or did not advertise instructions,
540
+ * return `undefined`.
541
+ */
542
+ getServerInstructions(): Record<string, string | undefined>;
536
543
  /**
537
544
  * Retrieves all tools from all configured servers with namespaced names.
538
545
  *
package/dist/client/configuration.d.ts.map CHANGED
@@ -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;AAG5C,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAO1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wHAAwH;IACxH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IACnD,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,SAAU,SAAQ,UAAU;IACvC,OAAO,CAAC,aAAa,CAAiD;IACtE,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,iBAAiB,CAA8B;IAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;gBACS,IAAI,EAAE,gBAAgB;IA2ClC;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAW,QAAQ;+BAGc,MAAM,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,QAAQ,CAAC,KAAK,IAAI;MAmBjG;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAW,WAAW;QAGlB;;;;;;;;;;;;;;;;;;WAkBG;gCAC2B,MAAM,WAAW,CAAC,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC;MAmB7G;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAW,SAAS;QAGhB;;;;;;;;;;;;;WAaG;oBACa,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QAwBnD;;;;;;;;;;;;;WAaG;yBACkB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;QAwBhE;;;;;;;;;;;;;WAaG;2BACsB,MAAM,OAAO,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;QAmB5C;;;;;;;;;;;;WAYG;gCAC2B,MAAM,OAAO,MAAM;;;;;;;;;QAmBjD;;;;;;;;;;;;WAYG;kCAC6B,MAAM,OAAO,MAAM;;;;;;;;;QAmBnD;;;;;;;;;;;;;;;WAeG;gCAC2B,MAAM,WAAW,CAAC,MAAM,EAAE;YAAE,GAAG,EAAE,MAAM,CAAA;SAAE,KAAK,IAAI;QAkBhF;;;;;;;;;;;;;;;WAeG;oCAC+B,MAAM,WAAW,MAAM,IAAI;MAmBhE;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,IAAW,OAAO;QAGd;;;;;;;;;;;;;WAaG;oBACa,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAwBjD;;;;;;;;;;;;;;;;;;;WAmBG;0CACqC;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;SAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAmBxG;;;;;;;;;;;;;;;WAeG;oCAC+B,MAAM,WAAW,MAAM,IAAI;MAmBhE;IAED,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,MAAM;IAKd;;;;;;;;;;;;;;OAcG;IACU,UAAU;IAsBvB;;;;;;;;;;;;;;OAcG;IACU,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/D;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IA8B3E;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAK9F;;;;;;;;;;;;;;;;OAgBG;IACU,sBAAsB,IAAI,OAAO,CAAC;QAC7C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;QACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAChC,CAAC;IAgCF;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACI,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;IAU1D;;;;;;;;;;;;;;OAcG;IACH,IAAI,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQvC;IAED;;;;;;;;OAQG;IACI,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;YAM3C,kBAAkB;YA0DlB,2BAA2B;YAQ3B,iBAAiB;CAuBhC"}
1
+ {"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../../src/client/configuration.ts"],"names":[],"mappings":"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"}
package/dist/client/types.d.ts CHANGED
@@ -151,6 +151,23 @@ export type BaseServerOptions = {
151
151
  enableServerLogs?: boolean;
152
152
  /** Whether to enable progress tracking (default: false) */
153
153
  enableProgressTracking?: boolean;
154
+ /**
155
+ * Whether instructions returned by this MCP server during initialization should
156
+ * be forwarded to agents that use the server's tools.
157
+ *
158
+ * Disabled by default: forwarded instructions are injected into the agent's
159
+ * system prompt, so only enable this for servers you trust.
160
+ *
161
+ * @default false
162
+ */
163
+ forwardInstructions?: boolean;
164
+ /**
165
+ * Maximum number of characters of this server's instructions to forward into
166
+ * an agent system prompt.
167
+ *
168
+ * @default 512
169
+ */
170
+ instructionsMaxLength?: number;
154
171
  /**
155
172
  * Whether tools from this server require explicit user approval before execution.
156
173
  *
package/dist/client/types.d.ts.map CHANGED
@@ -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.8.1"
6
+ version: "1.9.0-alpha.1"
7
7
  ---
8
8
 
9
9
  ## When to use
@@ -18,6 +18,7 @@ Read the individual reference documents for detailed explanations and code examp
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
20
  - [MCP overview](references/docs-mcp-overview.md) - Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient, connect to registries, and share your own tools using MCPServer.
21
+ - [Fine-Grained Authorization (FGA)](references/docs-server-auth-fga.md) - Add resource-level authorization to your Mastra application with FGA providers.
21
22
 
22
23
  ### Reference
23
24
 
package/dist/docs/assets/SOURCE_MAP.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.8.1",
2
+ "version": "1.9.0-alpha.1",
3
3
  "package": "@mastra/mcp",
4
4
  "exports": {
5
5
  "UnauthorizedError": {
package/dist/docs/references/docs-mcp-mcp-apps.md CHANGED
@@ -93,7 +93,7 @@ export const myAgent = new Agent({
93
93
  id: 'my-agent',
94
94
  name: 'My Agent',
95
95
  instructions: 'You have access to interactive UI tools.',
96
- model: '__OPENAI_MODEL_MINI__',
96
+ model: 'openai/gpt-5-mini',
97
97
  tools: { calculatorTool },
98
98
  })
99
99
  ```
@@ -125,7 +125,7 @@ const mcpClient = new MCPClient({
125
125
  const myAgent = new Agent({
126
126
  id: 'my-agent',
127
127
  name: 'My Agent',
128
- model: '__OPENAI_MODEL_MINI__',
128
+ model: 'openai/gpt-5-mini',
129
129
  tools: await mcpClient.listTools(),
130
130
  })
131
131
 
@@ -270,7 +270,7 @@ const mcpClient = new MCPClient({
270
270
  const myAgent = new Agent({
271
271
  id: 'my-agent',
272
272
  name: 'My Agent',
273
- model: '__OPENAI_MODEL_MINI__',
273
+ model: 'openai/gpt-5-mini',
274
274
  tools: await mcpClient.listTools(),
275
275
  })
276
276
 
package/dist/docs/references/docs-mcp-overview.md CHANGED
@@ -82,7 +82,7 @@ export const testAgent = new Agent({
82
82
  - US National Weather Service
83
83
 
84
84
  Answer questions using the information you find using the MCP Servers.`,
85
- model: 'openai/gpt-5.4',
85
+ model: 'openai/gpt-5.5',
86
86
  tools: await testMcpClient.listTools(),
87
87
  })
88
88
  ```
package/dist/docs/references/docs-server-auth-fga.md ADDED
@@ -0,0 +1,258 @@
1
+ # Fine-Grained Authorization (FGA)
2
+
3
+ > **Note:** Fine-Grained Authorization is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
4
+
5
+ Fine-Grained Authorization (FGA) adds resource-level permission checks to your Mastra application. While RBAC answers "can this role do this action?", FGA answers **"can this user do this action on this specific resource?"**
6
+
7
+ ## When to use FGA
8
+
9
+ FGA is designed for multi-tenant B2B products where permissions are contextual:
10
+
11
+ - A user might be an **admin** of Team A but only a **member** of Team B
12
+ - Thread access should be limited to the user's own organization
13
+ - Workflow execution should be scoped to a specific team or project
14
+ - Tool access depends on the user's relationship to a resource
15
+
16
+ ## Configuration
17
+
18
+ Configure FGA in your Mastra server config alongside authentication and RBAC:
19
+
20
+ ```typescript
21
+ import { Mastra } from '@mastra/core/mastra';
22
+ import { MastraFGAPermissions } from '@mastra/core/auth/ee';
23
+ import { MastraAuthWorkos, MastraFGAWorkos } from '@mastra/auth-workos';
24
+
25
+ const mastra = new Mastra({
26
+ server: {
27
+ auth: new MastraAuthWorkos({
28
+ /* ... */
29
+ fetchMemberships: true,
30
+ mapUserToResourceId: user => user.teamId,
31
+ }),
32
+ fga: new MastraFGAWorkos({
33
+ resourceMapping: {
34
+ agent: { fgaResourceType: 'team', deriveId: (ctx) => ctx.user.teamId },
35
+ workflow: { fgaResourceType: 'team', deriveId: (ctx) => ctx.user.teamId },
36
+ thread: { fgaResourceType: 'workspace-thread', deriveId: ({ resourceId }) => resourceId },
37
+ },
38
+ permissionMapping: {
39
+ [MastraFGAPermissions.AGENTS_EXECUTE]: 'manage-workflows',
40
+ [MastraFGAPermissions.WORKFLOWS_EXECUTE]: 'manage-workflows',
41
+ [MastraFGAPermissions.MEMORY_READ]: 'read',
42
+ [MastraFGAPermissions.MEMORY_WRITE]: 'update',
43
+ },
44
+ }),
45
+ storedResources: {
46
+ scope: true,
47
+ },
48
+ },
49
+ });
50
+ ```
51
+
52
+ When using `MastraFGAWorkos`, set `fetchMemberships: true` on `MastraAuthWorkos`. WorkOS FGA checks need the user's organization memberships to resolve the correct membership ID for authorization.
53
+
54
+ Use `thread` as the resource-mapping key for memory authorization. `MastraFGAWorkos` still accepts the legacy alias `memory`, but new configs should prefer `thread`.
55
+
56
+ When `server.fga` is configured, Mastra enforces FGA on protected actions. If a protected action has no authenticated user, Mastra denies it. If `server.fga` is not configured, these FGA checks are skipped and Mastra keeps the previous behavior.
57
+
58
+ ### Resource mapping
59
+
60
+ The `resourceMapping` tells Mastra how to resolve FGA resource types and IDs from request context. Keys are Mastra resource types, values define the FGA resource type and how to derive the ID:
61
+
62
+ ```typescript
63
+ resourceMapping: {
64
+ // When checking "can user execute agent X?", resolve the FGA resource
65
+ // as the user's team (type: 'team', id: user.teamId)
66
+ agent: {
67
+ fgaResourceType: 'team',
68
+ deriveId: (ctx) => ctx.user.teamId,
69
+ },
70
+ }
71
+ ```
72
+
73
+ `deriveId()` receives:
74
+
75
+ - `user` — the authenticated user
76
+ - `resourceId` — the owning Mastra resource ID when available (for example, a thread's `resourceId`)
77
+ - `requestContext` — the current request context for advanced tenant resolution
78
+ - `metadata` — provider-specific metadata for the attempted action
79
+
80
+ Return `undefined` from `deriveId()` to fall back to the original Mastra resource ID.
81
+
82
+ For thread and memory checks, Mastra still passes the raw `threadId` as the resource being checked, but it also forwards the thread's owning `resourceId` into `deriveId()`. This lets you map thread permissions to composite tenant IDs such as `userId-teamId-orgId`.
83
+
84
+ ### Permission mapping
85
+
86
+ The `permissionMapping` translates Mastra's internal permission strings to your FGA provider's permission slugs:
87
+
88
+ ```typescript
89
+ import { MastraFGAPermissions } from '@mastra/core/auth/ee';
90
+
91
+ permissionMapping: {
92
+ [MastraFGAPermissions.AGENTS_EXECUTE]: 'manage-workflows', // Mastra permission -> WorkOS permission slug
93
+ [MastraFGAPermissions.MEMORY_READ]: 'read',
94
+ }
95
+ ```
96
+
97
+ If no mapping exists for a permission, the original string is passed through.
98
+
99
+ Use `validatePermissions()` to validate the full set of permissions Mastra may emit at startup. Use this when a provider requires every Mastra permission to have an explicit provider permission slug.
100
+
101
+ ### Stored resource scoping
102
+
103
+ FGA authorizes access to a resource. It does not automatically filter stored records that live in shared storage. Enable stored resource scoping when the built-in stored resource APIs are used in a multi-tenant app.
104
+
105
+ ```typescript
106
+ const mastra = new Mastra({
107
+ server: {
108
+ auth: new MastraAuthWorkos({
109
+ /* ... */
110
+ mapUserToResourceId: user => user.teamId,
111
+ }),
112
+ storedResources: {
113
+ scope: true,
114
+ },
115
+ },
116
+ });
117
+ ```
118
+
119
+ With `scope: true`, Mastra reads `MASTRA_RESOURCE_ID_KEY` from the request context. `mapUserToResourceId()` sets this value after authentication. Stored resource handlers persist the scope in record metadata and filter list, read, update, publish, and delete operations by that scope.
120
+
121
+ Use an object when the scope needs custom request logic:
122
+
123
+ ```typescript
124
+ storedResources: {
125
+ scope: {
126
+ metadataKey: 'teamId',
127
+ resolve: ({ user }) => user.teamId,
128
+ requireScope: true,
129
+ },
130
+ },
131
+ ```
132
+
133
+ If `requireScope` is `true` or omitted, scoped stored resource routes fail when no scope can be resolved.
134
+
135
+ ### Route policy coverage
136
+
137
+ Mastra includes route-level FGA metadata for built-in resource routes, including agents, workflows, tools, MCP tools, memory threads, responses, conversations, and stored resources. Stored resource route coverage includes `/stored/agents`, `/stored/mcp-clients`, `/stored/prompt-blocks`, `/stored/scorers`, `/stored/skills`, and `/stored/workspaces`. A route is checked when it has route-level `fga` metadata, when Mastra can derive built-in metadata for that route, or when the provider supplies metadata with `resolveRouteFGA()`.
138
+
139
+ To deny protected routes that do not resolve FGA metadata, configure route policy coverage on the FGA provider:
140
+
141
+ ```typescript
142
+ const fga = new MastraFGAWorkos({
143
+ resourceMapping: {
144
+ project: { fgaResourceType: 'project' },
145
+ },
146
+ permissionMapping: {
147
+ 'projects:read': 'read',
148
+ },
149
+ requireForProtectedRoutes: true,
150
+ auditProtectedRoutes: 'warn',
151
+ validatePermissions: async permissions => {
152
+ // Throw if a Mastra permission is missing from permissionMapping.
153
+ },
154
+ });
155
+ ```
156
+
157
+ Set `auditProtectedRoutes: 'error'` to fail startup when protected routes are missing built-in FGA metadata. If `requireForProtectedRoutes` is enabled, Mastra logs this audit as a warning by default.
158
+
159
+ For custom routes, prefer route-level `fga` metadata. This keeps authorization policy next to the route:
160
+
161
+ ```typescript
162
+ import { createRoute } from '@mastra/server/server-adapter';
163
+
164
+ export const getProjectRoute = createRoute({
165
+ method: 'GET',
166
+ path: '/projects/:projectId',
167
+ responseType: 'json',
168
+ requiresAuth: true,
169
+ fga: {
170
+ resourceType: 'project',
171
+ resourceIdParam: 'projectId',
172
+ permission: 'projects:read',
173
+ },
174
+ handler: async () => {
175
+ return { project: null };
176
+ },
177
+ });
178
+ ```
179
+
180
+ Use `resolveRouteFGA()` only when route metadata must be derived centrally from route, params, or request context. A route map scales better than string-prefix checks:
181
+
182
+ ```typescript
183
+ import type { FGARouteConfig, FGARouteResolver } from '@mastra/core/auth/ee';
184
+
185
+ const routeFGA = {
186
+ 'GET /billing/:accountId': {
187
+ resourceType: 'account',
188
+ resourceIdParam: 'accountId',
189
+ permission: 'billing:read',
190
+ },
191
+ } satisfies Record<string, FGARouteConfig>;
192
+
193
+ const resolveRouteFGA: FGARouteResolver = ({ route }) => routeFGA[`${route.method} ${route.path}`];
194
+
195
+ const fga = new MastraFGAWorkos({
196
+ /* ... */
197
+ resolveRouteFGA,
198
+ });
199
+ ```
200
+
201
+ ## Enforcement points
202
+
203
+ When an FGA provider is configured, Mastra automatically checks authorization at these lifecycle points:
204
+
205
+ | Lifecycle point | Permission checked | Resource type | Resource ID |
206
+ | ---------------------------------------------------------------- | ----------------------------------------------- | -------------------- | ------------------------------------------------------------------- |
207
+ | Agent execution (`generate`, `stream`) | `agents:execute` | `agent` | `agentId` |
208
+ | Built-in workflow HTTP execution routes and `Workflow.execute()` | `workflows:execute` | `workflow` | `workflowId` |
209
+ | Standalone tool execution | `tools:execute` | `tool` | `toolName` |
210
+ | Agent tool execution | `tools:execute` | `tool` | `${agentId}:${toolName}` |
211
+ | MCP tool execution | `tools:execute` | `tool` | `JSON.stringify([serverName, toolName])` |
212
+ | Thread and memory access | `memory:read`, `memory:write`, `memory:delete` | `thread` | `threadId` |
213
+ | Stored resource routes | Stored resource permission for the route action | Stored resource type | Route record ID, or the stored-resource scope for collection routes |
214
+ | HTTP resource routes | Configured per route | Configured per route | Configured per route |
215
+
216
+ For OAuth-protected MCP servers, HTTP MCP transports pass authenticated data as `extra.authInfo`. If an `MCPServer` is registered on an FGA-enabled Mastra instance, configure `mapAuthInfoToUser` so Mastra can set `requestContext.get('user')` before checking `tools/list` and `tools/call`. See [MCPServer authentication context](https://mastra.ai/reference/tools/mcp-server).
217
+
218
+ Direct SDK calls to `createRun().start()`, `resume()`, or `restart()` are not independently checked by core FGA in this release. Make those calls from a protected route or guard them in application code. Pass a `requestContext` with an authenticated user when invoking protected entry points directly.
219
+
220
+ Core agent, internal workflow, tool, and memory checks also pass `requestContext` and action metadata to the FGA provider. Route checks pass `requestContext`. Thread checks pass the owning `resourceId` when available.
221
+
222
+ ## Custom FGA provider
223
+
224
+ Implement `IFGAProvider` to use any FGA backend:
225
+
226
+ ```typescript
227
+ import { FGADeniedError } from '@mastra/core/auth/ee'
228
+ import type { FGACheckParams, IFGAProvider, MastraFGAPermissionInput } from '@mastra/core/auth/ee'
229
+
230
+ class MyFGAProvider implements IFGAProvider {
231
+ async check(user: any, params: FGACheckParams): Promise<boolean> {
232
+ // Your authorization logic
233
+ return true
234
+ }
235
+
236
+ async require(user: any, params: FGACheckParams): Promise<void> {
237
+ const allowed = await this.check(user, params)
238
+ if (!allowed) {
239
+ throw new FGADeniedError(user, params.resource, params.permission)
240
+ }
241
+ }
242
+
243
+ async filterAccessible<T extends { id: string }>(
244
+ user: any,
245
+ resources: T[],
246
+ resourceType: string,
247
+ permission: MastraFGAPermissionInput,
248
+ ): Promise<T[]> {
249
+ // Filter resources the user can access
250
+ return resources
251
+ }
252
+ }
253
+ ```
254
+
255
+ ## Related
256
+
257
+ - [Authentication overview](https://mastra.ai/docs/server/auth)
258
+ - [WorkOS authentication](https://mastra.ai/docs/server/auth/workos)
package/dist/docs/references/reference-tools-mcp-client.md CHANGED
@@ -53,6 +53,10 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
53
53
 
54
54
  **enableServerLogs** (`boolean`): Whether to enable logging for this server. (Default: `true`)
55
55
 
56
+ **forwardInstructions** (`boolean`): Whether to append instructions advertised by this MCP server to an agent's system prompt when the agent uses this server's tools. Disabled by default; enable it only for servers you trust, since the instructions are injected into the agent's system prompt. (Default: `false`)
57
+
58
+ **instructionsMaxLength** (`number`): Maximum number of server instruction characters to append to an agent's system prompt. (Default: `512`)
59
+
56
60
  **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.
57
61
 
58
62
  ## Tool approval
@@ -123,6 +127,36 @@ Per the MCP specification, **clients MUST consider tool annotations to be untrus
123
127
 
124
128
  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.
125
129
 
130
+ ## Server instructions
131
+
132
+ When an MCP server advertises instructions during initialization, `MCPClient` stores them for that server. Forwarding those instructions into an agent's system prompt is **opt-in**: set `forwardInstructions: true` on a server to have agents that use its tools (via `listTools()` or `listToolsets()`) receive its instructions automatically.
133
+
134
+ The guidance is grouped by server name and truncated to `instructionsMaxLength` characters per server.
135
+
136
+ ```typescript
137
+ const mcp = new MCPClient({
138
+ servers: {
139
+ db: {
140
+ url: new URL('http://localhost:3000/mcp'),
141
+ forwardInstructions: true,
142
+ instructionsMaxLength: 512,
143
+ },
144
+ },
145
+ })
146
+
147
+ const agent = new Agent({
148
+ id: 'db-agent',
149
+ name: 'DB Agent',
150
+ instructions: 'Help with database changes.',
151
+ model,
152
+ tools: await mcp.listTools(),
153
+ })
154
+ ```
155
+
156
+ When `forwardInstructions` is omitted (the default), instructions are still cached and can be inspected via [`getServerInstructions()`](#getserverinstructions), but are not added to any agent's system prompt.
157
+
158
+ > **Security note:** server instructions are forwarded verbatim (subject only to length truncation) into the agent's system prompt. A malicious or compromised MCP server can use them to inject instructions the agent will treat as trusted system guidance. Only enable `forwardInstructions` for servers you trust, and prefer reviewing instructions with `getServerInstructions()` before forwarding instructions from third-party servers.
159
+
126
160
  ## Methods
127
161
 
128
162
  ### `listTools()`
@@ -143,6 +177,23 @@ const res = await agent.stream(prompt, {
143
177
  })
144
178
  ```
145
179
 
180
+ ### `getServerInstructions()`
181
+
182
+ Returns the instructions currently known for each configured MCP server. Servers that have not connected yet, or do not advertise instructions, return `undefined`.
183
+
184
+ ```typescript
185
+ getServerInstructions(): Record<string, string | undefined>
186
+ ```
187
+
188
+ Example:
189
+
190
+ ```typescript
191
+ await mcp.listTools()
192
+
193
+ const instructionsByServer = mcp.getServerInstructions()
194
+ console.log(instructionsByServer.db)
195
+ ```
196
+
146
197
  ### `disconnect()`
147
198
 
148
199
  Disconnects from all MCP servers and cleans up resources.
@@ -839,7 +890,7 @@ const agent = new Agent({
839
890
  id: 'multi-tool-agent',
840
891
  name: 'Multi-tool Agent',
841
892
  instructions: 'You have access to multiple tool servers.',
842
- model: 'openai/gpt-5.4',
893
+ model: 'openai/gpt-5.5',
843
894
  tools: await mcp.listTools(),
844
895
  })
845
896
 
@@ -890,7 +941,7 @@ const agent = new Agent({
890
941
  id: 'multi-tool-agent',
891
942
  name: 'Multi-tool Agent',
892
943
  instructions: 'You help users check stocks and weather.',
893
- model: 'openai/gpt-5.4',
944
+ model: 'openai/gpt-5.5',
894
945
  })
895
946
 
896
947
  // Later, configure MCP with user-specific settings