@mastra/mcp 1.16.0-alpha.2 → 1.17.0-alpha.0

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 (17) hide show
  1. package/CHANGELOG.md +99 -0
  2. package/dist/client/configuration.d.ts +11 -3
  3. package/dist/client/configuration.d.ts.map +1 -1
  4. package/dist/docs/SKILL.md +4 -3
  5. package/dist/docs/assets/SOURCE_MAP.json +1 -1
  6. package/dist/docs/references/docs-connections-overview.md +1 -1
  7. package/dist/docs/references/docs-mcp-overview.md +47 -6
  8. package/dist/docs/references/docs-server-auth-fga.md +1 -1
  9. package/dist/docs/references/reference-editor-tools.md +1 -1
  10. package/dist/docs/references/reference-migrations-upgrade-to-v1-mcp.md +99 -0
  11. package/dist/docs/references/reference-tools-mcp-client.md +37 -8
  12. package/dist/docs/references/reference-tools-mcp-server.md +10 -7
  13. package/dist/index.cjs +44 -16
  14. package/dist/index.cjs.map +1 -1
  15. package/dist/index.js +44 -16
  16. package/dist/index.js.map +1 -1
  17. package/package.json +9 -9
package/CHANGELOG.md CHANGED
@@ -1,5 +1,104 @@
1
1
  # @mastra/mcp
2
2
 
