@mastra/mcp 1.16.0-alpha.2 → 1.16.0

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # @mastra/mcp
 
+## 1.16.0
+
+### Minor Changes
+
+- 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))
+
+  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.
+
+  **If you pass a custom schema validator**
+
+  The optional `jsonSchemaValidator` option now takes its validator from the MCP packages. Update the import path:
+
+  ```ts
+  // Before
+  import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/cfworker';
+
+  // After
+  import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/client/validators/cf-worker';
+
+  const mcp = new MCPClient({
+    servers: {
+      weather: { url: new URL('https://example.com/mcp'), jsonSchemaValidator: new CfWorkerJsonSchemaValidator() },
+    },
+  });
+  ```
+
+  **If you import MCP protocol types directly**
+
+  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`.
+
+- 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))
+
+  - `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.
+  - `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.
+
+  ```typescript
+  const mcp = new MCPClient({
+    servers: {
+      weather: {
+        url: new URL('https://weather.example/mcp'),
+        allowedHosts: ['weather.example'],
+      },
+      local: {
+        command: 'npx',
+        args: ['tsx', 'stdio-server.ts'],
+        inheritDefaultEnv: false,
+        env: { WEATHER_API_KEY: process.env.WEATHER_API_KEY! },
+      },
+    },
+  });
+  ```
+
+- Add serializable MCP tool definitions and lazy hydration. ([#21119](https://github.com/mastra-ai/mastra/pull/21119))
+
+  `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.
+
+  - `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.
+  - `listToolDefinitionsWithErrors()` also reports per-server failures, so a partial catalog isn't cached silently.
+  - `toolFromDefinition({ serverName, definition })` rebuilds a single tool from a cached definition.
+  - `toolsFromDefinitions({ definitions })` rebuilds a whole namespaced tool map, matching the `serverName_toolName` keys from `listTools()`.
+
+  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.
+
+  Existing `listTools()` and `listToolsets()` behavior is unchanged.
+
+### Patch Changes
+
+- 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))
+
+- **Fixed spurious MCP reconnects when tool-execution errors contain transport-like substrings.** ([#20793](https://github.com/mastra-ai/mastra/pull/20793))
+
+  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).
+
+  **Surface the real failure after a failed reconnect.**
+
+  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.
+
+- 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))
+
+- 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)]:
+  - @mastra/core@1.58.0
+
 ## 1.16.0-alpha.2
 
 ### Minor Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-mcp
 description: Documentation for @mastra/mcp. Use when working with @mastra/mcp APIs, configuration, or implementation.
 metadata:
   package: "@mastra/mcp"
-  version: "1.16.0-alpha.2"
+  version: "1.16.0"
 ---
 
 ## When to use
@@ -23,6 +23,7 @@ Read the individual reference documents for detailed explanations and code examp
 ### Reference
 
 - [Reference: Tool configuration](references/reference-editor-tools.md) - Reference for Editor tool sources, providers, descriptions, conditions, MCP clients, and resolution order.
+- [MCP](references/reference-migrations-upgrade-to-v1-mcp.md) - Learn how to migrate MCP-related changes when upgrading to v1.
 - [Reference: MCPClient](references/reference-tools-mcp-client.md) - API Reference for MCPClient - A class for managing multiple Model Context Protocol servers and their tools.
 - [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.
 

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.16.0-alpha.2",
+  "version": "1.16.0",
   "package": "@mastra/mcp",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-mcp-overview.md

@@ -202,6 +202,48 @@ export const mastra = new Mastra({
 
 Visit the [`MCPServer` reference](https://mastra.ai/reference/tools/mcp-server) for prompts, resources, transports, and other server options.
 
+### Publish a stdio server package
+
+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:
+
+```typescript
+#!/usr/bin/env node
+import { mcpServer } from './server'
+
+mcpServer.startStdio().catch(error => {
+  console.error('Failed to start MCP server:', error)
+  process.exit(1)
+})
+```
+
+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:
+
+```json
+{
+  "bin": {
+    "my-mcp-server": "dist/stdio.js"
+  },
+  "files": ["dist"]
+}
+```
+
+After publishing the package, configure clients to run it by package name:
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+
+const mcpClient = new MCPClient({
+  servers: {
+    myServer: {
+      command: 'npx',
+      args: ['-y', '@your-org/my-mcp-server@1.0.0'],
+    },
+  },
+})
+```
+
+Visit the [npm package publishing documentation](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages) for package naming, authentication, and publication commands.
+
 ## Build MCP Apps
 
 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.

package/dist/docs/references/docs-server-auth-fga.md

