@mastra/mcp-docs-server 1.2.19-alpha.0 → 1.2.19-alpha.14

package/.docs/reference/core/mastra-class.md

@@ -79,7 +79,7 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 **bundler** (`BundlerConfig`): Configuration for the asset bundler with options for externals, sourcemap, transpilePackages, and dynamicPackages. (Default: `{ externals: [], sourcemap: false, transpilePackages: [], dynamicPackages: [] }`)
 
-**scorers** (`Record<string, Scorer>`): Scorers for evaluating agent responses and workflow outputs (Default: `{}`)
+**scorers** (`Record<string, Scorer>`): Scorers for evaluating agent responses and workflow outputs. Registration also makes a scorer resolvable by ID, which is required to persist its scores. See Score persistence (Default: `{}`)
 
 **processors** (`Record<string, Processor>`): Input/output processors for transforming agent inputs and outputs (Default: `{}`)
 

package/.docs/reference/evals/checks.md

@@ -6,6 +6,8 @@ Quick Checks are zero-LLM, composable micro-scorers for common assertions. They
 
 Internally they're standard `createScorer()` instances, so they have the same observability, storage, and pipeline integration as any other scorer.
 
+> **Register checks to persist their scores:** A check's score is only written to the scores store when the check is registered on the Mastra instance, alongside `storage`. Each check has a fixed id (`checks.includes()` is `check-includes`, `checks.calledTool()` is `check-called-tool`, and so on), so one registered instance covers every use of that check regardless of its arguments. See [Score persistence](https://mastra.ai/docs/evals/overview).
+
 ## Usage example
 
 ```typescript
@@ -203,6 +205,10 @@ const result = await runEvals({
 })
 ```
 