3
+ ## 1.17.0-alpha.0
4
+
5
+ ### Minor Changes
6
+
7
+ - Added per-server time budgets and duration metrics to MCP discovery methods. ([#21560](https://github.com/mastra-ai/mastra/pull/21560))
8
+
9
+ ```typescript
10
+ const { tools, errors, durations } = await mcp.listToolsWithErrors({
11
+ perServerTimeoutMs: 3_000,
12
+ });
13
+ ```
14
+
15
+ ### Patch Changes
16
+
17
+ - Updated dependencies [[`d7e6745`](https://github.com/mastra-ai/mastra/commit/d7e67456954863c55440ea9c49bc6ceb9949972d), [`9acb50f`](https://github.com/mastra-ai/mastra/commit/9acb50f71cec9c362f06820033f90ae6b1f8282f), [`46e9e3f`](https://github.com/mastra-ai/mastra/commit/46e9e3f73babe1bc70080a596cf2ac0b9da48519), [`3f9a190`](https://github.com/mastra-ai/mastra/commit/3f9a19057c027155867b9317294ee4ca7bd0581a), [`e8808e3`](https://github.com/mastra-ai/mastra/commit/e8808e3d8eb585a2565be53e56a7e0e1477352a4), [`d4be8c1`](https://github.com/mastra-ai/mastra/commit/d4be8c1739d22d621e3f78790e1dd5eb5ecc3589), [`a5d2eb1`](https://github.com/mastra-ai/mastra/commit/a5d2eb10347eade1ae2816d88f466c25186c54a5), [`e81744c`](https://github.com/mastra-ai/mastra/commit/e81744cd13c46619c142dc521dc0baac47607a84)]:
18
+ - @mastra/core@1.60.0-alpha.4
19
+
20
+ ## 1.16.0
21
+
22
+ ### Minor Changes
23
+
24
+ - Updated the MCP client and server to run on the MCP 2.0 packages. Request context, authentication, logging, and progress behavior are unchanged, so tools that read `context.mcp.extra.authInfo`, send progress, or use elicitation keep working as before. ([#18683](https://github.com/mastra-ai/mastra/pull/18683))
25
+
26
+ Tool schemas advertised over MCP no longer declare a draft-07 `$schema` dialect. The MCP 2.0 default validator rejects that dialect, which previously made tools with output schemas fail on the client.
27
+
28
+ **If you pass a custom schema validator**
29
+
30
+ The optional `jsonSchemaValidator` option now takes its validator from the MCP packages. Update the import path:
31
+
32
+ ```ts
33
+ // Before
34
+ import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/cfworker';
35
+
36
+ // After
37
+ import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/client/validators/cf-worker';
38
+
39
+ const mcp = new MCPClient({
40
+ servers: {
41
+ weather: { url: new URL('https://example.com/mcp'), jsonSchemaValidator: new CfWorkerJsonSchemaValidator() },
42
+ },
43
+ });
44
+ ```
45
+
46
+ **If you import MCP protocol types directly**
47
+
48
+ Types re-exported by `@mastra/mcp` (such as `ToolAnnotations`, `LoggingLevel`, and the OAuth helpers) are unchanged and need no edits. Only imports that reached past `@mastra/mcp` into `@modelcontextprotocol/sdk` need repointing to `@modelcontextprotocol/client` or `@modelcontextprotocol/server`.
49
+
50
+ - Add opt-in security hardening options to the MCP client. Both options are opt-in; default behavior is unchanged. ([#20868](https://github.com/mastra-ai/mastra/pull/20868))
51
+
52
+ - `allowedHosts` on HTTP server configs restricts which hosts the client's HTTP requests may target, covering the initial connection, the SSE fallback, and OAuth discovery. On the default fetch path redirect hops are blocked before they are sent; with a custom `fetch`, the final response URL is validated after the request runs, so custom fetch implementations must enforce redirect policy themselves when preventing outbound contact is required.
53
+ - `inheritDefaultEnv: false` on stdio server configs stops the subprocess from inheriting the SDK's default environment variables; only the entries you list in `env` are passed.
54
+
55
+ ```typescript
56
+ const mcp = new MCPClient({
57
+ servers: {
58
+ weather: {
59
+ url: new URL('https://weather.example/mcp'),
60
+ allowedHosts: ['weather.example'],
61
+ },
62
+ local: {
63
+ command: 'npx',
64
+ args: ['tsx', 'stdio-server.ts'],
65
+ inheritDefaultEnv: false,
66
+ env: { WEATHER_API_KEY: process.env.WEATHER_API_KEY! },
67
+ },
68
+ },
69
+ });
70
+ ```
71
+
72
+ - Add serializable MCP tool definitions and lazy hydration. ([#21119](https://github.com/mastra-ai/mastra/pull/21119))
73
+
74
+ `MCPClient` can now export its tool catalog as plain JSON and rebuild executable tools from it later, without reconnecting at startup. This removes the need to connect to every MCP server on every cold start just to discover tools that may never be called.
75
+
76
+ - `listToolDefinitions()` returns definitions grouped by server and keyed by tool name. The result is JSON-serializable, so it can be cached in Redis, a database, or a build artifact.
77
+ - `listToolDefinitionsWithErrors()` also reports per-server failures, so a partial catalog isn't cached silently.
78
+ - `toolFromDefinition({ serverName, definition })` rebuilds a single tool from a cached definition.
79
+ - `toolsFromDefinitions({ definitions })` rebuilds a whole namespaced tool map, matching the `serverName_toolName` keys from `listTools()`.
80
+
81
+ Hydrated tools connect lazily on first execution and behave the same as discovered tools, including strict-mode metadata, approval policies, structured content, tool error handling, progress metadata, abort signals, and reconnect and retry behavior. Definitions capture the server version and instructions recorded at discovery time so that metadata isn't lost.
82
+
83
+ Existing `listTools()` and `listToolsets()` behavior is unchanged.
84
+
85
+ ### Patch Changes
86
+
87
+ - Fix SSE transport fallback against MCP 2.0 servers. The Streamable HTTP transport reports non-OK responses as `SdkHttpError`, which carries the HTTP status on `status` while `code` holds a string error code, so the fallback check read a string where it expected a status number and rethrew instead of retrying over the deprecated HTTP+SSE transport. Servers that only speak HTTP+SSE are reachable again. ([#18683](https://github.com/mastra-ai/mastra/pull/18683))
88
+
89
+ - **Fixed spurious MCP reconnects when tool-execution errors contain transport-like substrings.** ([#20793](https://github.com/mastra-ai/mastra/pull/20793))
90
+
91
+ When an MCP tool returns an in-band error (\`isError: true\`) whose text contains words like "session", "404", or "connection closed", the client no longer misclassifies it as a transport failure and triggers a reconnect + retry. This prevents duplicate calls for non-idempotent tools (e.g. payments, writes).
92
+
93
+ **Surface the real failure after a failed reconnect.**
94
+
95
+ When a transport-level reconnect fails, the caller now receives the actual reconnection error instead of the stale tool/transport error that triggered the recovery attempt.
96
+
97
+ - Fixed MCP tools with outputSchema to send LLM-facing content text to the model via toModelOutput while keeping structuredContent on tool.execute() results. ([#20176](https://github.com/mastra-ai/mastra/pull/20176))
98
+
99
+ - Updated dependencies [[`e7109ee`](https://github.com/mastra-ai/mastra/commit/e7109ee6f731bacc79c885906f3c7dca8d8f013a), [`b8ce7ec`](https://github.com/mastra-ai/mastra/commit/b8ce7ec96e39343c6c2f36d12d68a9ad816c09f7), [`2e4624e`](https://github.com/mastra-ai/mastra/commit/2e4624edb6917e61249cb60ee377735e7af7e4a9), [`45a9147`](https://github.com/mastra-ai/mastra/commit/45a914741f578754d79d8b7de7b4e4f304d8e14a), [`a3a3624`](https://github.com/mastra-ai/mastra/commit/a3a3624f646b98e409424d8defccbd334da9e8b8), [`6246914`](https://github.com/mastra-ai/mastra/commit/62469146636911f3cbbe0880bd011c6a897a59a7), [`6445eba`](https://github.com/mastra-ai/mastra/commit/6445eba6020abac681aba1cc9289f446cb400cbe), [`86b7b77`](https://github.com/mastra-ai/mastra/commit/86b7b777980d30f66e1fd134a37d2af4c22e54cc), [`1c75e32`](https://github.com/mastra-ai/mastra/commit/1c75e32f7fc0b9fb6f548b4407feaec8a1440212), [`296dc9a`](https://github.com/mastra-ai/mastra/commit/296dc9af29f3616e786c7825ec32e0df92d754c5), [`f59032a`](https://github.com/mastra-ai/mastra/commit/f59032a73699443555a08a479e7ac578975784f2), [`cdd5c33`](https://github.com/mastra-ai/mastra/commit/cdd5c33ac6c7118a9f139e6dc0e14e6a8ae31658), [`3f73c07`](https://github.com/mastra-ai/mastra/commit/3f73c076727e8c36b4fff7a1b40290fb68957fa8), [`772c0c8`](https://github.com/mastra-ai/mastra/commit/772c0c897cec383258de2e6178147f8014767c7b), [`d7cf7fa`](https://github.com/mastra-ai/mastra/commit/d7cf7fafc1ae1b50bd8462dd0e6c671a8606db93), [`7c1ebb1`](https://github.com/mastra-ai/mastra/commit/7c1ebb15690c4b3f0eabb19077cf8af573311e57), [`0f9a448`](https://github.com/mastra-ai/mastra/commit/0f9a448502157e59f7b76f24360ad497168f5ef8), [`578bf2e`](https://github.com/mastra-ai/mastra/commit/578bf2e6a88e9d5b8bf502204e15a95dfbb679ae), [`c47165c`](https://github.com/mastra-ai/mastra/commit/c47165c983c87594c6952f1fd2fa51a90205034c), [`289f4ce`](https://github.com/mastra-ai/mastra/commit/289f4ce16e3293370440172132c52ee787cbc09f), [`df31eb0`](https://github.com/mastra-ai/mastra/commit/df31eb0c7087d782a0d9346e467f9a4af4b0eef6), [`9571e3a`](https://github.com/mastra-ai/mastra/commit/9571e3a06ed2c5220196460bf82a2129255c3a8b), [`4f16ff8`](https://github.com/mastra-ai/mastra/commit/4f16ff824bf2f9b0ddc93f210477c10c8a4fb1ab), [`b4c89b4`](https://github.com/mastra-ai/mastra/commit/b4c89b4371b0c86da57403ad1a3b3ef0681f3128), [`e6534fa`](https://github.com/mastra-ai/mastra/commit/e6534fab031216f6cb48c4c9907cbfdce9d60bc6), [`210cb7a`](https://github.com/mastra-ai/mastra/commit/210cb7a167998c7bbf72cb3b93e6eb0563330239), [`06b2d87`](https://github.com/mastra-ai/mastra/commit/06b2d87e63bcdd0ed59215c6789692b9b12de376), [`1c67d85`](https://github.com/mastra-ai/mastra/commit/1c67d85e9da8285662f4dbbf47e0378c3fee0747), [`ac01d63`](https://github.com/mastra-ai/mastra/commit/ac01d6355974aec73fdb8781449ed12bac582094), [`80a3324`](https://github.com/mastra-ai/mastra/commit/80a33245d3110204de6f56d61211523ffe338692), [`e44e8f3`](https://github.com/mastra-ai/mastra/commit/e44e8f370b66c339ddcaba946d33da6d3c3f06cd), [`d9d2881`](https://github.com/mastra-ai/mastra/commit/d9d2881ede6dd6c023d144215fc812062aed0890), [`a810a05`](https://github.com/mastra-ai/mastra/commit/a810a058f62ad407cfc1701e0be36ae91145d7cf), [`ba24be6`](https://github.com/mastra-ai/mastra/commit/ba24be662439c331ab23a600041f93803c89eca8), [`842b5fe`](https://github.com/mastra-ai/mastra/commit/842b5fe22b6a7fa811bd14e48eb9af523ac989f2), [`990611b`](https://github.com/mastra-ai/mastra/commit/990611ba76eb876d86c9c594371ae5f02f94b432), [`80bdf3a`](https://github.com/mastra-ai/mastra/commit/80bdf3ae16ade6ff63bde0cb16fa2df8ab7dd4dd), [`c967a5e`](https://github.com/mastra-ai/mastra/commit/c967a5eec150c5dc5418c4a4388982d1fb7ad27c), [`dc4a25d`](https://github.com/mastra-ai/mastra/commit/dc4a25d41af4e2fe97a816070eaec6aa963ab53b), [`9ba1247`](https://github.com/mastra-ai/mastra/commit/9ba12470c77f1c03642d720ce67e517e878f666e), [`fd96298`](https://github.com/mastra-ai/mastra/commit/fd96298a8367622f4ebfcaa97b5b6c1fbbd14564), [`66bbfb5`](https://github.com/mastra-ai/mastra/commit/66bbfb5f05b473d39f88c0e4a481ccac41634f3a), [`dc4a25d`](https://github.com/mastra-ai/mastra/commit/dc4a25d41af4e2fe97a816070eaec6aa963ab53b), [`f8da216`](https://github.com/mastra-ai/mastra/commit/f8da21633e7eb0e31c9ce0fc30567870d19416d3), [`4a09a9c`](https://github.com/mastra-ai/mastra/commit/4a09a9c0474ef643558fcb5f0edc542b82f1cab0), [`5f798b3`](https://github.com/mastra-ai/mastra/commit/5f798b3362e9bdf4d690f85245606e146eef60b9), [`6a84954`](https://github.com/mastra-ai/mastra/commit/6a84954a2667f85b6d59da652dab1bbff007ccb0), [`1e83a47`](https://github.com/mastra-ai/mastra/commit/1e83a4734ab61ba5926af6793e3569a78b72ed37), [`52d8ef0`](https://github.com/mastra-ai/mastra/commit/52d8ef03801f1deb7ee48532fc4190dd4a33916c), [`cdd5c33`](https://github.com/mastra-ai/mastra/commit/cdd5c33ac6c7118a9f139e6dc0e14e6a8ae31658), [`7fdcaa6`](https://github.com/mastra-ai/mastra/commit/7fdcaa66105d64290f9b14432a12ec99f39c4d3a), [`d6c56f9`](https://github.com/mastra-ai/mastra/commit/d6c56f951db3213330b98b0abafa9778c8770e58), [`e08e789`](https://github.com/mastra-ai/mastra/commit/e08e789c1bf4cd2fe46363f7a4728536ceccc9bd), [`bf936e2`](https://github.com/mastra-ai/mastra/commit/bf936e2c89b2ff0dad5695b873ddc009ba96d41e), [`7fb580a`](https://github.com/mastra-ai/mastra/commit/7fb580ac73fbcacf2ff00872a3395f73ae1b9fa5), [`ed5d606`](https://github.com/mastra-ai/mastra/commit/ed5d606739c5e3fbdfa9f272df7809aa5ab43b1d), [`f53d5bd`](https://github.com/mastra-ai/mastra/commit/f53d5bd4885b29e4ac29a428a6044088ea8d6aa3), [`32980a3`](https://github.com/mastra-ai/mastra/commit/32980a3e2413d0274ac244d32c37d910edc13f00), [`01a2943`](https://github.com/mastra-ai/mastra/commit/01a2943a7d886edefdff072bfa51f055bab54437), [`82e3365`](https://github.com/mastra-ai/mastra/commit/82e3365ef7c9bf7bee2e7a7029035ea262d68895), [`6104347`](https://github.com/mastra-ai/mastra/commit/61043473ba6bfd0a25156824e853e13165562e6c), [`35cc901`](https://github.com/mastra-ai/mastra/commit/35cc90102cf834a84827acaf9eee0b6d6d1e2a3b), [`a8b4cf0`](https://github.com/mastra-ai/mastra/commit/a8b4cf02823cffebc4751a53337dfacf097c1ae1), [`9571e3a`](https://github.com/mastra-ai/mastra/commit/9571e3a06ed2c5220196460bf82a2129255c3a8b), [`333785c`](https://github.com/mastra-ai/mastra/commit/333785c93cbb01e42c60167e995457c28897ddbf), [`bda2235`](https://github.com/mastra-ai/mastra/commit/bda22353ee28f2df0eaea555f7cae1549f979c0b), [`efd5c81`](https://github.com/mastra-ai/mastra/commit/efd5c81cc25fde3c2ddd86fc1178deb4ec176e19), [`1b482c2`](https://github.com/mastra-ai/mastra/commit/1b482c2d89244dd758c41e5f927a2b44041388d2), [`45bfb88`](https://github.com/mastra-ai/mastra/commit/45bfb88fd52f1dd3be20e2a38905777c96499c90), [`ff28284`](https://github.com/mastra-ai/mastra/commit/ff2828416f14daff9d956e6a352fdaa23c950979), [`4bcdfaf`](https://github.com/mastra-ai/mastra/commit/4bcdfaf0eac3199d7cb171b0a19a92c9c341eea4), [`e3b9307`](https://github.com/mastra-ai/mastra/commit/e3b9307098daefbfae2a52ae2ef51bc9fc701190), [`d6834c5`](https://github.com/mastra-ai/mastra/commit/d6834c5a7866b16734d23900163c2414ed70d791), [`f33264f`](https://github.com/mastra-ai/mastra/commit/f33264f517ae603279afd5c4251e2b40f6dd3618), [`689f2c4`](https://github.com/mastra-ai/mastra/commit/689f2c4b6c0835fe455702b01d21daa8abcd9331), [`fcd0667`](https://github.com/mastra-ai/mastra/commit/fcd0667a4e378be35c9a1b1eb19cce78fbfd7282), [`cfd0d9e`](https://github.com/mastra-ai/mastra/commit/cfd0d9ec77ec3c69dd96f79cdb579e03d79f22ce), [`acc3513`](https://github.com/mastra-ai/mastra/commit/acc3513b19f79bf0a7ec2998694580edca54086c), [`1670533`](https://github.com/mastra-ai/mastra/commit/1670533986f6bacf567746245348125e3a106448), [`a7eb4a1`](https://github.com/mastra-ai/mastra/commit/a7eb4a11450f6170274ed5141bffe821d4fdd5a6), [`0976933`](https://github.com/mastra-ai/mastra/commit/0976933142333ec78451feef265b68bcb45aa5e7), [`242b945`](https://github.com/mastra-ai/mastra/commit/242b94558777bfbdeb42cbfea84afff0b6ad0633), [`c52d346`](https://github.com/mastra-ai/mastra/commit/c52d3462ec831a5d95926ecd3d3373f5928ad2e5), [`af4636a`](https://github.com/mastra-ai/mastra/commit/af4636a74463275d71c1d13a38f7d2b738f128bf), [`01a2943`](https://github.com/mastra-ai/mastra/commit/01a2943a7d886edefdff072bfa51f055bab54437), [`2eabc09`](https://github.com/mastra-ai/mastra/commit/2eabc097d86d52fbd0123da36a7c874154cc384f), [`0023e79`](https://github.com/mastra-ai/mastra/commit/0023e7919431078280abd11c89d1edeae35fcc69), [`c2ad51e`](https://github.com/mastra-ai/mastra/commit/c2ad51e2467f901eecba8c9f4a45e22a50bd7c18), [`25ca73d`](https://github.com/mastra-ai/mastra/commit/25ca73d25dee7ce9f0ca72939e3a505c4db7257e), [`2f9ef3f`](https://github.com/mastra-ai/mastra/commit/2f9ef3f4ca06fc2dcdd5088c26b7f4da6a016791), [`e7eefcb`](https://github.com/mastra-ai/mastra/commit/e7eefcb162cda7c493e8c3bf43050ead0efbcb2c), [`fea5cae`](https://github.com/mastra-ai/mastra/commit/fea5caedc7e2cfea51784a15e015952692027abf), [`4d7aca2`](https://github.com/mastra-ai/mastra/commit/4d7aca2fe75f225c83d1502d63079568e6ec163f), [`e1cead1`](https://github.com/mastra-ai/mastra/commit/e1cead17b5f3653cf00d2f90cc19b113119c02ba), [`01a2943`](https://github.com/mastra-ai/mastra/commit/01a2943a7d886edefdff072bfa51f055bab54437), [`d9d93b2`](https://github.com/mastra-ai/mastra/commit/d9d93b25e4a65ad5fa153fa35be7ed149c8d587f), [`c4ec889`](https://github.com/mastra-ai/mastra/commit/c4ec889561c0264c43f66d04d587bee4ce35e792), [`4b59f78`](https://github.com/mastra-ai/mastra/commit/4b59f786cbc9a7d1ef07a07517dbd4b96865e99d), [`eeae63e`](https://github.com/mastra-ai/mastra/commit/eeae63e7fbe8e1f237adc69bca6e2ac13c5ca907), [`3dc97ea`](https://github.com/mastra-ai/mastra/commit/3dc97ea415fad353b48a13095fad1835933cc12a), [`94e7ae9`](https://github.com/mastra-ai/mastra/commit/94e7ae970b37c888cd1244ef013292639a2fe6d1), [`e6a2860`](https://github.com/mastra-ai/mastra/commit/e6a2860649cc51f87d32d78b766ae2126446ba07), [`7010c5d`](https://github.com/mastra-ai/mastra/commit/7010c5d15728bf9c5dfe4fb6b1bf80ce23bf143a), [`bab06b1`](https://github.com/mastra-ai/mastra/commit/bab06b18923873a584bdfc71a6b4ec7fb4727fb7), [`3d01cd3`](https://github.com/mastra-ai/mastra/commit/3d01cd387321b6f9c5cac31d487c84bf51b19c78), [`7bf3086`](https://github.com/mastra-ai/mastra/commit/7bf308663f0115ca74ad20554ade740f06640859), [`4c186a0`](https://github.com/mastra-ai/mastra/commit/4c186a017275f45e6ed4c09de0f89550e2d09e8c), [`b0fa077`](https://github.com/mastra-ai/mastra/commit/b0fa077bcbc9b08551846fe372a0d3d15b71ed72), [`0282e16`](https://github.com/mastra-ai/mastra/commit/0282e16115538c8e9b248b90f0748eb01cb5dc98), [`a8dd139`](https://github.com/mastra-ai/mastra/commit/a8dd1391a9fe9a6632c25809ef236980afa9a020), [`6a667b4`](https://github.com/mastra-ai/mastra/commit/6a667b4b7cd6a93fe41fcdd357b08c5a8c09b9ab), [`9be8878`](https://github.com/mastra-ai/mastra/commit/9be8878dcf0388e84fc4873e0eec27bd49b881a4), [`e5786be`](https://github.com/mastra-ai/mastra/commit/e5786be02bb903073082bd9d6da880ebaacc343f), [`2440e09`](https://github.com/mastra-ai/mastra/commit/2440e096ea6c2def1ccc1eb2d0f3f5b88c4af940), [`2093fbd`](https://github.com/mastra-ai/mastra/commit/2093fbd53bb744bae19ec89f6d73db9a66fbe8a7), [`a59049b`](https://github.com/mastra-ai/mastra/commit/a59049b1652a13efff66ac826326b5ed9a550342), [`7bd85ea`](https://github.com/mastra-ai/mastra/commit/7bd85ea7588b71c25ce9f4019c88f8539be5dcbc), [`83fa004`](https://github.com/mastra-ai/mastra/commit/83fa0044bfda8b703a83883dbd8bef204844d13f), [`a463cdf`](https://github.com/mastra-ai/mastra/commit/a463cdf1c95c3059e70f0bff27959e8558bb899d), [`e7a5da4`](https://github.com/mastra-ai/mastra/commit/e7a5da4ef8e4dd452d2f232961b4e682a85ffe43), [`7b4393d`](https://github.com/mastra-ai/mastra/commit/7b4393d557411fdcf07b0e30e5acaf7cc85154ae), [`0ea6b80`](https://github.com/mastra-ai/mastra/commit/0ea6b8001408ce02b56e8be0536b0fd8cbaf8ad2)]:
100
+ - @mastra/core@1.58.0
101
+
3
102
  ## 1.16.0-alpha.2
4
103
 
5
104
  ### Minor Changes
package/dist/client/configuration.d.ts CHANGED
@@ -5,6 +5,11 @@ import type { Tool } from '@mastra/core/tools';
5
5
  import type { ElicitRequest, ElicitResult, ProgressNotification, Prompt, Resource, ResourceTemplateType } from '@modelcontextprotocol/client';
6
6
  import type { MastraMCPServerDefinition, MCPServerAuthState } from './client.js';
7
7
  import type { SerializableMCPToolCatalog, SerializableMCPToolDefinition } from './types.js';
8
+ /** Options for aggregate discovery across configured MCP servers. */
9
+ export interface MCPDiscoveryOptions {
10
+ /** Maximum time to wait for each server's discovery operation, in milliseconds. */
11
+ perServerTimeoutMs?: number;
12
+ }
8
13
  /**
9
14
  * Configuration options for creating an MCPClient instance.
10
15
  */
@@ -719,9 +724,10 @@ export declare class MCPClient extends MastraBase {
719
724
  * }
720
725
  * ```
721
726
  */
722
- listToolsWithErrors(): Promise<{
727
+ listToolsWithErrors(options?: MCPDiscoveryOptions): Promise<{
723
728
  tools: Record<string, Tool<any, any, any, any>>;
724
729
  errors: Record<string, string>;
730
+ durations?: Record<string, number>;
725
731
  }>;
726
732
  /**
727
733
  * Returns toolsets organized by server name for dynamic tool injection.
@@ -764,9 +770,10 @@ export declare class MCPClient extends MastraBase {
764
770
  * }
765
771
  * ```
766
772
  */
767
- listToolsetsWithErrors(): Promise<{
773
+ listToolsetsWithErrors(options?: MCPDiscoveryOptions): Promise<{
768
774
  toolsets: Record<string, Record<string, Tool<any, any, any, any>>>;
769
775
  errors: Record<string, string>;
776
+ durations?: Record<string, number>;
770
777
  }>;
771
778
  /**
772
779
  * Discovers every configured server's tools as plain, serializable definitions.
@@ -798,9 +805,10 @@ export declare class MCPClient extends MastraBase {
798
805
  * Useful when caching a catalog, since it lets you avoid persisting a partial manifest that
799
806
  * silently omits a server which happened to be down at discovery time.
800
807
  */
801
- listToolDefinitionsWithErrors(): Promise<{
808
+ listToolDefinitionsWithErrors(options?: MCPDiscoveryOptions): Promise<{
802
809
  definitions: SerializableMCPToolCatalog;
803
810
  errors: Record<string, string>;
811
+ durations?: Record<string, number>;
804
812
  }>;
805
813
  /**
806
814
  * Rebuilds an executable Mastra tool from a cached {@link SerializableMCPToolDefinition}.
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":"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"}
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.16.0-alpha.2"
6
+ version: "1.17.0-alpha.0"
7
7
  ---
8
8
 
9
9
  ## When to use
@@ -16,13 +16,14 @@ Read the individual reference documents for detailed explanations and code examp
16
16
 
17
17
  ### Docs
18
18
 
19
- - [Connections overview](references/docs-connections-overview.md) - Connect Mastra to remote agents, coding agents, provider software development kit runtimes, and external tools and resources.
20
- - [MCP overview](references/docs-mcp-overview.md) - Connect Mastra agents to external MCP servers, expose Mastra tools through MCPServer, and build interactive MCP Apps for Studio.
19
+ - [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
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
25
  - [Reference: Tool configuration](references/reference-editor-tools.md) - Reference for Editor tool sources, providers, descriptions, conditions, MCP clients, and resolution order.
26
+ - [MCP](references/reference-migrations-upgrade-to-v1-mcp.md) - Learn how to migrate MCP-related changes when upgrading to v1.
26
27
  - [Reference: MCPClient](references/reference-tools-mcp-client.md) - API Reference for MCPClient - A class for managing multiple Model Context Protocol servers and their tools.
27
28
  - [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.
28
29
 
package/dist/docs/assets/SOURCE_MAP.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.16.0-alpha.2",
2
+ "version": "1.17.0-alpha.0",
3
3
  "package": "@mastra/mcp",
4
4
  "exports": {},
5
5
  "modules": {}
package/dist/docs/references/docs-connections-overview.md CHANGED
@@ -1,6 +1,6 @@
1
1
  > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
2
 
3
- # Connections overview
3
+ # Connections
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
 
package/dist/docs/references/docs-mcp-overview.md CHANGED
@@ -1,6 +1,6 @@
1
1
  > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
2
 
3
- # MCP overview
3
+ # MCP
4
4
 
5
5
  Mastra supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open standard for connecting AI agents to external tools and resources.
6
6
 
@@ -202,6 +202,48 @@ export const mastra = new Mastra({
202
202
 
203
203
  Visit the [`MCPServer` reference](https://mastra.ai/reference/tools/mcp-server) for prompts, resources, transports, and other server options.
204
204
 
205
+ ### Publish a stdio server package
206
+
207
+ Package a server that uses the standard input/output (stdio) transport when you want clients to run it locally through a command such as `npx`. Create a separate executable entry point that starts the server:
208
+
209
+ ```typescript
210
+ #!/usr/bin/env node
211
+ import { mcpServer } from './server'
212
+
213
+ mcpServer.startStdio().catch(error => {
214
+ console.error('Failed to start MCP server:', error)
215
+ process.exit(1)
216
+ })
217
+ ```
218
+
219
+ Build the entry point as an executable Node.js file, then point the package's `bin` field to that output. Include the built file in the published package and keep the shebang as its first line:
220
+
221
+ ```json
222
+ {
223
+ "bin": {
224
+ "my-mcp-server": "dist/stdio.js"
225
+ },
226
+ "files": ["dist"]
227
+ }
228
+ ```
229
+
230
+ After publishing the package, configure clients to run it by package name:
231
+
232
+ ```typescript
233
+ import { MCPClient } from '@mastra/mcp'
234
+
235
+ const mcpClient = new MCPClient({
236
+ servers: {
237
+ myServer: {
238
+ command: 'npx',
239
+ args: ['-y', '@your-org/my-mcp-server@1.0.0'],
240
+ },
241
+ },
242
+ })
243
+ ```
244
+
245
+ Visit the [npm package publishing documentation](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages) for package naming, authentication, and publication commands.
246
+
205
247
  ## Build MCP Apps
206
248
 
207
249
  The [MCP Apps extension](https://github.com/modelcontextprotocol/ext-apps) lets MCP tools serve interactive HTML interfaces through `ui://` resources. Mastra Studio renders these apps in sandboxed iframes on tool pages and in agent chat.
@@ -210,7 +252,7 @@ Use an MCP App when a tool result benefits from interaction, such as a form, cal
210
252
 
211
253
  ### Define an app resource
212
254
 
213
- Return a short `content` summary for the model and place UI data in `structuredContent`. Link the tool to its app by setting `_meta.ui.resourceUri` to the same `ui://` URI used in `appResources`:
255
+ Return a short `content` summary for the model and place UI data in `structuredContent`. Link the tool to its app by setting `mcp._meta.ui.resourceUri` to the same `ui://` URI used in `appResources`:
214
256
 
215
257
  ```typescript
216
258
  import { MCPServer } from '@mastra/mcp'
@@ -224,16 +266,15 @@ export const calculatorTool = createTool({
224
266
  num1: z.number(),
225
267
  num2: z.number(),
226
268
  }),
269
+ mcp: {
270
+ _meta: { ui: { resourceUri: 'ui://calculator/main' } },
271
+ },
227
272
  execute: async ({ num1, num2 }) => ({
228
273
  content: [{ type: 'text', text: 'The result is displayed in the calculator app.' }],
229
274
  structuredContent: { result: num1 + num2 },
230
275
  }),
231
276
  })
232
277
 
233
- calculatorTool._meta = {
234
- ui: { resourceUri: 'ui://calculator/main' },
235
- }
236
-
237
278
  export const calculatorMcpServer = new MCPServer({
238
279
  id: 'calculator-app-server',
239
280
  name: 'Calculator App Server',
package/dist/docs/references/docs-server-auth-fga.md CHANGED
@@ -300,4 +300,4 @@ The actor signal is trusted input, so construct it server-side:
300
300
 
301
301
  - [`IFGAProvider` reference](https://mastra.ai/reference/auth/fga)
302
302
  - [Authentication overview](https://mastra.ai/docs/server/auth)
303
- - [WorkOS authentication](https://mastra.ai/docs/server/auth/workos)
303
+ - [WorkOS authentication](https://mastra.ai/integrations/auth/workos)
package/dist/docs/references/reference-editor-tools.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  # Tool configuration
4
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.
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
7
  See [Editor tools](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.
8
8
 
package/dist/docs/references/reference-migrations-upgrade-to-v1-mcp.md ADDED
@@ -0,0 +1,99 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # MCP
4
+
5
+ MCP (Model Context Protocol) tool execution context has been reorganized, and deprecated client classes have been removed.
6
+
7
+ ## Changed
8
+
9
+ ### `getMCPServers` to `listMCPServers`
10
+
11
+ The `mastra.getMCPServers()` method has been renamed to `mastra.listMCPServers()`. This change aligns with the naming convention used across the API where plural getter methods use the `list` prefix.
12
+
13
+ To migrate, replace all calls to `mastra.getMCPServers()` with `mastra.listMCPServers()`.
14
+
15
+ ```diff
16
+ - const servers = await mastra.getMCPServers();
17
+ + const servers = await mastra.listMCPServers();
18
+ ```
19
+
20
+ > **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
21
+ >
22
+ > ```bash
23
+ > npx @mastra/codemod@latest v1/mastra-plural-apis .
24
+ > ```
25
+
26
+ ### `getTools` to `listTools`
27
+
28
+ The `mcp.getTools()` method has been renamed to `mcp.listTools()`. This change aligns with the naming convention used across the API where plural getter methods use the `list` prefix.
29
+
30
+ To migrate, replace all calls to `mcp.getTools()` with `mcp.listTools()`.
31
+
32
+ ```diff
33
+ - const tools = await mcp.getTools();
34
+ + const tools = await mcp.listTools();
35
+ ```
36
+
37
+ > **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
38
+ >
39
+ > ```bash
40
+ > npx @mastra/codemod@latest v1/mcp-get-tools .
41
+ > ```
42
+
43
+ ### `getToolsets` to `listToolsets`
44
+
45
+ The `mcp.getToolsets()` method has been renamed to `mcp.listToolsets()`. This change aligns with the naming convention used across the API where plural getter methods use the `list` prefix.
46
+
47
+ To migrate, replace all calls to `mcp.getToolsets()` with `mcp.listToolsets()`.
48
+
49
+ ```diff
50
+ - const toolsets = await mcp.getToolsets();
51
+ + const toolsets = await mcp.listToolsets();
52
+ ```
53
+
54
+ > **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
55
+ >
56
+ > ```bash
57
+ > npx @mastra/codemod@latest v1/mcp-get-toolsets .
58
+ > ```
59
+
60
+ ### MCP tool context properties organization
61
+
62
+ Context properties in MCP tools are now organized under the `context.mcp` namespace. The namespace organizes MCP-specific functionality under a clear API surface.
63
+
64
+ To migrate, access MCP-specific properties like `elicitation` and `extra` through `context.mcp` instead of directly from the context parameter.
65
+
66
+ ```diff
67
+ createTool({
68
+ id: 'account-balance',
69
+ - execute: async ({ context, elicitation, extra }) => {
70
+ - await checkAuth(extra.authInfo);
71
+ - const result = await elicitation.sendRequest({
72
+ - message: `Is it ok to fetch account ${context.accountId}?`,
73
+ - });
74
+ - },
75
+ + execute: async (inputData, context) => {
76
+ + await checkAuth(context?.mcp?.extra.authInfo);
77
+ + const result = await context?.mcp?.elicitation.sendRequest({
78
+ + message: `Is it ok to fetch account ${inputData.accountId}?`,
79
+ + });
80
+ + },
81
+ });
82
+ ```
83
+
84
+ ## Removed
85
+
86
+ ### Deprecated MCP client classes
87
+
88
+ The `MastraMCPClient` and related deprecated APIs have been removed from `@mastra/mcp`. This change consolidates on the new MCP client API.
89
+
90
+ To migrate, use the new `MCPClient` class instead of deprecated classes.
91
+
92
+ ```diff
93
+ - import { MastraMCPClient, MCPConfiguration } from '@mastra/mcp/client';
94
+ + import { MCPClient } from '@mastra/mcp/client';
95
+
96
+ - const client = new MastraMCPClient({ ... });
97
+ - const config = new MCPConfiguration({ ... });
98
+ + const client = new MCPClient({ ... });
99
+ ```
package/dist/docs/references/reference-tools-mcp-client.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  # MCPClient
4
4
 
5
- The `MCPClient` class provides a way to manage multiple MCP server connections and their tools in a Mastra application. It handles connection lifecycle, tool namespacing, and provides access to tools across all configured servers.
5
+ The `MCPClient` class provides a way to manage multiple MCP server connections and their tools in a Mastra application. It handles connection lifecycle and tool namespacing while providing access to tools across all configured servers.
6
6
 
7
7
  ## Constructor
8
8
 
@@ -223,17 +223,23 @@ Retrieves all tools from all configured servers, with tool names namespaced by t
223
223
  new Agent({ id: 'agent', tools: await mcp.listTools() })
224
224
  ```
225
225
 
226
- ### `listToolsWithErrors()`
226
+ ### `listToolsWithErrors(options?)`
227
227
 
228
228
  Retrieves all tools from all configured servers, with tool names namespaced by their server name. Also returns per-server errors for servers that failed to connect or list tools.
229
229
 
230
+ Set `perServerTimeoutMs` to limit how long discovery waits for each server. Servers that finish within the limit remain in `tools`. Timed-out servers appear in `errors`, and `durations` reports each server's discovery time in milliseconds.
231
+
230
232
  ```typescript
231
- const { tools, errors } = await mcp.listToolsWithErrors()
233
+ const { tools, errors, durations } = await mcp.listToolsWithErrors({
234
+ perServerTimeoutMs: 3_000,
235
+ })
232
236
 
233
237
  new Agent({ id: 'agent', tools })
234
- console.log(errors)
238
+ console.log(errors, durations)
235
239
  ```
236
240
 
241
+ When called without options, the method returns only `tools` and `errors`.
242
+
237
243
  ### `listToolsets()`
238
244
 
239
245
  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.
@@ -244,11 +250,26 @@ const res = await agent.stream(prompt, {
244
250
  })
245
251
  ```
246
252
 
253
+ ### `listToolsetsWithErrors(options?)`
254
+
255
+ Returns toolsets grouped by server name, along with per-server discovery errors. Set `perServerTimeoutMs` to limit each server independently and include per-server `durations` in milliseconds.
256
+
257
+ ```typescript
258
+ const { toolsets, errors, durations } = await mcp.listToolsetsWithErrors({
259
+ perServerTimeoutMs: 3_000,
260
+ })
261
+
262
+ const res = await agent.stream(prompt, { toolsets })
263
+ console.log(errors, durations)
264
+ ```
265
+
266
+ When called without options, the method returns only `toolsets` and `errors`.
267
+
247
268
  ### `listToolDefinitions()`
248
269
 
249
270
  Returns every server's tools as plain, serializable definitions, grouped by server name and keyed by the server's own tool name (without the `serverName_toolName` namespacing that `listTools()` applies).
250
271
 
251
- Unlike `listTools()`, the result contains no functions or references to a live client, so it can be passed through `JSON.stringify` and cached in Redis, a database, or a build artifact. Each definition holds the data from the MCP `tools/list` response (name, description, input schema, output schema, annotations, and `_meta`), plus the server name, version, and instructions captured at discovery time.
272
+ Unlike `listTools()`, the result contains no functions or references to a live client, so it can be passed through `JSON.stringify` and cached in Redis or a database, as well as a build artifact. Each definition holds the data from the MCP `tools/list` response (name, description, input schema, output schema, annotations, and `_meta`), plus the server name, version, and instructions captured at discovery time.
252
273
 
253
274
  ```typescript
254
275
  const definitions = await mcp.listToolDefinitions()
@@ -256,18 +277,26 @@ const definitions = await mcp.listToolDefinitions()
256
277
  await cache.set('mcp-tools', JSON.stringify(definitions))
257
278
  ```
258
279
 
259
- ### `listToolDefinitionsWithErrors()`
280
+ ### `listToolDefinitionsWithErrors(options?)`
260
281
 
261
282
  Like `listToolDefinitions()`, but also returns per-server errors for servers that failed to connect. Use this when caching a catalog, so you don't persist a partial manifest that omits a server that was down at discovery time.
262
283
 
284
+ Set `perServerTimeoutMs` to limit each server independently. When options are provided, `durations` reports each server's discovery time in milliseconds.
285
+
263
286
  ```typescript
264
- const { definitions, errors } = await mcp.listToolDefinitionsWithErrors()
287
+ const { definitions, errors, durations } = await mcp.listToolDefinitionsWithErrors({
288
+ perServerTimeoutMs: 3_000,
289
+ })
265
290
 
266
291
  if (Object.keys(errors).length === 0) {
267
292
  await cache.set('mcp-tools', JSON.stringify(definitions))
268
293
  }
294
+
295
+ console.log(durations)
269
296
  ```
270
297
 
298
+ When called without options, the method returns only `definitions` and `errors`.
299
+
271
300
  ### `toolFromDefinition()`
272
301
 
273
302
  Rebuilds a single executable tool from a cached definition. No connection is opened here. The client connects lazily, the first time the tool is executed.
@@ -991,7 +1020,7 @@ try {
991
1020
 
992
1021
  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.
993
1022
 
994
- 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:
1023
+ Hosts that drive the flow themselves can capture the authorization code with the exported `createOAuthCallbackServer` helper, which binds a one-shot loopback server and validates the OAuth `state` parameter before resolving 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:
995
1024
 
996
1025
  ```typescript
997
1026
  import { createOAuthCallbackServer, getCallbackUrlCandidates } from '@mastra/mcp'
package/dist/docs/references/reference-tools-mcp-server.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  # MCPServer
4
4
 
5
- The `MCPServer` class provides the functionality to expose your existing Mastra tools and Agents as a Model Context Protocol (MCP) server. This allows any MCP client (like Cursor, Windsurf, or Claude Desktop) to connect to these capabilities and make them available to an agent.
5
+ The `MCPServer` class provides the functionality to expose your existing Mastra tools and Agents as a Model Context Protocol (MCP) server. Any MCP client, such as Cursor, Windsurf, or Claude Desktop, can connect to these capabilities and make them available to an agent.
6
6
 
7
7
  Note that if you only need to use your tools or agents directly within your Mastra application, you don't necessarily need to create an MCP server. This API is specifically for exposing your Mastra tools and agents to _external_ MCP clients.
8
8
 
@@ -95,7 +95,7 @@ The constructor accepts an `MCPServerConfig` object with the following propertie
95
95
 
96
96
  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:
97
97
 
98
- - **Tool Naming**: Each agent is converted into a tool named `ask_<agentKey>`, where `<agentKey>` is the key you used for that agent in the `agents` object. For instance, if you configure `agents: { myAgentKey: myAgentInstance }`, a tool named `ask_myAgentKey` will be created.
98
+ - **Tool Naming**: Each agent is converted into a tool with the name `ask_<agentKey>`, where `<agentKey>` is the key you used for that agent in the `agents` object. For instance, if you configure `agents: { myAgentKey: myAgentInstance }`, a tool with the name `ask_myAgentKey` will be created.
99
99
 
100
100
  - **Tool Functionality**:
101
101
 
@@ -104,7 +104,7 @@ A powerful feature of `MCPServer` is its ability to automatically expose your Ma
104
104
  - **Execution**: When this tool is called, it invokes the corresponding agent's `generate()` method with the provided `query`.
105
105
  - **Output**: The direct result from the agent's `generate()` method is returned as the output of the tool.
106
106
 
107
- - **Name collisions.** If an explicit tool defined in the `tools` configuration has the same name as an agent-derived tool (e.g., a tool named `ask_myAgentKey` alongside an agent keyed as `myAgentKey`), the _explicitly defined tool will take precedence_. The agent won't be converted into a tool in this conflicting case, and a warning will be logged.
107
+ - **Name collisions.** If an explicit tool defined in the `tools` configuration has the same name as an agent-derived tool (e.g., a tool with the name `ask_myAgentKey` alongside an agent keyed as `myAgentKey`), the _explicitly defined tool will take precedence_. The agent won't be converted into a tool in this conflicting case, and a warning will be logged.
108
108
 
109
109
  This makes it straightforward to allow MCP clients to interact with your agents using natural language queries, like any other tool.
110
110
 
@@ -116,7 +116,7 @@ The description for this generated tool will be: "Ask agent `<agent.name>` a que
116
116
 
117
117
  For an agent to be converted into a tool, it **must** have a non-empty `description` string property set in its configuration when it was instantiated (e.g., `new Agent({ id: 'my-agent', name: 'myAgent', description: 'This agent does X.', ... })`). If an agent is passed to `MCPServer` with a missing or empty `description`, an error will be thrown when the `MCPServer` is instantiated, and server setup will fail.
118
118
 
119
- This allows you to quickly expose the generative capabilities of your agents through the MCP, enabling clients to "ask" your agents questions directly.
119
+ Clients can use MCP to access your agents' generative capabilities and ask them questions directly.
120
120
 
121
121
  ### Accessing MCP Context in Tools
122
122
 
@@ -929,7 +929,7 @@ Notification methods (`resources.notifyListChanged()`, `prompts.notifyListChange
929
929
 
930
930
  ## Examples
931
931
 
932
- For practical examples of setting up and deploying an MCPServer, see the [Publishing an MCP Server guide](https://mastra.ai/guides/guide/publishing-mcp-server).
932
+ For a practical example of packaging a stdio server, see [Publish a stdio server package](https://mastra.ai/docs/mcp/overview).
933
933
 
934
934
  The example at the beginning of this page also demonstrates how to instantiate `MCPServer` with both tools and agents.
935
935
 
@@ -1240,7 +1240,7 @@ const customMiddleware = createOAuthMiddleware({
1240
1240
 
1241
1241
  ## Authentication context
1242
1242
 
1243
- Tools can access request metadata via `context.mcp.extra` when using HTTP-based transports. This allows you to pass authentication info, user context, or any custom data from your HTTP middleware to your MCP tools.
1243
+ Tools can access request metadata via `context.mcp.extra` when using HTTP-based transports. You can pass authentication info and user context, as well as custom data from your HTTP middleware to your MCP tools.
1244
1244
 
1245
1245
  ### How it works
1246
1246
 
@@ -1637,6 +1637,9 @@ const calculatorTool = createTool({
1637
1637
  num2: z.number(),
1638
1638
  operation: z.enum(['add', 'subtract']),
1639
1639
  }),
1640
+ mcp: {
1641
+ _meta: { ui: { resourceUri: 'ui://calculator/main' } },
1642
+ },
1640
1643
  execute: async ({ num1, num2, operation }) => {
1641
1644
  const result = operation === 'add' ? num1 + num2 : num1 - num2
1642
1645
  return {
@@ -1660,7 +1663,7 @@ const server = new MCPServer({
1660
1663
  })
1661
1664
  ```
1662
1665
 
1663
- Link a tool to its app resource by setting `_meta.ui.resourceUri` on the tool to the matching `ui://` URI. The server auto-normalizes this metadata when registering tools. Visit [MCP Apps](https://mastra.ai/docs/mcp/overview) for the full app bridge API and usage patterns.
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/overview) for the full app bridge API and usage patterns.
1664
1667
 
1665
1668
  ## Related information
1666
1669