@mastra/mcp 1.16.0 → 1.17.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @mastra/mcp
 
+## 1.17.0-alpha.0
+
+### Minor Changes
+
+- Added per-server time budgets and duration metrics to MCP discovery methods. ([#21560](https://github.com/mastra-ai/mastra/pull/21560))
+
+  ```typescript
+  const { tools, errors, durations } = await mcp.listToolsWithErrors({
+    perServerTimeoutMs: 3_000,
+  });
+  ```
+
+### Patch Changes
+
+- 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)]:
+  - @mastra/core@1.60.0-alpha.4
+
 ## 1.16.0
 
 ### Minor Changes

package/dist/client/configuration.d.ts

@@ -5,6 +5,11 @@ import type { Tool } from '@mastra/core/tools';
 import type { ElicitRequest, ElicitResult, ProgressNotification, Prompt, Resource, ResourceTemplateType } from '@modelcontextprotocol/client';
 import type { MastraMCPServerDefinition, MCPServerAuthState } from './client.js';
 import type { SerializableMCPToolCatalog, SerializableMCPToolDefinition } from './types.js';
+/** Options for aggregate discovery across configured MCP servers. */
+export interface MCPDiscoveryOptions {
+    /** Maximum time to wait for each server's discovery operation, in milliseconds. */
+    perServerTimeoutMs?: number;
+}
 /**
  * Configuration options for creating an MCPClient instance.
  */
@@ -719,9 +724,10 @@ export declare class MCPClient extends MastraBase {
      * }
      * ```
      */
-    listToolsWithErrors(): Promise<{
+    listToolsWithErrors(options?: MCPDiscoveryOptions): Promise<{
         tools: Record<string, Tool<any, any, any, any>>;
         errors: Record<string, string>;
+        durations?: Record<string, number>;
     }>;
     /**
      * Returns toolsets organized by server name for dynamic tool injection.
@@ -764,9 +770,10 @@ export declare class MCPClient extends MastraBase {
      * }
      * ```
      */