+## Multi-turn behavior
+
+Checks read the accumulated `run.output`, so in a [multi-turn eval](https://mastra.ai/docs/evals/multi-turn) they see every turn. `checks.calledTool('get_weather', { times: 2 })` counts calls across the whole conversation, and `checks.includes()` searches all assistant text. Use per-turn `turns[].scorers` when a specific turn has to satisfy the check.
+
 ## Related
 
 - [Quick Checks overview](https://mastra.ai/docs/evals/quick-checks)

package/.docs/reference/evals/multi-turn-judge.md

@@ -0,0 +1,101 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Multi-turn Judge scorer
+
+**Added in:** `@mastra/evals@1.9.0`
+
+The `createMultiTurnJudgeScorer()` function creates an LLM-as-judge scorer that grades a whole conversation against a single plain-English criterion. It returns a **binary** score: `1` when the criterion is satisfied, otherwise `0`, and the `reason` echoes the criterion with the judge's explanation.
+
+Unlike the other prebuilt LLM judges, which read a single assistant message, this scorer reads every assistant turn accumulated in `run.output`, so it works with the [multi-turn `inputs`](https://mastra.ai/docs/evals/multi-turn) form of [`runEvals()`](https://mastra.ai/reference/evals/run-evals).
+
+## Parameters
+
+**model** (`MastraModelConfig`): The language model used to grade the conversation. A smaller, cheaper model is usually sufficient for grading.
+
+**criterion** (`string`): What the conversation must satisfy, in plain English, e.g. "The agent gave forecasts for London and Paris, and weather-appropriate packing advice".
+
+**options** (`MultiTurnJudgeScorerOptions`): Configuration options for the scorer
+
+## `.run()` returns
+
+**score** (`number`): 1 when the judge considers the criterion satisfied, otherwise 0 (multiplied by scale).
+
+**reason** (`string`): The verdict, the criterion it graded, and the judge's explanation of why the criterion is or is not satisfied.
+
+## Usage with multi-turn evals
+
+Pass the scorer to `runEvals` alongside an `inputs` array. Every assistant turn is included in the prompt sent to the judge:
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { createMultiTurnJudgeScorer } from '@mastra/evals/scorers/prebuilt'
+import { weatherAgent } from '../agents'
+
+const result = await runEvals({
+  data: [
+    {
+      inputs: [
+        "I'm planning a trip to London, Paris, and Tokyo next week.",
+        "How's the weather looking in London?",
+        'And Paris?',
+        'Tokyo too?',
+        'Should I pack an umbrella for the London leg?',
+      ],
+    },
+  ],
+  target: weatherAgent,
+  scorers: [
+    {
+      scorer: createMultiTurnJudgeScorer({
+        model: 'anthropic/claude-haiku-4-5',
+        criterion:
+          'The agent provided weather forecasts for London, Paris, and Tokyo, and gave weather-appropriate packing or clothing advice.',
+      }),
+      threshold: 1,
+    },
+  ],
+})
+```
+
+Use `threshold: 1` to turn the verdict into a pass or fail: the score is binary, so any lower threshold always passes.
+
+## Persisting scores
+
+Scores are only written to the scores store when a scorer with the same ID is registered on the Mastra instance, because persistence resolves scorer metadata through `Mastra.getScorerById()`. Only the ID is looked up, so the registered instance's `criterion` can be a placeholder:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+import { createMultiTurnJudgeScorer } from '@mastra/evals/scorers/prebuilt'
+
+export const mastra = new Mastra({
+  agents: { weatherAgent },
+  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+  scorers: {
+    'multi-turn-judge-scorer': createMultiTurnJudgeScorer({
+      model: 'anthropic/claude-haiku-4-5',
+      criterion: 'placeholder',
+    }),
+  },
+})
+```
+
+See [Score persistence](https://mastra.ai/docs/evals/overview) for the full requirement and the warning you get when a scorer isn't registered.
+
+## Scoring details
+
+The scorer runs in two phases:
+
+1. **Grade**: Every assistant message in `run.output` is collected in order and rendered as a numbered transcript, then the judge decides whether the conversation as a whole satisfies the criterion. Assistant messages with no text (a turn that only carried tool calls, for example) are skipped.
+2. **Score**: A `satisfied` verdict scores `1` and anything else scores `0`, multiplied by `scale`.
+
+The judge only sees what the assistant said. The user's turns and any tool results aren't included, so write criteria in terms of the agent's responses. This keeps the graded text limited to the agent's own output, but it also means a reply that only makes sense next to the question that prompted it ("Yes, bring one.") can't be judged on its own. For criteria that depend on the user's turns, grade each turn with `turns[].scorers` or write a [custom scorer](https://mastra.ai/docs/evals/multi-turn) that renders both roles.
+
+The transcript is passed to the judge as untrusted data, fenced with explicit delimiters and an instruction to ignore anything inside it that reads as an instruction, so an agent response can't talk its way into a passing verdict.
+
+## Related
+
+- [Multi-turn evals](https://mastra.ai/docs/evals/multi-turn)
+- [`runEvals()`](https://mastra.ai/reference/evals/run-evals)
+- [Rubric scorer](https://mastra.ai/reference/evals/rubric)
+- [createScorer](https://mastra.ai/reference/evals/create-scorer)

package/.docs/reference/index.md

@@ -45,6 +45,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [toAISdkV4Messages()](https://mastra.ai/reference/ai-sdk/to-ai-sdk-v4-messages)
 - [toAISdkV5Messages()](https://mastra.ai/reference/ai-sdk/to-ai-sdk-v5-messages)
 - [withMastra()](https://mastra.ai/reference/ai-sdk/with-mastra)
+- [withSseHeartbeat()](https://mastra.ai/reference/ai-sdk/with-sse-heartbeat)
 - [workflowRoute()](https://mastra.ai/reference/ai-sdk/workflow-route)
 - [workflowSnapshotToStream()](https://mastra.ai/reference/ai-sdk/workflow-snapshot-to-stream)
 - [Auth0](https://mastra.ai/reference/auth/auth0)
@@ -152,6 +153,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Faithfulness](https://mastra.ai/reference/evals/faithfulness)
 - [Hallucination](https://mastra.ai/reference/evals/hallucination)
 - [Keyword Coverage Scorer](https://mastra.ai/reference/evals/keyword-coverage)
+- [Multi-turn Judge Scorer](https://mastra.ai/reference/evals/multi-turn-judge)
 - [Noise Sensitivity Scorer](https://mastra.ai/reference/evals/noise-sensitivity)
 - [Prompt Alignment Scorer](https://mastra.ai/reference/evals/prompt-alignment)
 - [Rubric Scorer](https://mastra.ai/reference/evals/rubric)
@@ -276,6 +278,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [PubSub](https://mastra.ai/reference/pubsub/base)
 - [RedisStreamsPubSub](https://mastra.ai/reference/pubsub/redis-streams)
 - [UnixSocketPubSub](https://mastra.ai/reference/pubsub/unix-socket-pubsub)
+- [ValkeyStreamsPubSub](https://mastra.ai/reference/pubsub/valkey-streams)
 - [Overview](https://mastra.ai/reference/rag/overview)
 - [Chunking and Embedding](https://mastra.ai/reference/rag/chunking-and-embedding)
 - [DatabaseConfig](https://mastra.ai/reference/rag/database-config)
@@ -307,6 +310,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Overview](https://mastra.ai/reference/storage/overview)
 - [Composite Storage](https://mastra.ai/reference/storage/composite)
 - [Retention (prune)](https://mastra.ai/reference/storage/retention)
+- [Turso Storage](https://mastra.ai/reference/storage/turso)
 - [ChunkType](https://mastra.ai/reference/streaming/ChunkType)
 - [smoothStream()](https://mastra.ai/reference/streaming/smoothStream)
 - [MastraModelOutput](https://mastra.ai/reference/streaming/agents/MastraModelOutput)

package/.docs/reference/pubsub/valkey-streams.md

@@ -0,0 +1,84 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# ValkeyStreamsPubSub
+
+`ValkeyStreamsPubSub` is a [`PubSub`](https://mastra.ai/reference/pubsub/base) and [`LeaseProvider`](https://mastra.ai/reference/pubsub/lease-provider) implementation backed by Valkey Streams through [Valkey GLIDE](https://github.com/valkey-io/valkey-glide). It provides persistent cross-process delivery, consumer groups, redelivery, topic cleanup, and distributed leasing.
+
+Use it for Valkey deployments. Use [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) for Redis deployments that use the official `redis` client. Both integrations implement the same Mastra behavior, with independent tests running against Valkey and Redis.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/valkey-streams
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/valkey-streams
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/valkey-streams
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/valkey-streams
+```
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { ValkeyStreamsPubSub } from '@mastra/valkey-streams'
+
+export const mastra = new Mastra({
+  pubsub: new ValkeyStreamsPubSub({
+    url: 'valkey://localhost:6379',
+  }),
+})
+```
+
+## Constructor parameters
+
+**url** (`string`): Valkey connection URL. Falls back to valkeyOptions.url. (Default: `valkey://localhost:6379`)
+
+**valkeyOptions** (`ValkeyClientOptions`): GLIDE connection options, including native client configuration.
+
+**keyPrefix** (`string`): Prefix for stream keys. (Default: `mastra:topic`)
+
+**blockMs** (`number`): How long each read blocks while waiting for events. (Default: `1000`)
+
+**maxStreamLength** (`number`): Approximate maximum entries retained per stream. Set to 0 to disable trimming. (Default: `10000`)
+
+**streamIdleTtlMs** (`number`): Sliding idle expiry refreshed on stream writes. Set to 0 to disable. (Default: `0`)
+
+**reclaimIntervalMs** (`number`): Interval for reclaiming unacknowledged events. Set to 0 to disable. (Default: `30000`)
+
+**reclaimIdleMs** (`number`): Minimum idle time before an event can be reclaimed. (Default: `60000`)
+
+**maxDeliveryAttempts** (`number`): Maximum nack redeliveries. Pass Infinity to disable the cap. (Default: `5`)
+
+**logger** (`{ debug?: Function; warn?: Function }`): Optional diagnostic logger.
+
+## Delivery behavior
+
+`ValkeyStreamsPubSub` supports pull delivery and doesn't support numeric replay offsets. Grouped subscribers compete for events through a shared consumer group. Subscribers without a group receive fan-out delivery through private consumer groups.
+
+Use `startFrom: "latest"` to skip retained entries when a group is first created. The default, `"earliest"`, reads retained entries first.
+
+## Cleanup and shutdown
+
+`clearTopic(topic)` deletes a topic stream and its consumer groups. `flush()` waits for in-flight publishes, and `close()` stops subscriptions and closes GLIDE connections.
+
+```typescript
+await pubsub.clearTopic('workflow.events.run-123')
+await pubsub.flush()
+await pubsub.close()
+```

package/.docs/reference/rag/vector-databases.md

@@ -27,9 +27,9 @@ await store.upsert({
 })
 ```
 
-### Using MongoDB Atlas Vector Search
+### Using MongoDB Vector Search
 
-For detailed setup instructions and best practices, see the [official MongoDB Atlas Vector Search documentation](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/?utm_campaign=devrel\&utm_source=third-party-content\&utm_medium=cta\&utm_content=mastra-docs).
+MongoDB Vector Search is a good solution for teams who want to consolidate vector search, full-text search, and operational data in a single database to minimize infrastructure complexity and maintain production-grade performance. For detailed setup instructions and best practices, see the [official MongoDB Vector Search documentation](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/?utm_campaign=devrel\&utm_source=third-party-content\&utm_medium=cta\&utm_content=mastra-docs).
 
 ### Using VoyageAI with MongoDB
 
@@ -37,7 +37,7 @@ MongoDB works seamlessly with VoyageAI's embedding models, which are optimized f
 
 ### Hybrid Search (Vector + Full-Text)
 
-MongoDB supports hybrid search that fuses vector similarity with BM25 full-text search using server-side `$rankFusion` (requires MongoDB >= 8.0; generally available from 8.1, and enabled on Atlas 8.0.x). This is useful when you want to combine semantic and keyword-based retrieval:
+MongoDB supports hybrid search that fuses vector similarity with BM25 full-text search using server-side `$rankFusion` (requires MongoDB >= 8.0; generally available from 8.1, and enabled on MongoDB Atlas 8.0.x). This is useful when you want to combine semantic and keyword-based retrieval:
 
 ```ts
 await store.createSearchIndex({ indexName: 'myCollection', fields: ['text'] })
@@ -420,7 +420,7 @@ Each vector database enforces specific naming conventions for indexes and collec
 
 **MongoDB**:
 
-Collection (index) names must:
+Collection and index names must:
 
 - Start with a letter or underscore
 - Be up to 120 bytes long

package/.docs/reference/server/express-adapter.md

@@ -162,13 +162,13 @@ Available properties on `res.locals`:
 
 ## Adding middleware
 
-Add Express middleware before or after `init()`:
+Add Express middleware before `init()` to run it on every request. Mastra context isn't available at that point:
 
 ```typescript
 const app = express()
 app.use(express.json())
 
-// Middleware before init
+// Runs on every request, before Mastra context exists
 app.use((req, res, next) => {
   console.log(`${req.method} ${req.url}`)
   next()
@@ -176,14 +176,12 @@ app.use((req, res, next) => {
 
 const server = new MastraServer({ app, mastra })
 await server.init()
-
-// Middleware after init has access to Mastra context
-app.use((req, res, next) => {
-  const mastra = res.locals.mastra
-  next()
-})
 ```
 
+Middleware added after `init()` never runs for Mastra's routes. Express dispatches handlers in registration order, so middleware registered after the routes only applies to routes added later.
+
+This adapter can't run [`server.middleware`](https://mastra.ai/docs/server/middleware) handlers because they use Hono's signature, and it logs a warning when that option is set. If you need Express middleware between Mastra's context step and its routes, use the manual initialization flow below.
+
 ## Manual initialization
 
 For custom middleware ordering, call each method separately instead of `init()`. See [manual initialization](https://mastra.ai/docs/server/server-adapters) for details.

package/.docs/reference/server/hono-adapter.md

@@ -145,7 +145,7 @@ Available context keys:
 
 ## Adding middleware
 
-Add Hono middleware before or after `init()`:
+Add Hono middleware with `app.use()` before `init()` to run it on every request. Mastra context isn't available at that point:
 
 ```typescript
 import { Hono } from 'hono'
@@ -153,7 +153,7 @@ import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'
 
 const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()
 
-// Middleware before init
+// Runs on every request, before Mastra context exists
 app.use('*', async (c, next) => {
   console.log(`${c.req.method} ${c.req.url}`)
   await next()
@@ -161,11 +161,24 @@ app.use('*', async (c, next) => {
 
 const server = new MastraServer({ app, mastra })
 await server.init()
+```
 
-// Middleware after init has access to Mastra context
-app.use('*', async (c, next) => {
-  const mastra = c.get('mastra')
-  await next()
+Middleware added after `init()` never runs for Mastra's routes. Hono dispatches handlers in registration order, so middleware registered after the routes only applies to routes added later.
+
+To run middleware with Mastra context on Mastra's routes, use [`server.middleware`](https://mastra.ai/docs/server/middleware) in the Mastra config. The adapter registers it during `init()`, after the context step and before any route. These handlers are skipped for routes declared public with `requiresAuth: false`, so they can't block endpoints such as the Studio sign-in routes:
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+export const mastra = new Mastra({
+  server: {
+    middleware: [
+      async (c, next) => {
+        c.get('requestContext').set('locale', c.req.header('accept-language') ?? 'en')
+        await next()
+      },
+    ],
+  },
 })
 ```
 

package/.docs/reference/storage/turso.md

@@ -0,0 +1,88 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Turso Storage
+
+Use `@mastra/turso` to store Mastra agents, workflows, memory, and other storage domains in a local [Turso Database](https://github.com/tursodatabase/turso) file.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/turso
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/turso
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/turso
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/turso
+```
+
+## Usage
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { TursoStore } from '@mastra/turso'
+
+export const mastra = new Mastra({
+  storage: new TursoStore({
+    id: 'local-storage',
+    path: './mastra.db',
+  }),
+})
+```
+
+## Constructor options
+
+- `id` (required): Unique identifier for the storage instance.
+- `path` (required unless `client` is provided): Path to the local database file.
+- `client`: A compatible SQLite client to use instead of creating a native Turso client.
+- `readonly`: Opens the database in read-only mode.
+- `fileMustExist`: Requires the database file to exist before opening it.
+- `timeout`: Connection timeout in milliseconds.
+- `defaultQueryTimeout`: Default query timeout in milliseconds.
+- `tracing`: Native driver tracing level: `info`, `debug`, or `trace`.
+- `experimental`: Native Turso Database experimental features to enable.
+- `maxRetries`: Maximum number of retries for retryable writes.
+- `initialBackoffMs`: Initial retry delay in milliseconds.
+- `disableInit`: Disables automatic storage initialization.
+- `retention`: Retention policies for supported storage domains.
+
+## Platform support
+
+The native driver supports macOS on arm64, Windows on x64, and glibc-based Linux on x64 and arm64. Use `getTursoDatabaseSupport()` when your application needs to choose a fallback on unsupported systems.
+
+```typescript
+import { getTursoDatabaseSupport } from '@mastra/turso'
+
+const support = getTursoDatabaseSupport()
+if (!support.supported) {
+  console.warn(support.reason)
+}
+```
+
+## Experimental features
+
+Experimental Turso Database features are disabled by default. Enable only the features your application requires.
+
+```typescript
+const storage = new TursoStore({
+  id: 'multiprocess-storage',
+  path: './mastra.db',
+  experimental: ['multiprocess_wal'],
+})
+```
+
+`@mastra/turso` provides local-file Mastra storage. It doesn't connect to remote libSQL databases and doesn't include a vector store.

package/.docs/reference/streaming/ChunkType.md

@@ -272,8 +272,36 @@ Contains file data.
 
 **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata
 
+### reasoning-file
+
+Contains a file generated by the model as part of its reasoning. Emitted by providers on the AI SDK v7 specification.
+
+**type** (`"reasoning-file"`): Chunk type identifier
+
+**payload** (`ReasoningFilePayload`): Reasoning file data
+
+**payload.data** (`string | Uint8Array`): The file data
+
+**payload.base64** (`string`): Base64 encoded data if applicable
+
+**payload.mimeType** (`string`): MIME type of the file
+
+**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata
+
 ## Control chunks
 
+### custom
+
+Contains a provider-specific content block that doesn't map to any other standardized chunk type. Emitted by providers on the AI SDK v7 specification.
+
+**type** (`"custom"`): Chunk type identifier
+
+**payload** (`CustomPayload`): Custom provider content
+
+**payload.kind** (`string`): The kind of custom content, in the format {provider}.{provider-type}
+
+**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata
+
 ### start
 
 Signals the start of streaming.
@@ -324,7 +352,7 @@ Signals the completion of a processing step.
 
 ### raw
 
-Contains raw data from the provider.
+Contains raw data from the provider. Content types Mastra doesn't recognize are also emitted as `raw` chunks rather than being discarded. Raw chunks only appear when `includeRawChunks` is enabled.
 
 **type** (`"raw"`): Chunk type identifier
 

package/.docs/reference/streaming/agents/stream.md

@@ -82,7 +82,7 @@ const stream = await agent.stream('message for agent')
 
 **options.onAbort** (`(event: { steps: any[]; text?: string }) => Promise<void> | void`): Callback function called when the stream is aborted. steps contains the steps that completed before the abort, and text contains the assistant text streamed so far for the step that was in flight.
 
-**options.abortSignal** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated, including any in-flight subagent runs the agent delegated to.
+**options.abortSignal** (`AbortSignal`): Signal object that allows you to abort the agent's execution, including in-flight subagent runs. Canceled runs continue through output processors. When writable memory is configured, built-in memory processors persist submitted messages, completed tool results, and assistant output available when terminal processing runs. Output that doesn't reach terminal processing isn't persisted. Custom output processors can transform or interrupt this behavior before memory processors run.
 
 **options.activeTools** (`Array<keyof ToolSet> | undefined`): Array of active tool names that can be used during execution.
 
@@ -180,8 +180,6 @@ const stream = await agent.stream('message for agent')
 
 **options.savePerStep** (`boolean`): Save messages incrementally after each stream step completes (default: false).
 
-**options.persistPartialOnAbort** (`boolean`): Save the assistant text that was streamed before an abort to memory (default: false). Only text emitted before the abort is persisted; output a provider keeps producing after cancellation is discarded, and nothing is saved when no text was streamed.
-
 **options.requireToolApproval** (`boolean`): When true, all tool calls require explicit approval before execution. The stream will emit tool-call-approval chunks and pause until approveToolCall() or declineToolCall() is called.
 
 **options.autoResumeSuspendedTools** (`boolean`): When true, automatically resumes suspended tools when the user sends a new message on the same thread. The agent extracts resumeData from the user's message based on the tool's resumeSchema. Requires memory to be configured.

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

@@ -232,15 +232,17 @@ Retrieves all tools from all configured servers, with tool names namespaced by t
 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, durations } = await mcp.listToolsWithErrors({
+const { tools, errors, errorDetails, durations } = await mcp.listToolsWithErrors({
   perServerTimeoutMs: 3_000,
 })
 
 new Agent({ id: 'agent', tools })
-console.log(errors, durations)
+console.log(errors, errorDetails, durations)
 ```
 
-When called without options, the method returns only `tools` and `errors`.
+`errors` remains a string map for backward compatibility. `errorDetails` provides the same message plus machine-readable `httpStatus` and transport `code` fields when the underlying error exposes them. When an HTTP status is available, the legacy message also includes an `(HTTP nnn)` suffix.
+
+When called without options, the method omits only `durations`; `tools`, `errors`, and `errorDetails` are always returned.
 
 ### `listToolsets()`
 
@@ -257,15 +259,15 @@ const res = await agent.stream(prompt, {
 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({
+const { toolsets, errors, errorDetails, durations } = await mcp.listToolsetsWithErrors({
   perServerTimeoutMs: 3_000,
 })
 
 const res = await agent.stream(prompt, { toolsets })
-console.log(errors, durations)
+console.log(errors, errorDetails, durations)
 ```
 
-When called without options, the method returns only `toolsets` and `errors`.
+When called without options, the method omits only `durations`; `toolsets`, `errors`, and `errorDetails` are always returned.
 
 ### `listToolDefinitions()`
 
@@ -286,7 +288,7 @@ Like `listToolDefinitions()`, but also returns per-server errors for servers tha
 Set `perServerTimeoutMs` to limit each server independently. When options are provided, `durations` reports each server's discovery time in milliseconds.
 
 ```typescript
-const { definitions, errors, durations } = await mcp.listToolDefinitionsWithErrors({
+const { definitions, errors, errorDetails, durations } = await mcp.listToolDefinitionsWithErrors({
   perServerTimeoutMs: 3_000,
 })
 
@@ -294,10 +296,10 @@ if (Object.keys(errors).length === 0) {
   await cache.set('mcp-tools', JSON.stringify(definitions))
 }
 
-console.log(durations)
+console.log(errorDetails, durations)
 ```
 
-When called without options, the method returns only `definitions` and `errors`.
+When called without options, the method omits only `durations`; `definitions`, `errors`, and `errorDetails` are always returned.
 
 ### `toolFromDefinition()`
 
@@ -441,6 +443,18 @@ for (const serverName in resourcesByServer) {
 }
 ```
 
+#### `resources.listWithErrors(options?)`
+
+Preserves successful resources while reporting failed servers through legacy string `errors` and structured `errorDetails`. Pass `perServerTimeoutMs` to bound each server independently and include `durations`.
+
+```typescript
+const { resources, errors, errorDetails, durations } = await mcpClient.resources.listWithErrors({
+  perServerTimeoutMs: 3_000,
+})
+
+console.log(resources, errors, errorDetails, durations)
+```
+
 #### `resources.templates()`
 
 Retrieves all available resource templates from all connected MCP servers, grouped by server name.
@@ -458,6 +472,15 @@ for (const serverName in templatesByServer) {
 }
 ```
 
+#### `resources.templatesWithErrors(options?)`
+
+Returns successful resource templates together with per-server string `errors`, structured `errorDetails`, and optional `durations`.
+
+```typescript
+const { templates, errors, errorDetails } = await mcpClient.resources.templatesWithErrors()
+console.log(templates, errors, errorDetails)
+```
+
 #### `resources.read(serverName: string, uri: string)`
 
 Reads the content of a specific resource from a server.
@@ -711,6 +734,15 @@ for (const serverName in promptsByServer) {
 }
 ```
 
+#### `prompts.listWithErrors(options?)`
+
+Returns successful prompts together with per-server string `errors`, structured `errorDetails`, and optional `durations`.
+
+```typescript
+const { prompts, errors, errorDetails } = await mcpClient.prompts.listWithErrors()
+console.log(prompts, errors, errorDetails)
+```
+
 #### `prompts.get({ serverName, name, args?, version? })`
 
 Retrieves a specific prompt and its messages from a server.