@mastra/server 1.81.0-alpha.1 → 1.81.0-alpha.2

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-server
 description: Documentation for @mastra/server. Use when working with @mastra/server APIs, configuration, or implementation.
 metadata:
   package: "@mastra/server"
-  version: "1.81.0-alpha.1"
+  version: "1.81.0-alpha.2"
 ---
 
 ## When to use
@@ -24,7 +24,7 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Reference
 
-- [Reference: Advanced trace queries](references/reference-observability-tracing-advanced-queries.md) - Find, count, and measure completed traces and spans with structured predicates. List matching traces, aggregate traces or spans into grouped measures, paginate, poll, and discover query fields.
+- [Reference: Query traces and spans](references/reference-observability-tracing-advanced-queries.md) - Find, count, and measure completed traces and spans with structured predicates. List matching traces or spans, aggregate them into grouped measures, paginate, poll, and discover query fields.
 - [Reference: createRoute()](references/reference-server-create-route.md) - Use createRoute() to define type-safe Mastra server routes with Zod validation for requests and responses, plus handler context and OpenAPI metadata.
 - [Reference: MastraServer](references/reference-server-mastra-server.md) - The MastraServer abstract class is the base for all server adapters. Extend this class to create adapters for frameworks other than Hono or Express.
 - [Reference: Server routes](references/reference-server-routes.md) - Server adapters register these routes when you call server.init(). All routes are prefixed with the prefix option if configured.

package/dist/docs/assets/SOURCE_MAP.json

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

package/dist/docs/references/reference-observability-tracing-advanced-queries.md

@@ -2,43 +2,57 @@
 
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Advanced trace queries
+# Query traces and spans
 
-Advanced trace queries select completed traces with a structured time range and predicate, then either list or aggregate the matching traces:
+Query completed traces or spans with structured filters, or aggregate them into counts, error rates, latency percentiles, tokens, and cost. Each operation is available through the client SDK, HTTP API, and CLI:
 