-    listToolsetsWithErrors(): Promise<{
+    listToolsetsWithErrors(options?: MCPDiscoveryOptions): Promise<{
         toolsets: Record<string, Record<string, Tool<any, any, any, any>>>;
         errors: Record<string, string>;
+        durations?: Record<string, number>;
     }>;
     /**
      * Discovers every configured server's tools as plain, serializable definitions.
@@ -798,9 +805,10 @@ export declare class MCPClient extends MastraBase {
      * Useful when caching a catalog, since it lets you avoid persisting a partial manifest that
      * silently omits a server which happened to be down at discovery time.
      */
-    listToolDefinitionsWithErrors(): Promise<{
+    listToolDefinitionsWithErrors(options?: MCPDiscoveryOptions): Promise<{
         definitions: SerializableMCPToolCatalog;
         errors: Record<string, string>;
+        durations?: Record<string, number>;
     }>;
     /**
      * Rebuilds an executable Mastra tool from a cached {@link SerializableMCPToolDefinition}.

package/dist/client/configuration.d.ts.map

@@ -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,oBAAoB,EACrB,MAAM,8BAA8B,CAAC;AAKtC,OAAO,KAAK,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAM9E,OAAO,KAAK,EAAE,0BAA0B,EAAE,6BAA6B,EAAE,MAAM,SAAS,CAAC;AA2BzF;;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;IACvD,OAAO,CAAC,iBAAiB,CAAoC;IAC7D,OAAO,CAAC,2BAA2B,CAA0C;IAC7E;;;;;OAKG;IACH,OAAO,CAAC,4BAA4B,CAAsC;IAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;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;QAanD;;;;;;;;;;;;;WAaG;yBACkB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,EAAE,CAAC,CAAC;QAgBpE;;;;;;;;;;;;;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;QAajD;;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;OAaG;IACH,IAAW,KAAK;QAGZ;;;;;;;;;;;;;;WAcG;oCAC+B,MAAM,WAAW,MAAM,IAAI;MAmBhE;IAED,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,MAAM;IAKd;;;;;;;;;;;;;;OAcG;IACU,UAAU;IAuCvB;;;;;;;;;;;;;;OAcG;IACU,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACU,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B9F;;;;;OAKG;IACI,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;YAI/D,oBAAoB;IA4FlC;;;;;;;;;;;;;;;OAeG;IACU,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAevE;;;;;OAKG;IACI,qBAAqB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAUlE;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAK3E;;;;;;;;;;;;;;;;;OAiBG;IACU,mBAAmB,IAAI,OAAO,CAAC;QAC1C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;QAChD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAChC,CAAC;IAuBF;;;;;;;;;;;;;;;;;;;;;;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;IAqBF;;;;;;;;;;;;;;;;;;;;;OAqBG;IACU,mBAAmB,IAAI,OAAO,CAAC,0BAA0B,CAAC;IAKvE;;;;;;OAMG;IACU,6BAA6B,IAAI,OAAO,CAAC;QACpD,WAAW,EAAE,0BAA0B,CAAC;QACxC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAChC,CAAC;IA2BF;;;;;;;;;;;;;;OAcG;IACU,kBAAkB,CAAC,EAC9B,UAAU,EACV,UAAU,GACX,EAAE;QACD,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,6BAA6B,CAAC;KAC3C,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAQrC;;;;;;;;;;;;;;;OAeG;IACU,oBAAoB,CAAC,EAChC,WAAW,EAAE,OAAO,GACrB,EAAE;QACD,WAAW,EAAE,0BAA0B,CAAC;KACzC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAoBrD;;;;;;;;;;;OAWG;YACW,qBAAqB;IA2BnC;;;;;;;;;;;;;;;;;;;;;;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;IAMzD,OAAO,CAAC,eAAe;YAQT,iBAAiB;YAiCjB,kBAAkB;IAchC,OAAO,CAAC,kBAAkB;YAyBZ,2BAA2B;YAI3B,kBAAkB;YAIlB,iBAAiB;CAuBhC"}
+{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../../src/client/configuration.ts"],"names":[],"mappings":"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"}

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"
+  version: "1.17.0-alpha.0"
 ---
 
 ## When to use
@@ -16,8 +16,8 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Docs
 
-- [Connections overview](references/docs-connections-overview.md) - Connect Mastra to remote agents, coding agents, provider software development kit runtimes, and external tools and resources.
-- [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.
+- [Connections](references/docs-connections-overview.md) - Connect Mastra to remote agents, coding agents, provider software development kit runtimes, and external tools and resources.
+- [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.
 - [Fine-Grained Authorization (FGA)](references/docs-server-auth-fga.md) - Add resource-level authorization to your Mastra application with FGA providers.
 
 ### Reference

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Connections overview
+# Connections
 
 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.
 

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

@@ -1,6 +1,6 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# MCP overview
+# MCP
 
 Mastra supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open standard for connecting AI agents to external tools and resources.
 
@@ -252,7 +252,7 @@ Use an MCP App when a tool result benefits from interaction, such as a form, cal
 
 ### Define an app resource
 
-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`:
+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`:
 
 ```typescript
 import { MCPServer } from '@mastra/mcp'
@@ -266,16 +266,15 @@ export const calculatorTool = createTool({
     num1: z.number(),
     num2: z.number(),
   }),
+  mcp: {
+    _meta: { ui: { resourceUri: 'ui://calculator/main' } },
+  },
   execute: async ({ num1, num2 }) => ({
     content: [{ type: 'text', text: 'The result is displayed in the calculator app.' }],
     structuredContent: { result: num1 + num2 },
   }),
 })
 
-calculatorTool._meta = {
-  ui: { resourceUri: 'ui://calculator/main' },
-}
-
 export const calculatorMcpServer = new MCPServer({
   id: 'calculator-app-server',
   name: 'Calculator App Server',

package/dist/docs/references/reference-editor-tools.md

@@ -2,7 +2,7 @@
 
 # Tool configuration
 
-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.
+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.
 
 See [Editor tools](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.
 

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

@@ -59,7 +59,7 @@ To migrate, replace all calls to `mcp.getToolsets()` with `mcp.listToolsets()`.
 
 ### 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.
+Context properties in MCP tools are now organized under the `context.mcp` namespace. The namespace organizes MCP-specific functionality under a clear API surface.
 
 To migrate, access MCP-specific properties like `elicitation` and `extra` through `context.mcp` instead of directly from the context parameter.
 

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

@@ -2,7 +2,7 @@
 
 # MCPClient
 
-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.
+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.
 
 ## Constructor
 
@@ -223,17 +223,23 @@ Retrieves all tools from all configured servers, with tool names namespaced by t
 new Agent({ id: 'agent', tools: await mcp.listTools() })
 ```
 
-### `listToolsWithErrors()`
+### `listToolsWithErrors(options?)`
 
 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.
 
+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.
+
 ```typescript
-const { tools, errors } = await mcp.listToolsWithErrors()
+const { tools, errors, durations } = await mcp.listToolsWithErrors({
+  perServerTimeoutMs: 3_000,
+})
 
 new Agent({ id: 'agent', tools })
-console.log(errors)
+console.log(errors, durations)
 ```
 
+When called without options, the method returns only `tools` and `errors`.
+
 ### `listToolsets()`
 
 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, {
 })
 ```
 
+### `listToolsetsWithErrors(options?)`
+
+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.
+
+```typescript
+const { toolsets, errors, durations } = await mcp.listToolsetsWithErrors({
+  perServerTimeoutMs: 3_000,
+})
+
+const res = await agent.stream(prompt, { toolsets })
+console.log(errors, durations)
+```
+
+When called without options, the method returns only `toolsets` and `errors`.
+
 ### `listToolDefinitions()`
 
 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).
 
-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.
+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.
 
 ```typescript
 const definitions = await mcp.listToolDefinitions()
@@ -256,18 +277,26 @@ const definitions = await mcp.listToolDefinitions()
 await cache.set('mcp-tools', JSON.stringify(definitions))
 ```
 
-### `listToolDefinitionsWithErrors()`
+### `listToolDefinitionsWithErrors(options?)`
 
 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.
 
+Set `perServerTimeoutMs` to limit each server independently. When options are provided, `durations` reports each server's discovery time in milliseconds.
+
 ```typescript
-const { definitions, errors } = await mcp.listToolDefinitionsWithErrors()
+const { definitions, errors, durations } = await mcp.listToolDefinitionsWithErrors({
+  perServerTimeoutMs: 3_000,
+})
 
 if (Object.keys(errors).length === 0) {
   await cache.set('mcp-tools', JSON.stringify(definitions))
 }
+
+console.log(durations)
 ```
 
+When called without options, the method returns only `definitions` and `errors`.
+
 ### `toolFromDefinition()`
 
 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 {
 
 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.
 
-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:
+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:
 
 ```typescript
 import { createOAuthCallbackServer, getCallbackUrlCandidates } from '@mastra/mcp'

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

@@ -2,7 +2,7 @@
 
 # MCPServer
 
-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.
+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.
 
 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.
 
@@ -95,7 +95,7 @@ The constructor accepts an `MCPServerConfig` object with the following propertie
 
 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:
 
-- **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.
+- **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.
 
 - **Tool Functionality**:
 
@@ -104,7 +104,7 @@ A powerful feature of `MCPServer` is its ability to automatically expose your Ma
   - **Execution**: When this tool is called, it invokes the corresponding agent's `generate()` method with the provided `query`.
   - **Output**: The direct result from the agent's `generate()` method is returned as the output of the tool.
 
-- **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.
+- **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.
 
 This makes it straightforward to allow MCP clients to interact with your agents using natural language queries, like any other tool.
 
@@ -116,7 +116,7 @@ The description for this generated tool will be: "Ask agent `<agent.name>` a que
 
 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.
 
-This allows you to quickly expose the generative capabilities of your agents through the MCP, enabling clients to "ask" your agents questions directly.
+Clients can use MCP to access your agents' generative capabilities and ask them questions directly.
 
 ### Accessing MCP Context in Tools
 
@@ -1240,7 +1240,7 @@ const customMiddleware = createOAuthMiddleware({
 
 ## Authentication context
 
-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.
+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.
 
 ### How it works
 
@@ -1637,6 +1637,9 @@ const calculatorTool = createTool({
     num2: z.number(),
     operation: z.enum(['add', 'subtract']),
   }),
+  mcp: {
+    _meta: { ui: { resourceUri: 'ui://calculator/main' } },
+  },
   execute: async ({ num1, num2, operation }) => {
     const result = operation === 'add' ? num1 + num2 : num1 - num2
     return {
@@ -1660,7 +1663,7 @@ const server = new MCPServer({
 })
 ```
 
-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.
+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.
 
 ## Related information
 

package/dist/index.cjs

@@ -23762,25 +23762,31 @@ onListChanged: async (serverName, handler) => {
 	* }
 	* ```
 	*/
-	async listToolsWithErrors() {
+	async listToolsWithErrors(options) {
 		this.addToInstanceCache();
 		const connectedTools = {};
 		const errors = {};
+		const durations = {};
 		const settled = await this.discoverAcrossServers((serverName) => this.getToolsForServer(serverName), {
 			errorId: "MCP_CLIENT_GET_TOOLS_FAILED",
 			logMessage: "Failed to list tools from server:"
-		});
-		for (const { serverName, value, error } of settled) {
+		}, options);
+		for (const { serverName, value, error, duration } of settled) {
+			durations[serverName] = duration;
 			if (error !== void 0) {
 				errors[serverName] = error;
 				continue;
 			}
 			for (const [toolName, toolConfig] of Object.entries(value)) connectedTools[`${serverName}_${toolName}`] = toolConfig;
 		}
-		return {
+		const result = {
 			tools: connectedTools,
 			errors
 		};
+		return options ? {
+			...result,
+			durations
+		} : result;
 	}
 	/**
 	* Returns toolsets organized by server name for dynamic tool injection.
@@ -23825,25 +23831,31 @@ onListChanged: async (serverName, handler) => {
 	* }
 	* ```
 	*/
-	async listToolsetsWithErrors() {
+	async listToolsetsWithErrors(options) {
 		this.addToInstanceCache();
 		const connectedToolsets = {};
 		const errors = {};
+		const durations = {};
 		const settled = await this.discoverAcrossServers((serverName) => this.getToolsForServer(serverName), {
 			errorId: "MCP_CLIENT_GET_TOOLSETS_FAILED",
 			logMessage: "Failed to list toolsets from server:"
-		});
-		for (const { serverName, value, error } of settled) {
+		}, options);
+		for (const { serverName, value, error, duration } of settled) {
+			durations[serverName] = duration;
 			if (error !== void 0) {
 				errors[serverName] = error;
 				continue;
 			}
 			connectedToolsets[serverName] = value;
 		}
-		return {
+		const result = {
 			toolsets: connectedToolsets,
 			errors
 		};
+		return options ? {
+			...result,
+			durations
+		} : result;
 	}
 	/**
 	* Discovers every configured server's tools as plain, serializable definitions.
@@ -23877,27 +23889,33 @@ onListChanged: async (serverName, handler) => {
 	* Useful when caching a catalog, since it lets you avoid persisting a partial manifest that
 	* silently omits a server which happened to be down at discovery time.
 	*/
-	async listToolDefinitionsWithErrors() {
+	async listToolDefinitionsWithErrors(options) {
 		this.addToInstanceCache();
 		const definitions = {};
 		const errors = {};
+		const durations = {};
 		const settled = await this.discoverAcrossServers(async (serverName) => {
 			return (await this.getConnectedClientForServer(serverName)).toolDefinitions();
 		}, {
 			errorId: "MCP_CLIENT_GET_TOOL_DEFINITIONS_FAILED",
 			logMessage: "Failed to list tool definitions from server:"
-		});
-		for (const { serverName, value, error } of settled) {
+		}, options);
+		for (const { serverName, value, error, duration } of settled) {
+			durations[serverName] = duration;
 			if (error !== void 0) {
 				errors[serverName] = error;
 				continue;
 			}
 			definitions[serverName] = value;
 		}
-		return {
+		const result = {
 			definitions,
 			errors
 		};
+		return options ? {
+			...result,
+			durations
+		} : result;
 	}
 	/**
 	* Rebuilds an executable Mastra tool from a cached {@link SerializableMCPToolDefinition}.
@@ -23961,14 +23979,21 @@ onListChanged: async (serverName, handler) => {
 	* Backs `listTools`/`listToolsets`, `resources.list`/`templates`, and
 	* `prompts.list`.
 	*/
-	async discoverAcrossServers(operation, onError) {
+	async discoverAcrossServers(operation, onError, options) {
 		const serverNames = Object.keys(this.serverConfigs);
 		return Promise.all(serverNames.map(async (serverName) => {
+			const startedAt = performance.now();
+			let timer;
 			try {
+				const operationPromise = operation(serverName);
 				return {
 					serverName,
-					value: await operation(serverName),
-					error: void 0
+					value: options?.perServerTimeoutMs === void 0 ? await operationPromise : await Promise.race([operationPromise, new Promise((_, reject) => {
+						timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`Discovery timed out after ${options.perServerTimeoutMs}ms`)), options.perServerTimeoutMs);
+						timer.unref?.();
+					})]),
+					error: void 0,
+					duration: performance.now() - startedAt
 				};
 			} catch (error) {
 				const mastraError = new _mastra_core_error.MastraError({
@@ -23982,8 +24007,11 @@ onListChanged: async (serverName, handler) => {
 				return {
 					serverName,
 					value: void 0,
-					error: error instanceof Error ? error.message : String(error)
+					error: error instanceof Error ? error.message : String(error),
+					duration: performance.now() - startedAt
 				};
+			} finally {
+				clearTimeout(timer);
 			}
 		}));
 	}