@mastra/mcp 2.5.0 → 2.6.0-alpha.0

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

@@ -17,7 +17,9 @@ constructor({
   id?: string;
   servers: Record<string, MastraMCPServerDefinition>;
   timeout?: number;
+  typegen?: { outFile: string };
   clientInfo?: { name?: string; version?: string };
+  registerProcessHooks?: boolean;
 }: MCPClientOptions)
 ```
 
@@ -29,10 +31,174 @@ constructor({
 
 **timeout** (`number`): Global timeout value in milliseconds for all servers unless overridden in individual server configs. (Default: `60000`)
 
+**typegen** (`{ outFile: string }`): Enables optional CLI generation for this client. outFile must be a nonempty path, resolved from the command working directory. Construction stores readonly metadata and does not generate files.
+
 **clientInfo** (`{ name?: string; version?: string }`): Client name and version every server receives on connect and with each request, so servers can attribute traffic to your application. Defaults to the server key as name and '1.0.0' as version. Individual server configs can override either field with their own clientInfo. Doesn't change tool name prefixes, which always use the server key.
 
+**registerProcessHooks** (`boolean`): Install process exit and signal hooks that disconnect servers and end the process. Set to false when your application handles shutdown, and call disconnect() from that handler. See Handle shutdown yourself. (Default: `true`)
+
 **webhook** (`MCPClientWebhookOptions`): Experimental. Enables webhook delivery for MCP events. Servers POST occurrences to webhook.url, which must route to events.handleWebhook().
 
+### Typed client contracts
+
+Pass an explicit server-map type to `MCPClient<TServers>` to check configured server names, discovered tool names, and direct-call arguments. `MCPClientOptions<TServers>` accepts the same map. All declared servers are required. Use `Pick<TServers, 'weather'>` to configure a subset. Without a type argument, discovery keeps its existing broad types.
+
+The map describes each server's `tools`, with `input` and `output` types for each tool. This example assumes a running weather server at `WEATHER_MCP_URL`:
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+
+interface MCPServers {
+  weather: {
+    tools: {
+      get_weather: {
+        input: { location: string }
+        output: { temperature: number; conditions: string }
+      }
+    }
+  }
+}
+
+const mcp = new MCPClient<MCPServers>({
+  servers: { weather: { url: new URL(process.env.WEATHER_MCP_URL!) } },
+})
+
+try {
+  const tools = await mcp.listTools()
+  const weather = tools.weather_get_weather
+  if (weather?.execute) {
+    const result = await weather.execute({ location: 'Paris' })
+    if (result && 'temperature' in result && typeof result.temperature === 'number') {
+      console.log(result.temperature)
+    }
+  }
+} finally {
+  await mcp.disconnect()
+}
+```
+
+`listTools()` and `listToolsWithErrors().tools` expose exact `server_tool` keys. `listToolsets()` and `listToolsetsWithErrors().toolsets` expose server keys containing raw tool names. Both forms are partial: a server or tool can be absent. Check availability before calling a tool. Error maps, error details, and optional discovery durations keep their existing types.
+
+Execution can return the structured output, a protocol result envelope, a validation error, or `undefined`. Check the shape and property types before reading success fields. Protocol envelopes can have additional properties. Set `output: unknown` for tools without an output schema.
+
+These contracts describe a schema snapshot. Live servers can differ from that snapshot. Update them when server schemas change, using equivalent permissions. Extra live tools remain available at runtime but aren't included in the snapshot's known keys. Runtime discovery, validation, and execution are unchanged.
+
+### Generate client types
+
+Generate concrete TypeScript interfaces from live tool input and output schemas with the command included in `@mastra/mcp`. Export your existing client and set `typegen.outFile`:
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+import type { MCPServers } from './mcp-types.generated'
+
+export const mcp = new MCPClient<MCPServers>({
+  id: 'weather-client',
+  servers: { weather: { url: new URL(process.env.WEATHER_MCP_URL!) } },
+  typegen: { outFile: 'src/mcp/mcp-types.generated.ts' },
+})
+```
+
+Set the environment variables and authentication credentials your module needs, then run this command from your project root:
+
+**npm**:
+
+```bash
+npx @mastra/mcp generate ./src/mcp/client.ts
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx @mastra/mcp generate ./src/mcp/client.ts
+```
+
+**Yarn**:
+
+```bash
+yarn dlx @mastra/mcp generate ./src/mcp/client.ts
+```
+
+**Bun**:
+
+```bash
+bun x @mastra/mcp generate ./src/mcp/client.ts
+```
+
+The generated type-only import can be missing on the first run. The loader handles TypeScript and transitive imports without typechecking. Run your typecheck after generation.
+
+Use the generated names and check runtime availability and result shape. This example assumes the server publishes `get_weather` with a required string `location` and a numeric `temperature` output:
+
+```typescript
+import { mcp } from './client'
+
+try {
+  const tools = await mcp.listTools()
+  const weather = tools.weather_get_weather
+  if (weather?.execute) {
+    const result = await weather.execute({ location: 'Paris' })
+    if (result && 'temperature' in result && typeof result.temperature === 'number') {
+      console.log(result.temperature)
+    }
+  }
+} finally {
+  await mcp.disconnect()
+}
+```
+
+The command accepts one or more file paths. Both input files and `outFile` paths are relative to the command's working directory. It selects direct named and default exports of typegen-enabled clients. It doesn't scan your source tree, invoke factories, or inspect nested exported objects. Repeated files, symlink aliases, and exports of the same client are processed once. A file without an eligible client fails.
+
+For independent clients with identical server configurations, use distinct IDs and output paths:
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+
+const servers = { weather: { url: new URL(process.env.WEATHER_MCP_URL!) } }
+export const first = new MCPClient({
+  id: 'first',
+  servers,
+  typegen: { outFile: 'first.generated.ts' },
+})
+export const second = new MCPClient({
+  id: 'second',
+  servers,
+  typegen: { outFile: 'second.generated.ts' },
+})
+```
+
+**npm**:
+
+```bash
+npx @mastra/mcp generate ./src/mcp/clients.ts
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx @mastra/mcp generate ./src/mcp/clients.ts
+```
+
+**Yarn**:
+
+```bash
+yarn dlx @mastra/mcp generate ./src/mcp/clients.ts
+```
+
+**Bun**:
+
+```bash
+bun x @mastra/mcp generate ./src/mcp/clients.ts
+```
+
+The existing instance cache still applies. Constructing a client with the same explicit ID, server configuration, and `typegen.outFile` returns the existing object. A different server configuration or `outFile` replaces the cached instance instead, so a later constructor never silently keeps an output file it wasn't given.
+
+Generation lists tool definitions without calling tools. It fails on discovery errors, missing authentication, timeouts, output collisions, outputs that overwrite supplied input files, and schemas that can't be represented at all, such as reference cycles, excessive depth, or unresolved local references. Each failure names the client file, server, or tool it concerns. It prepares all sources before replacing files and disconnects selected clients on success or failure. Discovery and preflight failures preserve existing outputs. Each replacement is atomic, but multiple replacements aren't one transaction. A filesystem failure during replacement can leave earlier files updated.
+
+Tools without output schemas use `unknown`. Constraints such as string formats, length limits, and numeric bounds retain their base TypeScript types and remain runtime validation rules. Unsupported schema portions, including conditional schemas and `prefixItems` tuples, widen to `unknown` with a warning. A keyword whose value is outside its allowed shape widens that schema to `unknown` with a warning too, so one unusable tool doesn't stop generation for other servers. Warnings name the server, tool, and schema position they concern. External schema references aren't fetched. Unresolved local references and reference cycles fail generation. Schemas nested deeper than 128 levels fail generation too, matching the protocol depth limit. A schema that exceeds the protocol node budget of 10,000 widens to `unknown` with a warning, as does any schema or catalogue that exceeds the larger budgets generation applies to raw JSON values. Generation measures those budgets before it copies or converts a schema, so a server that advertises large schemas can't stall the command.
+
+> **Module execution and credentials:** The command executes the supplied modules and their imports. Use trusted modules without application startup side effects. Provide credentials before invoking the command. It doesn't load dotenv files or launch interactive authentication. Existing client timeout and discovery settings apply.
+>
+> Generator diagnostics omit raw schemas, transport errors, and credentials. Logs emitted by your imported application, custom log handlers, or server subprocesses remain outside that guarantee.
+
 ### `MastraMCPServerDefinition`
 
 Each server in the `servers` map is configured using the `MastraMCPServerDefinition` type. The transport type is detected based on the provided parameters:
@@ -765,9 +931,9 @@ Notes:
 
 ### `events` Property (experimental)
 
-The `events` property lists and subscribes to server events from servers that implement the [MCP Events extension (SEP-3415)](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/3415). Use it to react to things that happen on the server, such as a push to a repository, without polling a tool.
+The `events` property lists and subscribes to server events from servers that implement the [MCP Events extension (SEP-3415)](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/3415). Use it to react to things that happen on the server, such as a push to a repository, without polling a tool. Delivery is at least once. After a reconnect or a resume, the server can resend an occurrence, and the client drops repeats by `eventId` within `dedupWindow` of recent ids.
 
-For an end-to-end walkthrough, see the [MCP events guide](https://mastra.ai/docs/guides/mcp-events).
+For an end-to-end walkthrough, see [MCP events](https://mastra.ai/docs/connections/mcp).
 
 > **Warning:** SEP-3415 is a draft. This API may change in any release.
 
@@ -802,7 +968,7 @@ The client doesn't receive notifications when the server's event list changes ye
 
 #### `events.subscribe(serverName, eventName, args?, options?)`
 
-Starts a subscription and resolves once the server confirms it. Errors such as an unknown event, invalid arguments, or a forbidden subscription reject the returned promise.
+Starts a subscription and resolves once the server confirms it. Errors such as an unknown event, invalid arguments, or a forbidden subscription reject the returned promise. A new subscription starts at the point the server accepts it, so occurrences from before that point are not delivered unless `options.cursor` resumes from an earlier position. Under webhook delivery the promise can resolve after that point: the client answers `503` for a delivery it can't route yet, and the server retries it.
 
 ```typescript
 async subscribe(
@@ -860,7 +1026,7 @@ It verifies the Standard Webhooks signature on the raw body before parsing it, a
 
 - `200` after the occurrence is handed to its subscription, or with the echoed challenge for a verification request.
 - `401` when the signature is invalid or the timestamp is more than 5 minutes old.
-- `503` when the subscription id isn't known yet, so the server retries. This covers deliveries that arrive before the subscribe response.
+- `503` when the subscription id isn't known yet. The server retries in that case, covering deliveries that arrive before the subscribe response.
 - `400` for a signed but malformed body, and `405` for methods other than `POST`.
 - `413` for a body over 1 MiB. The body is read only up to that limit, before any other check.
 - `404` when the client has no `webhook` settings.
@@ -906,11 +1072,11 @@ export const mastra = new Mastra({
 
 **refreshMarginMs** (`number`): How long before the server-granted refreshBefore time to refresh the subscription. Defaults to the smaller of 60 seconds and 20% of the grant.
 
-The client refreshes each subscription before it expires by repeating `events/subscribe` with the latest cursor. When the server reports failing delivery in `deliveryStatus`, for example because your endpoint timed out, `onError` receives `MCP_EVENTS_WEBHOOK_DELIVERY_FAILING` with `lastError` in its details. The next refresh resumes a suspended subscription. `cancel()` sends `events/unsubscribe`.
+The client refreshes each subscription before it expires by repeating `events/subscribe` with the latest cursor. When the server reports failing delivery in `deliveryStatus`, for example because your endpoint timed out, `onError` receives `MCP_EVENTS_WEBHOOK_DELIVERY_FAILING` with `lastError` in its details. The `cursor` in each webhook delivery only covers occurrences your endpoint has acknowledged, so resuming from a saved cursor can deliver the last handled occurrence again. The next refresh resumes a suspended subscription. `cancel()` sends `events/unsubscribe`.
 
 Webhook state lives in this process: run the receiving route in the same process as the `MCPClient` that subscribed.
 
-Webhook delivery needs an authenticated HTTP connection to the server, because the server ties each webhook subscription to the caller. Over stdio, or over HTTP without authentication, the server rejects `events/subscribe`; it also rejects new subscriptions once its webhook subscription cap is reached (`-32025`). A subscription that didn't force a mode then falls back to `push` or `poll`, and the first `onError` handler receives `MCP_EVENTS_WEBHOOK_UNAVAILABLE` with the rejection `code` and the `fallback` mode in its details. Forcing `delivery: 'webhook'` rejects instead.
+Webhook delivery needs an authenticated HTTP connection to the server, because the server ties each webhook subscription to the caller. Over stdio, or over HTTP without authentication, the server rejects `events/subscribe`. It also rejects new subscriptions once its webhook subscription cap is reached (`-32025`). A subscription that didn't force a mode then falls back to `push` or `poll`, and the first `onError` handler receives `MCP_EVENTS_WEBHOOK_UNAVAILABLE` with the rejection `code` and the `fallback` mode in its details. Forcing `delivery: 'webhook'` rejects instead.
 
 Subscriptions on one server with the same event name and arguments share a single server-side webhook subscription. Each one gets every occurrence through its own iterator, and the client sends `events/unsubscribe` only when the last of them is cancelled.
 
@@ -937,7 +1103,7 @@ export const repoAgent = new Agent({
   id: 'repo-agent',
   name: 'Repo Agent',
   instructions: 'Triage repository activity.',
-  model: 'openai/gpt-5.6-sol',
+  model: 'openai/gpt-6.1-sol',
   signals: [repoEvents],
 })
 
@@ -947,7 +1113,7 @@ await repoEvents.subscribeThread(
 )
 ```
 
-Threads that subscribe to the same server, event and arguments share one MCP subscription. Argument key order doesn't matter. Each occurrence becomes a notification with `kind: 'mcp-event'` and `attributes: { server, event }`. The raw occurrence is in `payload`. The notification `summary`, which is the only part the model reads, labels the event as untrusted and wraps its data, together with the server-advertised event name, in an `<untrusted-mcp-event-data>` block that the content can't close. When the server reports a gap, `attributes.truncated` is `true` and the summary says that events may have been skipped.
+Threads that subscribe to the same server, event and arguments share one MCP subscription regardless of argument key order. Each occurrence becomes a notification with `kind: 'mcp-event'` and `attributes: { server, event }`. The raw occurrence is in `payload`. The notification `summary`, which is the only part the model reads, labels the event as untrusted and wraps its data, together with the server-advertised event name, in an `<untrusted-mcp-event-data>` block that the content can't close. When the server reports a gap, `attributes.truncated` is `true` and the summary says that events may have been skipped.
 
 If the subscription ends, for example because the server terminates it, each subscribed thread receives a `high` priority notification with `kind: 'mcp-event-subscription-ended'` and the threads are unsubscribed.
 
@@ -1234,7 +1400,7 @@ const client = new MCPClient({
 
 ### Custom Token Storage
 
-For persistent token storage across sessions, implement the `OAuthStorage` interface. The provider stores tokens (both the latest set and one entry per authorization-server issuer), discovery state, and the PKCE verifier under string keys, so the backend only needs a key-value contract:
+For persistent token storage across sessions, implement the `OAuthStorage` interface. The provider stores tokens (both the latest set and one entry per authorization-server issuer), discovery state, and the PKCE verifier under string keys. The backend only needs a key-value contract:
 
 ```typescript
 import { MCPOAuthClientProvider, OAuthStorage } from '@mastra/mcp'
@@ -1310,7 +1476,7 @@ const agent = new Agent({
   id: 'multi-tool-agent',
   name: 'Multi-tool Agent',
   instructions: 'You have access to multiple tool servers.',
-  model: 'openai/gpt-5.6-sol',
+  model: 'openai/gpt-6.1-sol',
   tools: await mcp.listTools(),
 })
 
@@ -1361,7 +1527,7 @@ const agent = new Agent({
   id: 'multi-tool-agent',
   name: 'Multi-tool Agent',
   instructions: 'You help users check stocks and weather.',
-  model: 'openai/gpt-5.6-sol',
+  model: 'openai/gpt-6.1-sol',
 })
 
 // Later, configure MCP with user-specific settings
@@ -1436,6 +1602,31 @@ MCPClient handles server connections gracefully:
 2. Graceful server shutdown to prevent error messages during development
 3. Proper cleanup of resources when disconnecting
 
+### Handle shutdown yourself
+
+By default, a connected client installs hooks for `SIGINT`, `SIGTERM`, `SIGHUP`, and `beforeExit` that disconnect its servers and end the process. These hooks can interrupt your application's awaited cleanup, such as draining HTTP requests.
+
+Set `registerProcessHooks: false` to let your application own shutdown. Call `disconnect()` after requests that use the client have finished:
+
+```typescript
+import { MCPClient } from '@mastra/mcp'
+
+const mcp = new MCPClient({
+  servers: { weather: { url: new URL('https://example.com/mcp') } },
+  registerProcessHooks: false,
+})
+
+process.once('SIGTERM', async () => {
+  // Finish your application's cleanup before disconnecting the client.
+  await mcp.disconnect()
+  process.exit(0)
+})
+```
+
+Set the option on every `MCPClient` in the process before connecting. Once any client registers the default hooks, the global `SIGINT` and `SIGTERM` listeners remain until the process exits, even after `disconnect()`.
+
+With hooks disabled, your application is responsible for closing MCP connections. In a Mastra server, coordinate `disconnect()` with your server's shutdown lifecycle so in-flight requests can finish using the client.
+
 ## Using custom fetch for runtime-defined authentication
 
 For HTTP servers, you can provide a custom `fetch` function to handle runtime-defined authentication or request interception. It can also handle other custom behavior. This is particularly useful when you need to refresh tokens on each request or forward user credentials from the incoming request to the MCP server.

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

@@ -28,7 +28,7 @@ const myAgent = new Agent({
   name: 'MyExampleAgent',
   description: 'A generalist to help with basic questions.',
   instructions: 'You are a helpful assistant.',
-  model: 'openai/gpt-5.6-sol',
+  model: 'openai/gpt-6.1-sol',
 })
 
 const weatherTool = createTool({
@@ -93,6 +93,8 @@ The constructor accepts an `MCPServerConfig` object with the following propertie
 
 **cacheHints** (`MCPServerCacheHints`): Cache hints (ttlMs / cacheScope) advertised on cacheable results, keyed by operation: 'tools/list', 'prompts/list', 'resources/list', 'resources/templates/list', 'resources/read' and 'server/discover'.
 
+**legacy** (`'reject' | 'stateless'`): How HTTP requests from 2025-era clients (those that open with initialize, such as VS Code and Cursor) are served. 'reject' (default) answers them with an unsupported-protocol-version error. 'stateless' answers each request without a session: listing and calling tools, reading resources and getting prompts work, GET and DELETE session requests get 405, and features that need 2026-07-28 (suspend/resume, subscriptions/listen, events) aren't available to these clients.
+
 **jsonSchemaValidator** (`jsonSchemaValidator`): Custom JSON Schema validator used for tool input, output and continuation answers, for runtimes where the SDK default is unavailable.
 
 **repository** (`Repository`): Optional repository information for the server's source code.
@@ -1418,7 +1420,7 @@ Link a tool to its app resource by setting `mcp._meta.ui.resourceUri` in `create
 
 > **Warning:** Events implement [SEP-3415](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/3415), a draft MCP extension. The wire format and this API may change in any release.
 
-For an end-to-end walkthrough, see the [MCP events guide](https://mastra.ai/docs/guides/mcp-events).
+For an end-to-end walkthrough, see [MCP events](https://mastra.ai/docs/connections/mcp).
 
 The `events` option lets clients subscribe to things that happen on your server, such as a ticket being created or a build finishing. The server advertises the `io.modelcontextprotocol/events` extension and answers `events/list`, `events/poll` and `events/stream` over both stdio and Streamable HTTP. With [`eventsOptions.webhook`](#webhook-delivery) set, it also answers `events/subscribe` and `events/unsubscribe` and POSTs occurrences to client webhook URLs.
 
@@ -1476,7 +1478,7 @@ const ticketCreated = defineEvent({
 
 **authorize** (`(context) => boolean | Promise<boolean>`): Decides whether the caller may receive this type with these arguments. Receives arguments, requestContext and delivery ('poll', 'push' or 'webhook'). Runs on every events/poll, before a poll source is called, on every events/stream open, and on every webhook events/subscribe, including refreshes. Returning false rejects the request with -32024. A refresh that is denied also removes the webhook subscription. If it throws, the client gets a generic -32603 error and the details are logged on the server. Defaults to allowing every caller.
 
-**poll** (`(context) => Promise<MCPServerEventPollResult>`): Pull source for events/poll. Receives arguments, cursor (null means start from now), maxEvents, maxAgeMs, requestContext and signal. Returns { events, cursor, hasMore?, nextPollMs?, truncated? }. Each event needs data and a stable eventId (clients dedupe by it, so return the same id whenever the same occurrence is polled); a missing timestamp defaults to now. If poll or match throws, the client gets a generic -32603 error and the details are logged on the server.
+**poll** (`(context) => Promise<MCPServerEventPollResult>`): Pull source for events/poll. Receives arguments, cursor (null means start from now), maxEvents, maxAgeMs, requestContext and signal. Returns { events, cursor, hasMore?, nextPollMs?, truncated? }. Each event needs data and a stable eventId (clients dedupe by it, so return the same id whenever the same occurrence is polled); when cursor is null, resolve the starting position once, and return the id of the last occurrence, or that starting position when the result is empty; a missing timestamp defaults to now. If poll or match throws, the client gets a generic -32603 error and the details are logged on the server.
 
 **delivery** (`Array<'poll' | 'push' | 'webhook'>`): Restricts the advertised delivery modes to this list. It only narrows the modes from the table below, and a definition left with no mode throws when the server is constructed.