@@ -300,4 +300,4 @@ The actor signal is trusted input, so construct it server-side:
 
 - [`IFGAProvider` reference](https://mastra.ai/reference/auth/fga)
 - [Authentication overview](https://mastra.ai/docs/server/auth)
-- [WorkOS authentication](https://mastra.ai/docs/server/auth/workos)
+- [WorkOS authentication](https://mastra.ai/integrations/auth/workos)

package/dist/docs/references/reference-migrations-upgrade-to-v1-mcp.md

@@ -0,0 +1,99 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# MCP
+
+MCP (Model Context Protocol) tool execution context has been reorganized, and deprecated client classes have been removed.
+
+## Changed
+
+### `getMCPServers` to `listMCPServers`
+
+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.
+
+To migrate, replace all calls to `mastra.getMCPServers()` with `mastra.listMCPServers()`.
+
+```diff
+- const servers = await mastra.getMCPServers();
++ const servers = await mastra.listMCPServers();
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/mastra-plural-apis .
+> ```
+
+### `getTools` to `listTools`
+
+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.
+
+To migrate, replace all calls to `mcp.getTools()` with `mcp.listTools()`.
+
+```diff
+- const tools = await mcp.getTools();
++ const tools = await mcp.listTools();
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/mcp-get-tools .
+> ```
+
+### `getToolsets` to `listToolsets`
+
+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.
+
+To migrate, replace all calls to `mcp.getToolsets()` with `mcp.listToolsets()`.
+
+```diff
+- const toolsets = await mcp.getToolsets();
++ const toolsets = await mcp.listToolsets();
+```
+
+> **Codemod:** You can use Mastra's codemod CLI to update your code automatically:
+>
+> ```bash
+> npx @mastra/codemod@latest v1/mcp-get-toolsets .
+> ```
+
+### MCP tool context properties organization
+
+Context properties in MCP tools are now organized under the `context.mcp` namespace. This change provides better organization and clearer API surface for MCP-specific functionality.
+
+To migrate, access MCP-specific properties like `elicitation` and `extra` through `context.mcp` instead of directly from the context parameter.
+
+```diff
+createTool({
+    id: 'account-balance',
+-   execute: async ({ context, elicitation, extra }) => {
+-     await checkAuth(extra.authInfo);
+-     const result = await elicitation.sendRequest({
+-       message: `Is it ok to fetch account ${context.accountId}?`,
+-     });
+-   },
++   execute: async (inputData, context) => {
++     await checkAuth(context?.mcp?.extra.authInfo);
++     const result = await context?.mcp?.elicitation.sendRequest({
++       message: `Is it ok to fetch account ${inputData.accountId}?`,
++     });
++   },
+  });
+```
+
+## Removed
+
+### Deprecated MCP client classes
+
+The `MastraMCPClient` and related deprecated APIs have been removed from `@mastra/mcp`. This change consolidates on the new MCP client API.
+
+To migrate, use the new `MCPClient` class instead of deprecated classes.
+
+```diff
+- import { MastraMCPClient, MCPConfiguration } from '@mastra/mcp/client';
++ import { MCPClient } from '@mastra/mcp/client';
+
+- const client = new MastraMCPClient({ ... });
+- const config = new MCPConfiguration({ ... });
++ const client = new MCPClient({ ... });
+```

package/dist/docs/references/reference-tools-mcp-server.md

@@ -929,7 +929,7 @@ Notification methods (`resources.notifyListChanged()`, `prompts.notifyListChange
 
 ## Examples
 
-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).
+For a practical example of packaging a stdio server, see [Publish a stdio server package](https://mastra.ai/docs/mcp/overview).
 
 The example at the beginning of this page also demonstrates how to instantiate `MCPServer` with both tools and agents.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp",
-  "version": "1.16.0-alpha.2",
+  "version": "1.16.0",
   "description": "",
   "type": "module",
   "main": "dist/index.js",
@@ -55,14 +55,14 @@
     "vitest": "4.1.10",
     "zod": "^4.4.3",
     "zod-to-json-schema": "^3.25.1",
-    "@internal/lint": "0.0.121",
-    "@internal/llm-recorder": "0.0.57",
-    "@internal/ai-sdk-v5": "0.0.68",
-    "@internal/types-builder": "0.0.96",
-    "@internal/test-utils": "0.0.57",
-    "@mastra/core": "1.58.0-alpha.12",
-    "@mastra/observability": "1.16.6-alpha.3",
-    "@mastra/schema-compat": "1.3.6-alpha.3"
+    "@internal/ai-sdk-v5": "0.0.69",
+    "@internal/lint": "0.0.122",
+    "@internal/llm-recorder": "0.0.58",
+    "@internal/test-utils": "0.0.58",
+    "@mastra/core": "1.58.0",
+    "@mastra/observability": "1.16.6",
+    "@internal/types-builder": "0.0.97",
+    "@mastra/schema-compat": "1.3.6"
   },
   "homepage": "https://mastra.ai",
   "repository": {