@mastra/mcp-docs-server 1.2.27-alpha.22 → 1.2.27-alpha.24

package/.docs/reference/client-js/observability.md

@@ -89,6 +89,33 @@ const result = await mastraClient.queryTraces({
 })
 ```
 
+### Load a page and poll for traces
+
+`queryTraces()` supports keyset traversal with `page`, numbered pages with `pagination`, and delta polling with `mode: 'delta'`. Use one mode per request. To migrate from `listTracesLight()`, read `traces` instead of `spans` and retain the numbered page's `deltaCursor`:
+
+```typescript
+const timeRange = {
+  from: '2026-08-01T00:00:00.000Z',
+  to: '2026-08-08T00:00:00.000Z',
+}
+const initial = await mastraClient.queryTraces({
+  timeRange,
+  pagination: { page: 0, perPage: 100 },
+})
+if (!initial.deltaCursor) throw new Error('Delta polling is unavailable')
+
+const changes = await mastraClient.queryTraces({
+  timeRange,
+  mode: 'delta',
+  after: initial.deltaCursor,
+  limit: 100,
+})
+```
+
+Merge `changes.traces` by `traceId`, retain `changes.deltaCursor`, and continue while `changes.delta.hasMore` is `true`. Keep the same time range and predicate across polls. Only completed traces are returned; polling doesn't guarantee notifications for related-record updates, deletions, or traces that stop matching.
+
+See [Delta polling](https://mastra.ai/reference/observability/tracing/trace-query) for bootstrap behavior, cursor lifetime, retention, and a complete polling loop. `queryTraceThreads()` remains keyset-only.
+
 ### Discover trace-query fields and values
 
 `getTraceQueryFields()` returns canonical query fields and observed top-level string metadata fields for one predicate scope. The response includes each field's value kind, supported operators, and whether value suggestions are available.

package/.docs/reference/observability/tracing/interfaces.md

@@ -67,6 +67,7 @@ interface SpanTypeMap {
   CLIENT_TOOL_CALL: ClientToolCallAttributes
   PROVIDER_TOOL_CALL: ProviderToolCallAttributes
   MCP_TOOL_CALL: MCPToolCallAttributes
+  MCP_SERVER_REQUEST: MCPServerRequestAttributes
   PROCESSOR_RUN: ProcessorRunAttributes
   WORKFLOW_STEP: WorkflowStepAttributes
   WORKFLOW_CONDITIONAL: WorkflowConditionalAttributes
@@ -390,6 +391,9 @@ enum SpanType {
   /** MCP (Model Context Protocol) tool execution */
   MCP_TOOL_CALL = 'mcp_tool_call',
 
+  /** A request served by a Mastra MCPServer (the server side of an MCP edge) */
+  MCP_SERVER_REQUEST = 'mcp_server_request',
+
   /**
    * Processor execution. This is the default; a processor can declare a
    * different span type so its span names the subsystem it belongs to.
@@ -652,6 +656,35 @@ interface MCPToolCallAttributes {
 }
 ```
 
+### `MCPServerRequestAttributes`
+
+Attributes of a request served by a Mastra `MCPServer`.
+
+```typescript
+interface MCPServerRequestAttributes {
+  /** MCP method served, e.g. 'tools/call', 'resources/list', 'prompts/get' */
+  mcpMethod: string
+
+  /** Name or URI of the tool, prompt, or resource requested. Absent on list-style calls. */
+  targetName?: string
+
+  /** Configured MCPServer name */
+  mcpServer: string
+
+  /** Configured MCPServer version */
+  serverVersion?: string
+
+  /** Negotiated MCP protocol revision for this request */
+  mcpProtocolVersion?: string
+
+  /** Client implementation name, when the client reported one */
+  clientName?: string
+
+  /** Client implementation version, when the client reported one */
+  clientVersion?: string
+}
+```
+
 ### `ProcessorRunAttributes`
 
 Processor attributes.

package/.docs/reference/observability/tracing/trace-query.md

@@ -236,12 +236,16 @@ Both routes require `observability:read` and use the configured observability st
 
 ### Trace queries
 