-| API              | Use it to                                                                                                                                                 | Client SDK          | HTTP endpoint                              |
-| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------ |
-| Query traces     | List matching traces, paginate through them, and poll for new ones.                                                                                       | `queryTraces()`     | `POST /api/observability/traces/query`     |
-| Aggregate traces | Count matching traces and compute measures, such as error rate, latency percentiles, tokens, and cost, optionally grouped by dimensions and time buckets. | `aggregateTraces()` | `POST /api/observability/traces/aggregate` |
-| Aggregate spans  | Compute the same measures over individual spans, such as every agent run including nested ones, grouped by span dimensions.                               | `aggregateSpans()`  | `POST /api/observability/spans/aggregate`  |
+| Operation                             | Use it to                                                                        | Client SDK          | HTTP endpoint                              | CLI command                  |
+| ------------------------------------- | -------------------------------------------------------------------------------- | ------------------- | ------------------------------------------ | ---------------------------- |
+| [Query traces](#query-traces)         | List traces matching root-span fields or conditions on related spans.            | `queryTraces()`     | `POST /api/observability/traces/query`     | `mastra api trace query`     |
+| [Query spans](#query-spans)           | List individual spans across traces, including nested agent runs and tool calls. | `querySpans()`      | `POST /api/observability/spans/query`      | `mastra api span query`      |
+| [Aggregate traces](#aggregate-traces) | Compute measures over matching traces, optionally grouped or bucketed by time.   | `aggregateTraces()` | `POST /api/observability/traces/aggregate` | `mastra api trace aggregate` |
+| [Aggregate spans](#aggregate-spans)   | Compute measures over individual matching spans at any depth.                    | `aggregateSpans()`  | `POST /api/observability/spans/aggregate`  | `mastra api span aggregate`  |
 
-The trace APIs accept the same [trace selection](#select-traces). The filters, operators, and limits on this page apply to each. Use the aggregate API to find the group that needs attention, such as an agent with a high error rate, then send the same predicate plus the group's dimensions to the query API to list the traces behind it. Each query result represents a trace. Use its `traceId` to [retrieve the full trace](https://mastra.ai/reference/client-js/observability).
+The trace operations share a [trace selection](#select-traces): root-span predicates and `spans.some` / `spans.none` clauses. The span operations share a direct span predicate, without nested `spans` clauses. Reuse a selection between the query and aggregate operations for the same record type.
+
+| Option                      | Query traces                             | Query spans    | Aggregate traces or spans             |
+| --------------------------- | ---------------------------------------- | -------------- | ------------------------------------- |
+| Maximum time-range duration | No maximum                               | No maximum     | 365 days                              |
+| Pagination                  | Keyset, numbered pages, or delta polling | Keyset only    | No pagination; `limit` selects groups |
+| `orderBy` shape             | One-item array                           | One-item array | One object                            |
+
+CLI commands take filters and request options together as one JSON argument and wrap the response in `data`. To inspect a query result, use its `traceId` to [retrieve the full trace](https://mastra.ai/reference/client-js/observability), or call `getSpan(traceId, spanId)` to retrieve one span.
 
 The endpoints use the same authentication as other observability routes and require the `observability:read` permission. Every request requires a time range.
 
-For hosted traces, see [Query observability data on Mastra Platform](https://mastra.ai/docs/mastra-platform/observability) for project credentials and regional endpoints.
+These API time-range limits are separate from data retention. For hosted traces, your Platform plan's retention period applies. See [Query observability data on Mastra Platform](https://mastra.ai/docs/mastra-platform/observability) for retention, project credentials, and regional endpoints.
 
 ## Check capabilities
 
 The configured observability store must support each API. Call `getObservabilityCapabilities()` or `GET /api/observability/capabilities` and check these flags before showing a feature:
 
-| Capability                       | Store feature                          | Enables                                                                                |
-| -------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------- |
-| `traceQuery`                     | `trace-query`                          | `queryTraces()`                                                                        |
-| `traceAggregate`                 | `trace-aggregate`                      | `aggregateTraces()`                                                                    |
-| `spanAggregate`                  | `span-aggregate`                       | `aggregateSpans()`                                                                     |
-| `traceQueryRootDuration`         | `trace-query-root-duration`            | Trace-scope `durationMs` predicates                                                    |
-| `traceQueryTimeToFirstChunk`     | `trace-query-time-to-first-chunk`      | `timeToFirstChunkMs` predicates and results                                            |
-| `traceQueryTimeToFirstChunkSort` | `trace-query-time-to-first-chunk-sort` | `orderBy` on `timeToFirstChunkMs`                                                      |
-| `traceQueryTimeToFirstToken`     | `trace-query-time-to-first-token`      | `timeToFirstTokenMs` predicates and results                                            |
-| `traceQueryTimeToFirstTokenSort` | `trace-query-time-to-first-token-sort` | `orderBy` on `timeToFirstTokenMs`                                                      |
-| `traceQueryContextIds`           | `trace-query-context-ids`              | `runId`, `sessionId`, `userId`, and `organizationId` predicates                        |
-| `traceQueryRootSpanFields`       | `trace-query-root-span-fields`         | Trace-scope `name` and `spanType` predicates, dimensions, and `countDistinct` measures |
-| `traceQueryRootEntityId`         | `trace-query-root-entity-id`           | Trace-scope `entityId` predicates, dimensions, and `countDistinct` measures            |
-| `traceQueryDiscovery`            | `trace-query-discovery`                | [Field and value discovery](#discover-fields-and-values)                               |
-| `traceQueryTenantScope`          | `trace-query-tenant-scope`             | [Trusted tenant scope](#trusted-tenant-scope)                                          |
-
-A missing `traceAggregate` value means the server doesn't support aggregation. Servers without the aggregate route return `404`, and stores without the feature return `501 TRACE_AGGREGATE_UNSUPPORTED`. A missing `spanAggregate` value means the same for span aggregation, and stores without the feature return `501 SPAN_AGGREGATE_UNSUPPORTED`. Against a store without a sub-feature, a request that uses a gated field returns `501` before storage runs. Root span `name`, `spanType`, and `entityId` are the exception and return `422` with a `field_not_allowed` issue.
+| Capability                       | Store feature                          | Enables                                                                                                                                                                     |
+| -------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `traceQuery`                     | `trace-query`                          | `queryTraces()`                                                                                                                                                             |
+| `spanQuery`                      | `span-query`                           | `querySpans()`                                                                                                                                                              |
+| `spanQueryContextFields`         | `span-query-context-fields`            | Additional identity, context, and parent/root entity predicates in span queries and aggregates                                                                              |
+| `spanQueryModelFields`           | `span-query-model-fields`              | `model` and `provider` predicates in span queries and aggregates                                                                                                            |
+| `traceAggregate`                 | `trace-aggregate`                      | `aggregateTraces()`                                                                                                                                                         |
+| `spanAggregate`                  | `span-aggregate`                       | `aggregateSpans()`                                                                                                                                                          |
+| `traceQueryRootDuration`         | `trace-query-root-duration`            | Trace-scope `durationMs` predicates                                                                                                                                         |
+| `traceQueryTimeToFirstChunk`     | `trace-query-time-to-first-chunk`      | `timeToFirstChunkMs` predicates and results                                                                                                                                 |
+| `traceQueryTimeToFirstChunkSort` | `trace-query-time-to-first-chunk-sort` | `orderBy` on `timeToFirstChunkMs`                                                                                                                                           |
+| `traceQueryTimeToFirstToken`     | `trace-query-time-to-first-token`      | `timeToFirstTokenMs` predicates and results                                                                                                                                 |
+| `traceQueryTimeToFirstTokenSort` | `trace-query-time-to-first-token-sort` | `orderBy` on `timeToFirstTokenMs`                                                                                                                                           |
+| `traceQueryContextIds`           | `trace-query-context-ids`              | `runId`, `sessionId`, `userId`, and `organizationId` predicates                                                                                                             |
+| `traceQueryRootSpanFields`       | `trace-query-root-span-fields`         | Trace-scope `name` and `spanType` predicates, dimensions, and `countDistinct` measures                                                                                      |
+| `traceQueryRootEntityId`         | `trace-query-root-entity-id`           | Trace-scope `entityId` predicates, dimensions, and `countDistinct` measures                                                                                                 |
+| `traceQueryOutcomeFields`        | `trace-query-outcome-fields`           | `outcome` and `stopReason` in trace and `spans.some` / `spans.none` predicates, trace dimensions, and value discovery, plus the root span's outcome fields on trace results |
+| `spanQueryOutcomeFields`         | `span-query-outcome-fields`            | `outcome` and `stopReason` in `querySpans()` and `aggregateSpans()` predicates, dimensions, and `countDistinct` measures, plus the outcome fields on span results           |
+| `traceQueryDiscovery`            | `trace-query-discovery`                | [Field and value discovery](#discover-fields-and-values)                                                                                                                    |
+| `traceQueryTenantScope`          | `trace-query-tenant-scope`             | [Trusted tenant scope](#trusted-tenant-scope)                                                                                                                               |
+
+A missing `traceAggregate` value means the server doesn't support aggregation. Servers without the aggregate route return `404`, and stores without the feature return `501 TRACE_AGGREGATE_UNSUPPORTED`. A missing `spanAggregate` value means the same for span aggregation, and stores without the feature return `501 SPAN_AGGREGATE_UNSUPPORTED`. Against a store without a sub-feature, a request that uses a gated field returns `501` before storage runs. Unsupported root span `name`, `spanType`, and `entityId`, and span predicates requiring `spanQueryContextFields`, return `422` with a `field_not_allowed` issue instead. A store without `spanQuery` returns `501 SPAN_QUERY_UNSUPPORTED`.
 
 ## Select traces
 
@@ -79,16 +93,16 @@ Span clauses examine the current root span and current child spans. The root `ti
 
 ### Fields and operators
 
-| Predicate context | Fields                                                                                                                                                                                                 | Operators                                                                  |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
-| Trace             | `traceId`, `threadId`, `resourceId`, `runId`, `sessionId`, `userId`, `organizationId`, `entityId`, `entityName`, `entityType`, `name`, `spanType`, `environment`, `status`                             | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
-| Trace metadata    | `metadata.<key>`                                                                                                                                                                                       | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
-| Trace             | `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`, `timeToFirstTokenMs`                                                                                                                       | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
-| Trace             | `tags`                                                                                                                                                                                                 | `includes`, `notIncludes`, `exists`, `notExists`                           |
-| Span              | `name`                                                                                                                                                                                                 | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`, `matches`, `notMatches`  |
-| Span              | `spanType`, `model`, `provider`, `status`, `entityType`, `entityId`, `entityName`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId`, `runId`, `sessionId`, `userId`, `organizationId` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
-| Span              | `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`, `timeToFirstTokenMs`                                                                                                                       | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
-| Span              | `error`                                                                                                                                                                                                | `exists`, `notExists`                                                      |
+| Predicate context | Fields                                                                                                                                                                                                                          | Operators                                                                  |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Trace             | `traceId`, `threadId`, `resourceId`, `runId`, `sessionId`, `userId`, `organizationId`, `entityId`, `entityName`, `entityType`, `name`, `spanType`, `environment`, `status`, `outcome`, `stopReason`                             | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| Trace metadata    | `metadata.<key>`                                                                                                                                                                                                                | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| Trace             | `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`, `timeToFirstTokenMs`                                                                                                                                                | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
+| Trace             | `tags`                                                                                                                                                                                                                          | `includes`, `notIncludes`, `exists`, `notExists`                           |
+| Span              | `name`                                                                                                                                                                                                                          | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`, `matches`, `notMatches`  |
+| Span              | `spanType`, `model`, `provider`, `status`, `outcome`, `stopReason`, `entityType`, `entityId`, `entityName`, `entityVersionId`, `parentEntityVersionId`, `rootEntityVersionId`, `runId`, `sessionId`, `userId`, `organizationId` | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| Span              | `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`, `timeToFirstTokenMs`                                                                                                                                                | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
+| Span              | `error`                                                                                                                                                                                                                         | `exists`, `notExists`                                                      |
 
 Trace-scope `name`, `spanType`, and `entityId` read the current root span, so `{ op: 'eq', left: { path: 'spanType' }, right: { literal: 'workflow_run' } }` selects traces started by a workflow run. Inside `spans.some` or `spans.none`, the same fields match any span in the trace.
 
@@ -156,6 +170,26 @@ const slowFirstToken = { op: 'gt', left: { path: 'timeToFirstTokenMs' }, right:
 
 Stores advertise support through the `trace-query-time-to-first-token` feature and the sort through the `trace-query-time-to-first-token-sort` feature. The server reports them as the `traceQueryTimeToFirstToken` and `traceQueryTimeToFirstTokenSort` capabilities. Against an older store, results omit the field, and a predicate or sort on it returns `501` before storage runs.
 
+#### Filter by outcome
+
+`outcome` records how a span ended, for example `success`, `error`, `abort`, `limit`, or `unknown`. `stopReason` records why, for example `max_steps`. Both are free strings, so custom spans can record their own values. They're separate from `status`, which still reads only whether the span recorded an error.
+
+At trace scope, both fields read the current root span, the span with no parent that started the trace. Inside `spans.some` or `spans.none`, they read each related span. A trace whose root succeeded but whose tool call hit a step limit doesn't match a trace-scope `outcome` of `limit`. Find it through `spans.some`:
+
+```typescript
+const hitALimit = {
+  spans: {
+    some: { op: 'eq', left: { path: 'outcome' }, right: { literal: 'limit' } },
+  },
+}
+```
+
+Spans written by an SDK that predates these fields, or a root span that's still running, have no outcome. A missing outcome means "not recorded", never success. Select those spans with `{ op: 'notExists', path: 'outcome' }`. As with other optional string fields, `ne` and `notIn` match spans with no value.
+
+Both fields support `eq`, `ne`, `in`, `notIn`, `exists`, and `notExists`, group trace and span aggregates, and return values from value discovery. They can't sort individual trace or span query results. In aggregates, either field can be used in `orderBy` when it's included in `groupBy`. Results also return `stopReasonContext`, an object with details about the stop reason such as `{ maxSteps: 5 }`. `stopReasonContext` is returned only and can't be filtered, grouped, or sorted.
+
+Stores advertise support through the `trace-query-outcome-fields` feature for trace queries and aggregates, and the `span-query-outcome-fields` feature for span queries and aggregates. The server reports them as the `traceQueryOutcomeFields` and `spanQueryOutcomeFields` capabilities. Against an older store, results omit the fields, and a request that uses them returns `501` before storage runs.
+
 #### Filter by context identifiers
 
 `runId`, `sessionId`, `userId`, and `organizationId` are available at trace scope and inside `spans.some` / `spans.none`. Trace-scope predicates read the current root span. Span-scope predicates bind to one related current span, so a run recorded only on a child span is found through `spans.some`:
@@ -219,7 +253,7 @@ const slowModelCalls = {
 }
 ```
 
-`model` and `provider` read the canonical `attributes.model` and `attributes.provider` span attributes. Only stored string values are queryable; missing, null, and non-string values count as missing.
+`model` and `provider` read the span's `model` and `provider` columns. When a column is empty, they fall back to the string `attributes.model` and `attributes.provider` values that older `@mastra/observability` versions exported, so existing filters keep matching older spans. Trace results omit `model` and `provider`, because a trace can match through one span while its other spans used a different model.
 
 ```typescript
 const selectedModel = {
@@ -486,6 +520,14 @@ A query using keyset pagination returns lightweight completed traces and a curso
     {
       "traceId": "trace-123",
       "rootSpanId": "span-123",
+      "name": "agent run: support-agent",
+      "entityId": "support-agent",
+      "parentSpanId": null,
+      "createdAt": "2026-08-03T10:00:00.000Z",
+      "metadata": null,
+      "inputPreview": "Where is my order?",
+      "outputPreview": "Your order arrives tomorrow.",
+      "errorPreview": null,
       "threadId": "thread-123",
       "resourceId": "resource-123",
       "startedAt": "2026-08-03T10:00:00.000Z",
@@ -495,14 +537,19 @@ A query using keyset pagination returns lightweight completed traces and a curso
       "environment": "production",
       "status": "success",
       "timeToFirstChunkMs": 412,
-      "timeToFirstTokenMs": 380
+      "timeToFirstTokenMs": 380,
+      "outcome": "success",
+      "stopReason": null,
+      "stopReasonContext": null
     }
   ],
   "page": { "next": null }
 }
 ```
 
-`timeToFirstChunkMs` and `timeToFirstTokenMs` are present only when the configured store supports them. See [Filter by time to first chunk](#filter-by-time-to-first-chunk) and [Filter and sort by time to first token](#filter-and-sort-by-time-to-first-token).
+The response includes `name`, `createdAt`, identity fields, `metadata`, and input/output/error previews. Supported nullable fields remain present with `null` when no value was recorded. Fields that require an optional store feature are omitted when the store lacks that feature. Previews summarize payloads; retrieve the full trace for complete input, output, and error details.
+
+`timeToFirstChunkMs` and `timeToFirstTokenMs` are present only when the configured store supports them. See [Filter by time to first chunk](#filter-by-time-to-first-chunk) and [Filter and sort by time to first token](#filter-and-sort-by-time-to-first-token). `outcome`, `stopReason`, and `stopReasonContext` read the root span and are present only when the store supports the `traceQueryOutcomeFields` capability. They're `null` when the root span didn't record them. See [Filter by outcome](#filter-by-outcome).
 
 The response doesn't include the related spans that matched the predicate. Use [`getTrace()`](https://mastra.ai/reference/client-js/observability) to load the full trace after selecting a result.
 
@@ -599,7 +646,7 @@ Numbered-page handoff cursors and delta cursors also bind the authorization stat
 
 Cursor pagination is deterministic, but it isn't a database snapshot. Traces or replacement signals written between page requests can change later pages.
 
-PostgreSQL and ClickHouse stop trace queries after 15 seconds by default and return `504` when the database timeout is exceeded. Set `traceQueryTimeoutMs` in the store's vNext observability configuration to an integer from 1 through 300,000 milliseconds to change the timeout. DuckDB doesn't currently provide query-scoped timeout or cancellation through its driver wrapper, so this `504` guarantee doesn't apply to DuckDB.
+PostgreSQL and ClickHouse stop trace queries after 15 seconds by default and return `504` when the database timeout is exceeded. Set `observability.traceQueryTimeoutMs` on `PostgresStoreVNext`, or `observability.traceQuery.timeoutMs` on `ClickhouseStoreVNext`, to an integer from 1 through 300,000 milliseconds to change the timeout. DuckDB doesn't currently provide query-scoped timeout or cancellation through its driver wrapper, so this `504` guarantee doesn't apply to DuckDB.
 
 | Status | Meaning                                                                                                                                                                                                                                                  |
 | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -611,6 +658,73 @@ PostgreSQL and ClickHouse stop trace queries after 15 seconds by default and ret
 | `503`  | Discovery exceeded a backend memory or resource budget and returned `TRACE_QUERY_RESOURCE_LIMIT`.                                                                                                                                                        |
 | `504`  | A PostgreSQL or ClickHouse query exceeded its configured database execution timeout. Discovery returns `TRACE_QUERY_EXECUTION_TIMEOUT`.                                                                                                                  |
 
+## Query spans
+
+Use `querySpans()`, `mastra api span query`, or `POST /api/observability/spans/query` to return completed span summaries across traces. It requires a positive ISO timestamp range over span start time and supports cursor pagination. This example finds tool calls that took at least one second:
+
+```typescript
+const result = await mastraClient.querySpans({
+  timeRange: {
+    from: '2026-10-01T00:00:00.000Z',
+    to: '2026-10-02T00:00:00.000Z',
+  },
+  where: {
+    op: 'and',
+    args: [
+      { op: 'eq', left: { path: 'spanType' }, right: { literal: 'tool_call' } },
+      { op: 'gte', left: { path: 'durationMs' }, right: { literal: 1000 } },
+    ],
+  },
+  orderBy: [{ field: 'startedAt', direction: 'desc' }],
+  page: { limit: 100 },
+})
+
+// Pass result.page.next as page.after to continue with the same filters and ordering.
+console.log(result.spans)
+```
+
+Pages default to 100 rows and allow at most 1,000. The response is `{ spans, page: { next } }`, without a total count. Ordering accepts exactly one of `startedAt`, `endedAt`, `timeToFirstChunkMs`, or `timeToFirstTokenMs`, ascending or descending, and defaults to descending start time. Spans without a value for the `timeToFirstChunkMs` or `timeToFirstTokenMs` sort field sort last in both directions.
+
+| Fields                                                                                                                                       | Operators                                                                                                  |
+| -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `traceId`, `spanId`, `parentSpanId`, `threadId`                                                                                              | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                                                           |
+| `organizationId`, `resourceId`, `runId`, `sessionId`, `userId`, `requestId`, `serviceName`, `experimentId`, `environment`, `executionSource` | Same string operators                                                                                      |
+| Entity, parent entity and root entity `Type`, `Id`, `Name`, `VersionId` fields, such as `parentEntityId`                                     | Same string operators                                                                                      |
+| `name`, `spanType`, `status`                                                                                                                 | Same string operators; `name` also accepts `matches` / `notMatches` for normalized whole words and phrases |
+| `model`, `provider`, `outcome`, `stopReason`                                                                                                 | Same string operators                                                                                      |
+| `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`, `timeToFirstTokenMs`                                                             | Comparisons, membership and presence                                                                       |
+| `error`                                                                                                                                      | `exists`, `notExists`                                                                                      |
+
+Combine predicates with `and`, `or` and `not`. Membership uses `{ op: 'in', value: { path: 'spanType' }, set: ['agent_run', 'tool_call'] }`. A span's status is `error` when it has an error and `success` otherwise.
+
+Each summary includes identity, context, entity lineage, status, timestamps, `durationMs`, model/provider and input/output/error previews.
+
+Check `capabilities.spanQueryContextFields` from `getObservabilityCapabilities()` before filtering on `traceId`, `spanId`, `parentSpanId`, `threadId`, `resourceId`, `requestId`, `serviceName`, `experimentId`, `environment`, `executionSource`, or the parent/root entity `Type`, `Id`, and `Name` fields. If this capability is missing or false, requests using these filters return a structured `422` error. It doesn't gate `runId`, `sessionId`, `userId`, `organizationId`, or entity `VersionId` filters.
+
+Check `capabilities.spanQueryModelFields` before filtering on `model` or `provider`. These filters read only the span's `model` and `provider` columns. `@mastra/observability` fills the columns only when a span has both a `model` and a `provider`, and versions before it filled them left them empty. Filters treat empty columns as missing, so `eq`, `in` and `exists` don't match those spans while `ne`, `notIn` and `notExists` do. Results still return `model` and `provider` for them from the span's attributes. Trace query `spans.some` filters fall back to the attributes and do match those spans. With an older adapter, requests using these filters return `501`.
+
+Check `capabilities.spanQueryOutcomeFields` before filtering or grouping spans by `outcome` and `stopReason`. Rows then also include `outcome`, `stopReason` and `stopReasonContext`. These record how the span ended, separately from `status`, and are `null` when the span didn't record them. A missing outcome means "not recorded", not success. `stopReasonContext` can't be used in filters and is omitted when the store lacks `span-query-outcome-fields`. For traces, `capabilities.traceQueryOutcomeFields` enables the same fields on `queryTraces()` and `aggregateTraces()`, where they read the root span. With an older adapter, requests using these fields return `501`:
+
+```typescript
+const { capabilities } = await mastraClient.getObservabilityCapabilities()
+
+if (capabilities.spanQueryOutcomeFields) {
+  const limited = await mastraClient.querySpans({
+    timeRange: { from: '2026-10-01T00:00:00.000Z', to: '2026-10-02T00:00:00.000Z' },
+    where: { op: 'eq', left: { path: 'outcome' }, right: { literal: 'limit' } },
+  })
+  console.log(limited.spans.map(span => [span.stopReason, span.stopReasonContext]))
+}
+```
+
+See [Filter by outcome](https://mastra.ai/reference/observability/tracing/advanced-queries) for trace-scope and `spans.some` semantics.
+
+DuckDB returns `null` for parent/root entity type, ID and name on spans written before `@mastra/duckdb` stored them. Equality filters on these fields don't match those spans.
+
+The CLI returns the same response under `data`: read `data.spans` and pass `data.page.next` as `page.after`. Span queries support only keyset pagination, so reuse the same time range, predicate, and ordering when following the cursor. A malformed cursor returns `400`, while a cursor that doesn't match the query or scope returns `409`.
+
+Use `mastra api trace span <traceId> <spanId>` or `getSpan(traceId, spanId)` to retrieve a selected span's full details.
+
 ## Aggregate traces
 
 Use `aggregateTraces()` or `POST /api/observability/traces/aggregate` to count the selected traces and compute measures over them. Add `groupBy` to split the result by up to two dimensions, and `interval` to split each group into time buckets. The response contains one row per group, or one row per group and bucket.
@@ -667,16 +781,16 @@ curl --request POST \
 
 ### Aggregate request fields
 
-| Field       | Required | Description                                                                                                                                              |
-| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `timeRange` | Yes      | Trace start-time boundary, as in [Select traces](#select-traces). The range can span up to 365 days.                                                     |
-| `where`     | No       | Trace predicate, as in [Select traces](#select-traces).                                                                                                  |
-| `measures`  | Yes      | One or more distinct [measure names](#measures).                                                                                                         |
-| `groupBy`   | No       | Up to two distinct [dimensions](#dimensions). Defaults to `[]`, which returns one row for all selected traces.                                           |
-| `interval`  | No       | Bucket width: `'1m'`, `'5m'`, `'15m'`, `'1h'`, or `'1d'`. See [Time buckets](#time-buckets).                                                             |
-| `having`    | No       | Scalar predicate over measures that removes groups after grouping. See [Filter and order groups](#filter-and-order-groups).                              |
-| `orderBy`   | No       | `{ field, direction }`. `field` is a requested measure, `count`, or a `groupBy` dimension, and `direction` is `asc` or `desc`. Defaults to `count desc`. |
-| `limit`     | No       | Maximum number of groups. Defaults to 100 and has a maximum of 1,000.                                                                                    |
+| Field       | Required | Description                                                                                                                                                                                                      |
+| ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `timeRange` | Yes      | Trace start-time boundary, as in [Select traces](#select-traces). The range can span up to 365 days.                                                                                                             |
+| `where`     | No       | Trace predicate, as in [Select traces](#select-traces).                                                                                                                                                          |
+| `measures`  | Yes      | One or more distinct [measure names](#measures).                                                                                                                                                                 |
+| `groupBy`   | No       | Up to two distinct [dimensions](#dimensions). Defaults to `[]`, which treats all selected traces as one group. With `interval`, that group has one row per non-empty bucket. No matching traces returns no rows. |
+| `interval`  | No       | Bucket width: `'1m'`, `'5m'`, `'15m'`, `'1h'`, or `'1d'`. See [Time buckets](#time-buckets).                                                                                                                     |
+| `having`    | No       | Scalar predicate over measures that removes groups after grouping. See [Filter and order groups](#filter-and-order-groups).                                                                                      |
+| `orderBy`   | No       | `{ field, direction }`. `field` is a requested measure, `count`, or a `groupBy` dimension, and `direction` is `asc` or `desc`. Defaults to `count desc`.                                                         |
+| `limit`     | No       | Maximum number of groups. Defaults to 100 and has a maximum of 1,000.                                                                                                                                            |
 
 Unknown fields are rejected. Aggregation isn't paginated. Narrow the selection, or rank by a different measure, when `truncated` is `true`.
 
@@ -684,15 +798,16 @@ Unknown fields are rejected. Aggregation isn't paginated. Narrow the selection,
 
 Dimensions read the current root span of each selected trace:
 
-| Dimension                                                                             | Notes                                                                                                                                |
-| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `entityType`, `entityName`, `environment`, `status`, `serviceName`, `executionSource` | Root span attributes.                                                                                                                |
-| `threadId`, `resourceId`, `userId`, `sessionId`, `organizationId`, `experimentId`     | Context identifiers recorded on the root span.                                                                                       |
-| `name`, `spanType`                                                                    | Root span name and type. Requires the `traceQueryRootSpanFields` capability.                                                         |
-| `entityId`                                                                            | Root span entity ID. Groups traces that have no `entityName`, such as scorer runs. Requires the `traceQueryRootEntityId` capability. |
-| `metadata.<key>`                                                                      | One non-empty top-level metadata key. Values are trimmed. Missing, empty, and non-string values group as `null`.                     |
+| Dimension                                                                             | Notes                                                                                                                                             |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `entityType`, `entityName`, `environment`, `status`, `serviceName`, `executionSource` | Root span attributes.                                                                                                                             |
+| `threadId`, `resourceId`, `userId`, `sessionId`, `organizationId`, `experimentId`     | Context identifiers recorded on the root span.                                                                                                    |
+| `name`, `spanType`                                                                    | Root span name and type. Requires the `traceQueryRootSpanFields` capability.                                                                      |
+| `entityId`                                                                            | Root span entity ID. Groups traces that have no `entityName`, such as scorer runs. Requires the `traceQueryRootEntityId` capability.              |
+| `outcome`, `stopReason`                                                               | How the root span ended and why. Traces whose root span didn't record a value group as `null`. Requires the `traceQueryOutcomeFields` capability. |
+| `metadata.<key>`                                                                      | One non-empty top-level metadata key. Values are trimmed. Missing, empty, and non-string values group as `null`.                                  |
 
-Every dimension except `serviceName`, `executionSource`, and `experimentId` is also a trace-scope `where` field, so you can drill into a group by adding its values to the predicate. `traceId`, `spanId`, `runId`, and `requestId` aren't groupable. Traces with no value for a dimension form their own group with a `null` value.
+Every dimension except `serviceName`, `executionSource`, and `experimentId` is also a trace-scope `where` field, so you can drill into a group by adding its values to the predicate. `traceId`, `spanId`, `runId`, and `requestId` aren't groupable. Traces with no value for a dimension form their own group with a `null` value. To select that group in a query, use `notExists` for the dimension instead of `eq` with `literal: null`.
 
 ### Measures
 
@@ -812,21 +927,21 @@ const dailyCost = await mastraClient.aggregateTraces({
 
 Predicate limits from [Query limits](#query-limits) apply to both `where` and `having`, and the request body is limited to 256 KiB. A time range that doesn't start on a bucket boundary touches one more bucket than its length divided by the interval. If the range has too many buckets, choose a wider `interval`. If `limit` × buckets exceeds 10,000, reduce `limit` or widen the interval.
 
-PostgreSQL and ClickHouse stop aggregations after the same `traceQueryTimeoutMs` timeout as trace queries, which defaults to 15 seconds. The timeout doesn't apply to DuckDB.
+PostgreSQL and ClickHouse use the same [execution timeout](#keyset-ordering-and-errors) for aggregations as for trace queries, defaulting to 15 seconds. The timeout doesn't apply to DuckDB.
 
-| Status | Meaning                                                                                                                                                                                                                         |
-| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `400`  | Malformed JSON.                                                                                                                                                                                                                 |
-| `413`  | The request body exceeds 256 KiB.                                                                                                                                                                                               |
-| `422`  | The request is invalid and returns `TRACE_QUERY_INVALID` with issues. Issue codes include `time_range_too_large`, `too_many_buckets`, `too_many_rows`, `field_not_allowed`, `invalid_metadata_key`, and `operator_not_allowed`. |
-| `501`  | The installed Core or configured observability store doesn't support aggregation or a requested field. Returns `TRACE_AGGREGATE_UNSUPPORTED`.                                                                                   |
-| `504`  | A PostgreSQL or ClickHouse aggregation exceeded its execution timeout. Returns `TRACE_QUERY_EXECUTION_TIMEOUT` without partial results.                                                                                         |
+| Status | Meaning                                                                                                                                                                                                                                                                            |
+| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400`  | Malformed JSON.                                                                                                                                                                                                                                                                    |
+| `413`  | The request body exceeds 256 KiB.                                                                                                                                                                                                                                                  |
+| `422`  | The request is invalid and returns `TRACE_QUERY_INVALID` with issues. A time range exceeding 365 days produces an `invalid_request` issue. Other issue codes include `too_many_buckets`, `too_many_rows`, `field_not_allowed`, `invalid_metadata_key`, and `operator_not_allowed`. |
+| `501`  | The installed Core or configured observability store doesn't support aggregation or a requested field. Returns `TRACE_AGGREGATE_UNSUPPORTED`.                                                                                                                                      |
+| `504`  | A PostgreSQL or ClickHouse aggregation exceeded its execution timeout. Returns `TRACE_QUERY_EXECUTION_TIMEOUT` without partial results.                                                                                                                                            |
 
 ## Aggregate spans
 
 Use `aggregateSpans()` or `POST /api/observability/spans/aggregate` to compute measures over individual spans instead of traces. Trace aggregation only sees each trace's root span, so an agent run nested inside a workflow isn't counted. Span aggregation counts every span that matches, at any depth.
 
-The request has the same shape as [`aggregateTraces()`](#aggregate-request-fields), with the same measures, `having`, `orderBy`, `interval`, limits, and errors. The differences are in which records are selected and which dimensions are available.
+The request has the same shape as [`aggregateTraces()`](#aggregate-request-fields), with the same fixed measures, `having`, `orderBy`, `interval`, and shared limits. Its `where`, dimensions, and `countDistinct` fields follow the span contract below. Unsupported span aggregation returns `501 SPAN_AGGREGATE_UNSUPPORTED`.
 
 ### Aggregate spans with the client SDK
 
@@ -853,30 +968,36 @@ Send the same body to `POST /api/observability/spans/aggregate` to use HTTP dire
 
 ### Span selection
 
-Aggregation selects the spans that [`querySpans()`](https://mastra.ai/reference/client-js/observability) would return for the same `timeRange` and `where`:
+Aggregation uses the same span predicates as [`querySpans()`](#query-spans), with the ClickHouse selection differences described below:
 
 - `timeRange` bounds each span's `startedAt`, and can span up to 365 days.
-- `where` accepts the `querySpans()` fields and operators, such as `spanType`, `name`, `status`, `durationMs`, entity and parent/root entity fields, and context identifiers.
+- `where` accepts the `querySpans()` fields and operators, such as `spanType`, `name`, `status`, `durationMs`, `model`, `provider`, entity and parent/root entity fields, and context identifiers. Like `querySpans()`, `model` and `provider` filters read only the span's columns, not its attributes.
 - Only completed spans count. When a span was exported more than once, only its latest copy counts.
 
-`count` equals the number of spans `querySpans()` pages through for the same request. Buckets use each span's `startedAt`. `duration.*` measures read the span's own duration, and `errorCount` and `errorRate` read whether the span itself recorded an error.
+`count` counts selected spans in each group or time bucket. Buckets use each span's `startedAt`. `duration.*` measures read the span's own duration, and `errorCount` and `errorRate` read whether the span itself recorded an error.
 
-On ClickHouse, a request whose `where` limits `spanType` to agent, workflow, processor, or scorer runs, RAG ingestion, or tool calls reads the smaller branch table instead of every span. That path can differ from `querySpans()`:
+On ClickHouse, a direct `spanType` `eq` or `in` predicate, or one immediately inside an `and`, can select the smaller branch table. All selected types must be branch types: `agent_run`, `workflow_run`, `processor_run`, `scorer_run`, `rag_ingestion`, `tool_call`, or `mcp_tool_call`. Every requested field must be available in that table. An equivalent `or` predicate doesn't select this optimization. The branch path can differ from `querySpans()`:
 
 - Spans written before an upgrade from `@mastra/clickhouse` 1.4, 1.5, or 1.6 aren't in the branch table, so older windows can count fewer spans.
-- After ClickHouse merges the copies of a span exported more than once, the branch table keeps the copy written last, not the one that ended last. Counts don't change, but the `status` and duration of a retried span can.
+- After ClickHouse merges the copies of a span exported more than once, the branch table keeps the copy written last, not the one that ended last. The retained version's status and duration can differ. This can change filtered counts and group membership even though the span identity is unchanged.
 
 ### Span dimensions
 
-| Dimension                                                                         | Notes                                                                                                               |
-| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `name`, `spanType`, `status`                                                      | The span's own name, type, and status. `status` is `error` when the span recorded an error and `success` otherwise. |
-| `entityType`, `entityId`, `entityName`                                            | The entity that produced the span.                                                                                  |
-| `parentEntityType`, `parentEntityName`, `rootEntityType`, `rootEntityName`        | The calling entity and the trace's root entity, such as the agent that made a model call.                           |
-| `environment`, `serviceName`, `executionSource`                                   | Deployment attributes recorded on the span.                                                                         |
-| `threadId`, `resourceId`, `userId`, `sessionId`, `organizationId`, `experimentId` | Context identifiers recorded on the span.                                                                           |
+| Dimension                                                                         | Notes                                                                                                                                                                              |
+| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`, `spanType`, `status`                                                      | The span's own name, type, and status. `status` is `error` when the span recorded an error and `success` otherwise.                                                                |
+| `outcome`, `stopReason`                                                           | How the span ended and why. Spans without a recorded value group as `null`. Requires the `spanQueryOutcomeFields` capability.                                                      |
+| `entityType`, `entityId`, `entityName`                                            | The entity that produced the span.                                                                                                                                                 |
+| `parentEntityType`, `parentEntityName`, `rootEntityType`, `rootEntityName`        | The calling entity and the trace's root entity, such as the agent that made a model call.                                                                                          |
+| `environment`, `serviceName`, `executionSource`                                   | Deployment attributes recorded on the span.                                                                                                                                        |
+| `threadId`, `resourceId`, `userId`, `sessionId`, `organizationId`, `experimentId` | Context identifiers recorded on the span.                                                                                                                                          |
+| `model`, `provider`                                                               | The model and provider recorded on the span's `model` and `provider` columns, such as `claude-sonnet-5-5` and `anthropic`. Requires the `spanAggregateModelDimensions` capability. |
 
-`countDistinct.<field>` accepts these dimensions and `traceId`, so `countDistinct.traceId` counts the traces the selected spans belong to. Span aggregation can't group by `metadata.<key>`, identity fields such as `traceId`, `spanId`, or `runId`, or by model and provider.
+`countDistinct.<field>` accepts these dimensions and `traceId`, so `countDistinct.traceId` counts the traces the selected spans belong to. Span aggregation can't group by `metadata.<key>` or identity fields such as `traceId`, `spanId`, or `runId`.
+
+Like the `model` and `provider` filters, the `model` and `provider` dimensions read only the span's columns, not its attributes. Existing spans aren't backfilled, so spans exported before `@mastra/observability` filled the columns group under `null`, and `countDistinct.model` doesn't count them.
+
+Stores advertise support through the `span-aggregate-model-dimensions` feature, and the server reports it as the `spanAggregateModelDimensions` capability. Against an older store, a request that groups by `model` or `provider` or counts their distinct values returns `501` before storage runs.
 
 ### Span tokens and cost
 
@@ -897,9 +1018,28 @@ const tokensByAgent = await mastraClient.aggregateSpans({
 })
 ```
 
+To compare models instead, group the same spans by `model`:
+
+```typescript
+const { capabilities } = await mastraClient.getObservabilityCapabilities()
+
+if (capabilities.spanAggregateModelDimensions) {
+  const { rows } = await mastraClient.aggregateSpans({
+    timeRange: {
+      from: '2026-08-01T00:00:00.000Z',
+      to: '2026-08-08T00:00:00.000Z',
+    },
+    where: { op: 'eq', left: { path: 'spanType' }, right: { literal: 'model_generation' } },
+    groupBy: ['provider', 'model'],
+    measures: ['count', 'tokens.total.sum', 'cost.sum'],
+  })
+  // rows[0]: { dimensions: { provider: 'anthropic', model: 'claude-sonnet-5-5' }, measures: { ... } }
+}
+```
+
 ### List the spans behind a group
 
-Aggregation never returns span records. To inspect a group, send the same `timeRange` and `where` to `querySpans()`, and add the group's dimension values as `eq` conditions. For example, add `{ op: 'eq', left: { path: 'status' }, right: { literal: 'error' } }` to list the failed agent runs from the first example.
+Aggregation never returns span records. To inspect a group, send the same `timeRange` and `where` to `querySpans()`, and add non-null dimension values as `eq` conditions. For a null dimension, use `notExists`, such as `{ op: 'notExists', path: 'entityName' }`. `eq` with `literal: null` is rejected. For example, add `{ op: 'eq', left: { path: 'status' }, right: { literal: 'error' } }` to list the failed agent runs from the first example.
 
 ## Trusted tenant scope
 
@@ -1017,12 +1157,12 @@ Discovery returns string values only. Missing values, empty strings, and strings
 
 Value suggestions are available for these canonical fields:
 
-| Scope | Fields                                                                          |
-| ----- | ------------------------------------------------------------------------------- |
-| Trace | `entityName`, `entityType`, `name`, `spanType`, `environment`, `status`, `tags` |
-| Spans | `name`, `spanType`, `model`, `provider`, `status`, `entityType`, `entityName`   |
+| Scope | Fields                                                                                                   |
+| ----- | -------------------------------------------------------------------------------------------------------- |
+| Trace | `entityName`, `entityType`, `name`, `spanType`, `environment`, `status`, `outcome`, `stopReason`, `tags` |
+| Spans | `name`, `spanType`, `model`, `provider`, `status`, `outcome`, `stopReason`, `entityType`, `entityName`   |
 
-Each executable top-level string `metadata.<key>` field also supports value suggestions in the `trace` scope. Identifiers, timestamps, durations, time to first chunk, time to first token, errors, and version IDs don't. The fields response still includes canonical fields with `valueSuggestions: false`. The values endpoint rejects those paths with `422 TRACE_QUERY_INVALID`.
+`outcome` and `stopReason` suggestions require the `traceQueryOutcomeFields` capability. Each executable top-level string `metadata.<key>` field also supports value suggestions in the `trace` scope. Identifiers, timestamps, durations, time to first chunk, time to first token, errors, and version IDs don't. The fields response still includes canonical fields with `valueSuggestions: false`. The values endpoint rejects those paths with `422 TRACE_QUERY_INVALID`.
 
 Both discovery requests require a half-open time range. They use the same current-record semantics as `queryTraces()`: qualifying completed roots satisfy `from <= startedAt < to`, and related values come only from current records joined to those roots by `traceId`. Discovery doesn't accept or apply a draft `where` predicate.
 

package/dist/docs/references/reference-server-routes.md

@@ -704,20 +704,24 @@ How a supplied `id` is treated depends on the storage adapter. Some adapters ups
 
 ## MCP
 
-| Method | Path                                       | Description              |
-| ------ | ------------------------------------------ | ------------------------ |
-| `GET`  | `/api/mcp/v0/servers`                      | List MCP servers         |
-| `GET`  | `/api/mcp/v0/servers/:id`                  | Get server details       |
-| `GET`  | `/api/mcp/:serverId/tools`                 | List server tools        |
-| `GET`  | `/api/mcp/:serverId/tools/:toolId`         | Get tool details         |
-| `POST` | `/api/mcp/:serverId/tools/:toolId/execute` | Execute a tool           |
-| `GET`  | `/api/mcp/:serverId/resources`             | List server resources    |
-| `POST` | `/api/mcp/:serverId/resources/read`        | Read a resource          |
-| `ALL`  | `/api/mcp/:serverId/mcp`                   | MCP HTTP transport       |
-| `ALL`  | `/api/mcp/:serverId/sse`                   | Legacy MCP SSE transport |
-| `POST` | `/api/mcp/:serverId/messages`              | Legacy MCP SSE messages  |
-
-All MCP routes declare `requiresAuth: true`. Authentication is enforced only when `server.auth` is configured. Paths use the default `/api` prefix. The legacy SSE routes return `404` for MCP v2 servers.
+| Method | Path                                       | Description                                        |
+| ------ | ------------------------------------------ | -------------------------------------------------- |
+| `GET`  | `/api/mcp/v0/servers`                      | List MCP servers                                   |
+| `GET`  | `/api/mcp/v0/servers/:id`                  | Get server details                                 |
+| `GET`  | `/api/mcp/:serverId/tools`                 | List server tools                                  |
+| `GET`  | `/api/mcp/:serverId/tools/:toolId`         | Get tool details                                   |
+| `POST` | `/api/mcp/:serverId/tools/:toolId/execute` | Execute a tool                                     |
+| `GET`  | `/api/mcp/:serverId/resources`             | List server resources                              |
+| `POST` | `/api/mcp/:serverId/resources/read`        | Read a resource                                    |
+| `GET`  | `/api/mcp/:serverId/tasks`                 | List a server's recent MCP tasks (experimental)    |
+| `POST` | `/api/mcp/:serverId/tasks/find`            | Find an MCP task by its task id (experimental)     |
+| `POST` | `/api/mcp/:serverId/tasks/:taskKey/cancel` | Cancel an MCP task (experimental)                  |
+| `POST` | `/api/mcp/:serverId/tasks/:taskKey/input`  | Answer an MCP task's input requests (experimental) |
+| `ALL`  | `/api/mcp/:serverId/mcp`                   | MCP HTTP transport                                 |
+| `ALL`  | `/api/mcp/:serverId/sse`                   | Legacy MCP SSE transport                           |
+| `POST` | `/api/mcp/:serverId/messages`              | Legacy MCP SSE messages                            |
+
+All MCP routes declare `requiresAuth: true`. Authentication is enforced only when `server.auth` is configured. With an RBAC provider, listing and finding tasks need `mcp:read`. Cancelling and answering a task need `mcp:write`, since they act on a task another client started. Paths use the default `/api` prefix. The legacy SSE routes return `404` for MCP v2 servers.
 
 ## Responses API