-| Field       | Required | Description                                                                                                                                                                     |
-| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `timeRange` | Yes      | Trace start-time boundary. `from` is inclusive and `to` is exclusive. Both values must be ISO timestamps, `from` must be earlier than `to`, and the range can't exceed 31 days. |
-| `where`     | No       | Recursive trace predicate. Supports scalar conditions and `spans`, `scores`, and `feedback` `some` or `none` clauses.                                                           |
-| `orderBy`   | No       | One item ordering results by `startedAt` or `endedAt`, in `asc` or `desc` order. Defaults to `startedAt desc`.                                                                  |
-| `page`      | No       | `{ limit, after }`. `limit` defaults to 100 and has a maximum of 1000. Pass the opaque `page.next` value as `after`.                                                            |
+| Field        | Required | Description                                                                                                                                                                     |
+| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `timeRange`  | Yes      | Trace start-time boundary. `from` is inclusive and `to` is exclusive. Both values must be ISO timestamps, `from` must be earlier than `to`, and the range can't exceed 31 days. |
+| `where`      | No       | Recursive trace predicate. Supports scalar conditions and `spans`, `scores`, and `feedback` `some` or `none` clauses.                                                           |
+| `orderBy`    | No       | One item ordering results by `startedAt` or `endedAt`, in `asc` or `desc` order. Defaults to `startedAt desc`. Not accepted in delta mode.                                      |
+| `page`       | No       | `{ limit, after }`. `limit` defaults to 100 and has a maximum of 1000. Pass the opaque `page.next` value as `after`.                                                            |
+| `pagination` | No       | Numbered pages: `{ page, perPage }`. Defaults to page 0 and 10 results. `perPage` has a maximum of 100.                                                                         |
+| `mode`       | No       | Set to `'delta'` to poll using a delta cursor instead of `page` or `pagination`.                                                                                                |
+| `after`      | No       | Delta mode only. Opaque `deltaCursor` from a numbered page or previous poll. Omit to establish the current watermark.                                                           |
+| `limit`      | No       | Delta mode only. Maximum results per batch. Defaults to 10 and has a maximum of 100.                                                                                            |
 
 ### Thread queries
 
@@ -525,9 +529,75 @@ Related evidence isn't embedded in either response. Use the trace-detail and bra
 
 ## Pagination and errors
 
+### Choose a pagination mode
+
+Trace queries support three mutually exclusive modes:
+
+| Mode                | Request fields                                          | Response metadata                                                                                   |
+| ------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Keyset, the default | `page: { limit, after }`                                | `page: { next }`                                                                                    |
+| Numbered pages      | `pagination: { page, perPage }`                         | `pagination: { total, page, perPage, hasMore }` and, when delta polling is supported, `deltaCursor` |
+| Delta polling       | `mode: 'delta'`, optional top-level `after` and `limit` | `delta: { limit, hasMore }` and `deltaCursor`                                                       |
+
+Numbered pages are zero-based. Their total and rows are read consistently within each request. Don't combine `page`, `pagination`, or delta mode. Top-level `after` and `limit` are accepted only in delta mode. Thread queries and grouped compatibility queries remain keyset-only.
+
+### Poll after loading a numbered page
+
+Use the numbered response's `deltaCursor` to replace the numbered-page-to-delta-polling workflow of `listTracesLight()`. Results use `traces` instead of `spans` and contain completed traces only. The configured store must support delta polling.
+
+```typescript
+const timeRange = {
+  from: '2026-08-01T00:00:00.000Z',
+  to: '2026-08-08T00:00:00.000Z',
+}
+const initial = await mastraClient.queryTraces({
+  timeRange,
+  pagination: { page: 0, perPage: 100 },
+})
+if (!initial.deltaCursor) throw new Error('Delta polling is unavailable')
+
+const traces = new Map(initial.traces.map(trace => [trace.traceId, trace]))
+let after = initial.deltaCursor
+
+async function poll() {
+  let hasMore: boolean
+  do {
+    const result = await mastraClient.queryTraces({
+      timeRange,
+      mode: 'delta',
+      after,
+      limit: 100,
+    })
+    for (const trace of result.traces) traces.set(trace.traceId, trace)
+    after = result.deltaCursor
+    hasMore = result.delta.hasMore
+  } while (hasMore)
+}
+
+await poll()
+```
+
+Retain `after` and call `poll()` again at your application's polling interval. A trace can appear in the initial page and a later batch, or in multiple batches, so merge results by `traceId`. To load historical traces omitted from the initial page, request the remaining numbered pages.
+
+A delta request without `after` returns an empty array and establishes the current cursor. It doesn't return historical matches. Always retain the returned cursor, including for empty batches. `hasMore` means another matching trace exists beyond the batch limit. Continue immediately while it's `true`.
+
+Delta ordering uses the storage ingestion watermark and adapter-specific tie-breakers, so matching timestamps don't make the cursor ambiguous. Don't pass `orderBy` in delta mode. Keyset and delta cursors aren't interchangeable, and delta cursors can't move between storage adapters.
+
+Keep the same normalized `where` predicate and exact `timeRange` bounds for every poll. The range continues to select root `startedAt`, even when a trace completes later. Changing `timeRange.to` to the current time invalidates the cursor. Reload a numbered page and use its cursor whenever the selection or authorization scope changes. You can change the batch limit without restarting.
+
+New completed roots and roots completing after the cursor can be returned. Related spans, scores, and feedback are evaluated when a root is selected, but later related-record writes don't guarantee that the trace is emitted again. Deleted traces and traces that stop matching aren't returned as removals or tombstones. Refresh numbered pages when you need to reconcile those changes.
+
+ClickHouse polling is best effort. Its delta index and trace records use separate materialized-view tables. Concurrent queries can observe an insert in one table before another, as described in [ClickHouse's materialized-view visibility rules](https://github.com/ClickHouse/clickhouse-docs/blob/main/knowledgebase/are_materialized_views_inserted_asynchronously.mdx). A poll can advance past an index entry before the matching trace becomes visible and miss that trace in later polls. Reload numbered pages periodically to reconcile these gaps.
+
+ClickHouse's delta index retains two days of events and doesn't backfill historical rows. Reload numbered pages after a polling interruption longer than this retention window. Delta polling isn't a durable change feed and doesn't guarantee delivery of every matching trace.
+
+### Keyset ordering and errors
+
 Ordering is deterministic. Trace ordering appends `traceId` ascending as a tie-breaker. Thread queries always use raw ordinal `threadId` ascending order. Callers can't override it.
 
-Cursors are bound to the operation, accepted normalized query, authorization state, and ordering. Reusing a cursor after changing the trace selection, predicates, or ordering returns `409`. Trace and thread cursors aren't interchangeable. A malformed cursor returns `400`.
+Keyset cursors are bound to the operation, accepted normalized query, and ordering. Reusing a keyset cursor after changing the trace selection, predicates, or ordering returns `409`. Trace and thread cursors aren't interchangeable.
+
+Numbered-page handoff cursors and delta cursors also bind the authorization state. Changes to the caller's roles or permissions invalidate these cursors and return `409`. If a delta poll returns `409`, reload the numbered pages and resume polling with the new `deltaCursor`. A malformed cursor returns `400`.
 
 Cursor pagination is deterministic, but it isn't a database snapshot. Traces or replacement signals written between page requests can change later pages.
 
@@ -545,7 +615,7 @@ PostgreSQL and ClickHouse stop advanced trace and thread queries after 15 second
 
 ## Limitations
 
-Both operations consider completed traces only. They don't support running traces, custom projections, embedded evidence, summaries, aggregations, counts, measures, or custom grouping.
+Both operations consider completed traces only. They don't support running traces, custom projections, embedded evidence, summaries, aggregations, measures, or custom grouping. Numbered trace pages include a total count.
 
 ## Related
 

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

@@ -959,6 +959,14 @@ execute: async ({ items }, context) => {
 }
 ```
 
+## Tracing
+
+When the server is registered on a `Mastra` instance that has observability configured, every request it handles produces an `MCP_SERVER_REQUEST` root span: `tools/list`, `tools/call`, `resources/*`, and `prompts/*`. `executeTool()` produces the same span, so the Studio MCP server page is traced like an MCP client.
+
+The span is named after the method and target (for example `tools/call lookupOrder`). It stores the request params as input and the response as output, and records the server name and version, the negotiated protocol version, and the client name and version when the client reported them. A `tools/call` that returns `isError: true` fails the span. Agents and workflows exposed as tools attach their `AGENT_RUN` and `WORKFLOW_RUN` spans under it. A served tool doesn't get its own `TOOL_CALL` span. Tools an agent calls inside the request still do.
+
+A standalone `MCPServer` with no `mastra` instance produces no spans.
+
 ## Notification delivery
 
 Notification methods (`resources.notifyListChanged()`, `prompts.notifyListChanged()`, `toolActions.notifyListChanged()`, and `sendLoggingMessage()`) broadcast to every connected client across all transports: the stdio/SSE connection and each streamable HTTP session. `resources.notifyUpdated()` is the exception: it only notifies clients that subscribed to the resource URI via `resources/subscribe`. Subscriptions are tracked per session for streamable HTTP clients; legacy SSE clients share the main server instance and therefore share one subscription set. Clients using the stateless serverless mode can't receive notifications because each request uses a transient server instance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.27-alpha.22",
+  "version": "1.2.27-alpha.24",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "local-pkg": "^1.1.2",
     "zod": "^4.6.4",
-    "@mastra/core": "1.68.0-alpha.10"
+    "@mastra/core": "1.68.0-alpha.11"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -43,7 +43,7 @@
     "typescript": "^7.0.2",
     "vitest": "4.1.11",
     "@internal/lint": "0.0.133",
-    "@mastra/core": "1.68.0-alpha.10",
+    "@mastra/core": "1.68.0-alpha.11",
     "@internal/types-builder": "0.0.108"
   },
   "homepage": "https://mastra.ai",