@mastra/mcp-docs-server 1.2.27-alpha.22 → 1.2.27
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.docs/models/environment-variables.md +1 -0
- package/.docs/models/gateways/merge-gateway.md +2 -1
- package/.docs/models/gateways/netlify.md +2 -1
- package/.docs/models/gateways/openrouter.md +7 -2
- package/.docs/models/gateways/vercel.md +5 -1
- package/.docs/models/index.md +1 -1
- package/.docs/models/providers/alibaba-cn.md +3 -3
- package/.docs/models/providers/coralbricks.md +10 -10
- package/.docs/models/providers/deepinfra.md +1 -1
- package/.docs/models/providers/digitalocean.md +9 -9
- package/.docs/models/providers/edenai.md +8 -7
- package/.docs/models/providers/empiriolabs.md +6 -2
- package/.docs/models/providers/huggingface.md +2 -1
- package/.docs/models/providers/kilo.md +15 -10
- package/.docs/models/providers/llmgateway-providers.md +3 -1
- package/.docs/models/providers/llmgateway.md +3 -2
- package/.docs/models/providers/llmtech.md +7 -7
- package/.docs/models/providers/nano-gpt.md +2 -1
- package/.docs/models/providers/neuralwatt.md +25 -25
- package/.docs/models/providers/opencode-go.md +4 -1
- package/.docs/models/providers/opencode.md +2 -1
- package/.docs/models/providers/opper.md +63 -47
- package/.docs/models/providers/siliconflow-cn.md +1 -4
- package/.docs/models/providers/siliconflow.md +60 -52
- package/.docs/models/providers/stepfun-ai.md +2 -1
- package/.docs/models/providers/stepfun-step-plan.md +2 -1
- package/.docs/models/providers/tempr.md +105 -0
- package/.docs/models/providers/vivgrid.md +4 -2
- package/.docs/models/providers/wandb.md +2 -1
- package/.docs/models/providers/xai.md +3 -1
- package/.docs/models/providers/xiaomi-token-plan-ams.md +4 -2
- package/.docs/models/providers/xiaomi-token-plan-cn.md +4 -2
- package/.docs/models/providers/xiaomi-token-plan-sgp.md +4 -2
- package/.docs/models/providers/xiaomi.md +5 -2
- package/.docs/models/providers/zai.md +2 -1
- package/.docs/models/providers/zhipuai.md +2 -1
- package/.docs/models/providers.md +1 -0
- package/.docs/reference/cli/mastra.md +11 -0
- package/.docs/reference/client-js/observability.md +27 -0
- package/.docs/reference/observability/tracing/exporters/mastra-platform-exporter.md +10 -0
- package/.docs/reference/observability/tracing/interfaces.md +33 -0
- package/.docs/reference/observability/tracing/trace-query.md +78 -8
- package/.docs/reference/tools/mcp-server.md +8 -0
- package/package.json +5 -5
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Vivgrid
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 31 Vivgrid models through Mastra's model router. Authentication is handled automatically using the `VIVGRID_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [Vivgrid documentation](https://docs.vivgrid.com/models).
|
|
10
10
|
|
|
@@ -46,6 +46,7 @@ for await (const chunk of stream) {
|
|
|
46
46
|
| `vivgrid/deepseek-v4-flash` | 1.0M | | | | | | $0.15 | $0.30 |
|
|
47
47
|
| `vivgrid/deepseek-v4-pro` | 1.0M | | | | | | $0.43 | $0.87 |
|
|
48
48
|
| `vivgrid/deepseek-v4-pro-0813` | 1.0M | | | | | | $1 | $3 |
|
|
49
|
+
| `vivgrid/deepseek-v4.1-flash` | 1.0M | | | | | | $0.31 | $1 |
|
|
49
50
|
| `vivgrid/gemini-3.1-flash-lite-preview` | 1.0M | | | | | | $0.25 | $2 |
|
|
50
51
|
| `vivgrid/gemini-3.1-pro-preview` | 1.0M | | | | | | $2 | $12 |
|
|
51
52
|
| `vivgrid/gemini-3.7-flash` | 1.0M | | | | | | $0.75 | $4 |
|
|
@@ -67,6 +68,7 @@ for await (const chunk of stream) {
|
|
|
67
68
|
| `vivgrid/gpt-5.6-terra` | 1.1M | | | | | | $3 | $15 |
|
|
68
69
|
| `vivgrid/gpt-6-astra` | 1.1M | | | | | | $10 | $50 |
|
|
69
70
|
| `vivgrid/kimi-k3` | 1.0M | | | | | | $3 | $15 |
|
|
71
|
+
| `vivgrid/viv-fast` | 1.0M | | | | | | $0.13 | $0.40 |
|
|
70
72
|
|
|
71
73
|
Model availability, capabilities, context windows, and pricing are sourced from [models.dev](https://models.dev) and may change.
|
|
72
74
|
|
|
@@ -98,7 +100,7 @@ const agent = new Agent({
|
|
|
98
100
|
model: ({ requestContext }) => {
|
|
99
101
|
const useAdvanced = requestContext.task === "complex";
|
|
100
102
|
return useAdvanced
|
|
101
|
-
? "vivgrid/
|
|
103
|
+
? "vivgrid/viv-fast"
|
|
102
104
|
: "vivgrid/claude-fable-5";
|
|
103
105
|
}
|
|
104
106
|
});
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# CoreWeave
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 28 CoreWeave models through Mastra's model router. Authentication is handled automatically using the `WANDB_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [CoreWeave documentation](https://docs.wandb.ai).
|
|
10
10
|
|
|
@@ -43,6 +43,7 @@ for await (const chunk of stream) {
|
|
|
43
43
|
| `wandb/deepseek-ai/DeepSeek-V4-Flash-0731` | 262K | | | | | | $0.13 | $0.28 |
|
|
44
44
|
| `wandb/deepseek-ai/DeepSeek-V4-Pro` | 1.0M | | | | | | $1 | $3 |
|
|
45
45
|
| `wandb/deepseek-ai/DeepSeek-V4-Pro-0813` | 1.0M | | | | | | $1 | $4 |
|
|
46
|
+
| `wandb/deepseek-ai/DeepSeek-V4.1-Flash` | 1.0M | | | | | | $0.20 | $0.65 |
|
|
46
47
|
| `wandb/google/gemma-4-31B-it` | 262K | | | | | | $0.10 | $0.34 |
|
|
47
48
|
| `wandb/ibm-granite/granite-4.1-8b` | 131K | | | | | | $0.05 | $0.10 |
|
|
48
49
|
| `wandb/ibm-granite/granite-4.2-8b` | 131K | | | | | | $0.10 | $0.15 |
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# xAI
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 12 xAI models through Mastra's model router. Authentication is handled automatically using the `XAI_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [xAI documentation](https://docs.x.ai/docs/models).
|
|
10
10
|
|
|
@@ -42,8 +42,10 @@ for await (const chunk of stream) {
|
|
|
42
42
|
| `xai/grok-4.3` | 1.0M | | | | | | $1 | $3 |
|
|
43
43
|
| `xai/grok-4.5` | 500K | | | | | | $2 | $6 |
|
|
44
44
|
| `xai/grok-4.6` | 500K | | | | | | $2 | $6 |
|
|
45
|
+
| `xai/grok-4.7` | 500K | | | | | | $2 | $6 |
|
|
45
46
|
| `xai/grok-build-0.1` | 256K | | | | | | $1 | $2 |
|
|
46
47
|
| `xai/grok-imagine-image` | 16K | | | | | | — | — |
|
|
48
|
+
| `xai/grok-imagine-image-quality` | 16K | | | | | | — | — |
|
|
47
49
|
| `xai/grok-imagine-video` | 1K | | | | | | — | — |
|
|
48
50
|
| `xai/grok-imagine-video-1.5` | 1K | | | | | | — | — |
|
|
49
51
|
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Xiaomi Token Plan (Europe)
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 9 Xiaomi Token Plan (Europe) models through Mastra's model router. Authentication is handled automatically using the `XIAOMI_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [Xiaomi Token Plan (Europe) documentation](https://platform.xiaomimimo.com/#/docs).
|
|
10
10
|
|
|
@@ -44,6 +44,8 @@ for await (const chunk of stream) {
|
|
|
44
44
|
| `xiaomi-token-plan-ams/mimo-v2.5-tts` | 8K | | | | | | — | — |
|
|
45
45
|
| `xiaomi-token-plan-ams/mimo-v2.5-tts-voiceclone` | 8K | | | | | | — | — |
|
|
46
46
|
| `xiaomi-token-plan-ams/mimo-v2.5-tts-voicedesign` | 8K | | | | | | — | — |
|
|
47
|
+
| `xiaomi-token-plan-ams/mimo-v2.6-flash` | 1.0M | | | | | | — | — |
|
|
48
|
+
| `xiaomi-token-plan-ams/mimo-v2.6-pro` | 1.0M | | | | | | — | — |
|
|
47
49
|
|
|
48
50
|
Model availability, capabilities, context windows, and pricing are sourced from [models.dev](https://models.dev) and may change.
|
|
49
51
|
|
|
@@ -75,7 +77,7 @@ const agent = new Agent({
|
|
|
75
77
|
model: ({ requestContext }) => {
|
|
76
78
|
const useAdvanced = requestContext.task === "complex";
|
|
77
79
|
return useAdvanced
|
|
78
|
-
? "xiaomi-token-plan-ams/mimo-v2.
|
|
80
|
+
? "xiaomi-token-plan-ams/mimo-v2.6-pro"
|
|
79
81
|
: "xiaomi-token-plan-ams/mimo-v2-pro";
|
|
80
82
|
}
|
|
81
83
|
});
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Xiaomi Token Plan (China)
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 9 Xiaomi Token Plan (China) models through Mastra's model router. Authentication is handled automatically using the `XIAOMI_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [Xiaomi Token Plan (China) documentation](https://platform.xiaomimimo.com/#/docs).
|
|
10
10
|
|
|
@@ -44,6 +44,8 @@ for await (const chunk of stream) {
|
|
|
44
44
|
| `xiaomi-token-plan-cn/mimo-v2.5-tts` | 8K | | | | | | — | — |
|
|
45
45
|
| `xiaomi-token-plan-cn/mimo-v2.5-tts-voiceclone` | 8K | | | | | | — | — |
|
|
46
46
|
| `xiaomi-token-plan-cn/mimo-v2.5-tts-voicedesign` | 8K | | | | | | — | — |
|
|
47
|
+
| `xiaomi-token-plan-cn/mimo-v2.6-flash` | 1.0M | | | | | | — | — |
|
|
48
|
+
| `xiaomi-token-plan-cn/mimo-v2.6-pro` | 1.0M | | | | | | — | — |
|
|
47
49
|
|
|
48
50
|
Model availability, capabilities, context windows, and pricing are sourced from [models.dev](https://models.dev) and may change.
|
|
49
51
|
|
|
@@ -75,7 +77,7 @@ const agent = new Agent({
|
|
|
75
77
|
model: ({ requestContext }) => {
|
|
76
78
|
const useAdvanced = requestContext.task === "complex";
|
|
77
79
|
return useAdvanced
|
|
78
|
-
? "xiaomi-token-plan-cn/mimo-v2.
|
|
80
|
+
? "xiaomi-token-plan-cn/mimo-v2.6-pro"
|
|
79
81
|
: "xiaomi-token-plan-cn/mimo-v2-pro";
|
|
80
82
|
}
|
|
81
83
|
});
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Xiaomi Token Plan (Singapore)
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 9 Xiaomi Token Plan (Singapore) models through Mastra's model router. Authentication is handled automatically using the `XIAOMI_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [Xiaomi Token Plan (Singapore) documentation](https://platform.xiaomimimo.com/#/docs).
|
|
10
10
|
|
|
@@ -44,6 +44,8 @@ for await (const chunk of stream) {
|
|
|
44
44
|
| `xiaomi-token-plan-sgp/mimo-v2.5-tts` | 8K | | | | | | — | — |
|
|
45
45
|
| `xiaomi-token-plan-sgp/mimo-v2.5-tts-voiceclone` | 8K | | | | | | — | — |
|
|
46
46
|
| `xiaomi-token-plan-sgp/mimo-v2.5-tts-voicedesign` | 8K | | | | | | — | — |
|
|
47
|
+
| `xiaomi-token-plan-sgp/mimo-v2.6-flash` | 1.0M | | | | | | — | — |
|
|
48
|
+
| `xiaomi-token-plan-sgp/mimo-v2.6-pro` | 1.0M | | | | | | — | — |
|
|
47
49
|
|
|
48
50
|
Model availability, capabilities, context windows, and pricing are sourced from [models.dev](https://models.dev) and may change.
|
|
49
51
|
|
|
@@ -75,7 +77,7 @@ const agent = new Agent({
|
|
|
75
77
|
model: ({ requestContext }) => {
|
|
76
78
|
const useAdvanced = requestContext.task === "complex";
|
|
77
79
|
return useAdvanced
|
|
78
|
-
? "xiaomi-token-plan-sgp/mimo-v2.
|
|
80
|
+
? "xiaomi-token-plan-sgp/mimo-v2.6-pro"
|
|
79
81
|
: "xiaomi-token-plan-sgp/mimo-v2-pro";
|
|
80
82
|
}
|
|
81
83
|
});
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Xiaomi
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 9 Xiaomi models through Mastra's model router. Authentication is handled automatically using the `XIAOMI_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [Xiaomi documentation](https://platform.xiaomimimo.com/#/docs).
|
|
10
10
|
|
|
@@ -41,6 +41,9 @@ for await (const chunk of stream) {
|
|
|
41
41
|
| `xiaomi/mimo-v2.5` | 1.0M | | | | | | $0.14 | $0.28 |
|
|
42
42
|
| `xiaomi/mimo-v2.5-pro` | 1.0M | | | | | | $0.43 | $0.87 |
|
|
43
43
|
| `xiaomi/mimo-v2.5-pro-ultraspeed` | 1.0M | | | | | | $1 | $3 |
|
|
44
|
+
| `xiaomi/mimo-v2.6-flash` | 1.0M | | | | | | $0.14 | $0.28 |
|
|
45
|
+
| `xiaomi/mimo-v2.6-pro` | 1.0M | | | | | | $0.43 | $0.87 |
|
|
46
|
+
| `xiaomi/mimo-v2.6-pro-ultraspeed` | 1.0M | | | | | | $4 | $9 |
|
|
44
47
|
|
|
45
48
|
Model availability, capabilities, context windows, and pricing are sourced from [models.dev](https://models.dev) and may change.
|
|
46
49
|
|
|
@@ -72,7 +75,7 @@ const agent = new Agent({
|
|
|
72
75
|
model: ({ requestContext }) => {
|
|
73
76
|
const useAdvanced = requestContext.task === "complex";
|
|
74
77
|
return useAdvanced
|
|
75
|
-
? "xiaomi/mimo-v2.
|
|
78
|
+
? "xiaomi/mimo-v2.6-pro-ultraspeed"
|
|
76
79
|
: "xiaomi/mimo-v2-flash";
|
|
77
80
|
}
|
|
78
81
|
});
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Z.AI
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 18 Z.AI models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [Z.AI documentation](https://docs.z.ai/guides/overview/pricing).
|
|
10
10
|
|
|
@@ -44,6 +44,7 @@ for await (const chunk of stream) {
|
|
|
44
44
|
| `zai/glm-4.5v` | 64K | | | | | | $0.60 | $2 |
|
|
45
45
|
| `zai/glm-4.6` | 205K | | | | | | $0.60 | $2 |
|
|
46
46
|
| `zai/glm-4.6v` | 128K | | | | | | $0.30 | $0.90 |
|
|
47
|
+
| `zai/glm-4.6v-flash` | 128K | | | | | | — | — |
|
|
47
48
|
| `zai/glm-4.7` | 205K | | | | | | $0.60 | $2 |
|
|
48
49
|
| `zai/glm-4.7-flash` | 200K | | | | | | — | — |
|
|
49
50
|
| `zai/glm-4.7-flashx` | 200K | | | | | | $0.07 | $0.40 |
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Zhipu AI
|
|
6
6
|
|
|
7
|
-
Access
|
|
7
|
+
Access 17 Zhipu AI models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
|
|
8
8
|
|
|
9
9
|
Learn more in the [Zhipu AI documentation](https://docs.z.ai/guides/overview/pricing).
|
|
10
10
|
|
|
@@ -44,6 +44,7 @@ for await (const chunk of stream) {
|
|
|
44
44
|
| `zhipuai/glm-4.5v` | 64K | | | | | | $0.60 | $2 |
|
|
45
45
|
| `zhipuai/glm-4.6` | 205K | | | | | | $0.60 | $2 |
|
|
46
46
|
| `zhipuai/glm-4.6v` | 128K | | | | | | $0.30 | $0.90 |
|
|
47
|
+
| `zhipuai/glm-4.6v-flash` | 128K | | | | | | — | — |
|
|
47
48
|
| `zhipuai/glm-4.7` | 205K | | | | | | $0.60 | $2 |
|
|
48
49
|
| `zhipuai/glm-4.7-flash` | 200K | | | | | | — | — |
|
|
49
50
|
| `zhipuai/glm-4.7-flashx` | 200K | | | | | | $0.07 | $0.40 |
|
|
@@ -173,6 +173,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
|
|
|
173
173
|
- [Subconscious](https://mastra.ai/models/providers/subconscious)
|
|
174
174
|
- [submodel](https://mastra.ai/models/providers/submodel)
|
|
175
175
|
- [Synthetic](https://mastra.ai/models/providers/synthetic)
|
|
176
|
+
- [Tempr](https://mastra.ai/models/providers/tempr)
|
|
176
177
|
- [Tencent Coding Plan (China)](https://mastra.ai/models/providers/tencent-coding-plan)
|
|
177
178
|
- [Tencent Token Plan](https://mastra.ai/models/providers/tencent-token-plan)
|
|
178
179
|
- [Tencent TokenHub](https://mastra.ai/models/providers/tencent-tokenhub)
|
|
@@ -1618,6 +1618,17 @@ The response remains nested under `data` to preserve cursor pagination:
|
|
|
1618
1618
|
|
|
1619
1619
|
Pass a non-null `page.next` value back as `page.after` in the next query. See [Advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query) for supported fields and operators, recursive predicates, limits, pagination, and errors.
|
|
1620
1620
|
|
|
1621
|
+
To load a numbered page and then poll, keep the same time range and predicate in both requests:
|
|
1622
|
+
|
|
1623
|
+
```bash
|
|
1624
|
+
mastra api trace query '{"timeRange":{"from":"2026-08-01T00:00:00.000Z","to":"2026-08-08T00:00:00.000Z"},"pagination":{"page":0,"perPage":100}}'
|
|
1625
|
+
mastra api trace query '{"timeRange":{"from":"2026-08-01T00:00:00.000Z","to":"2026-08-08T00:00:00.000Z"},"mode":"delta","after":"CURSOR_FROM_NUMBERED_RESPONSE","limit":100}'
|
|
1626
|
+
```
|
|
1627
|
+
|
|
1628
|
+
Replace `CURSOR_FROM_NUMBERED_RESPONSE` with `data.deltaCursor` from the first response. Delta results remain under `data`, with `traces`, `delta: { limit, hasMore }`, and `deltaCursor`. Merge traces by `traceId`, retain each returned cursor, and continue immediately while `data.delta.hasMore` is `true`. Don't combine delta mode with `page`, `pagination`, or `orderBy`.
|
|
1629
|
+
|
|
1630
|
+
Omitting `after` establishes a cursor and returns no historical traces. Changing the time range or predicate requires a fresh numbered request. See [Delta polling limitations](https://mastra.ai/reference/observability/tracing/trace-query) before using this workflow to maintain a local trace list.
|
|
1631
|
+
|
|
1621
1632
|
#### `mastra api trace get`
|
|
1622
1633
|
|
|
1623
1634
|
Gets a lightweight timeline for one observability trace without fetching full span input, output, attributes, or metadata payloads. Pass `--verbose` to fetch the full trace payload.
|
|
@@ -89,6 +89,33 @@ const result = await mastraClient.queryTraces({
|
|
|
89
89
|
})
|
|
90
90
|
```
|
|
91
91
|
|
|
92
|
+
### Load a page and poll for traces
|
|
93
|
+
|
|
94
|
+
`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`:
|
|
95
|
+
|
|
96
|
+
```typescript
|
|
97
|
+
const timeRange = {
|
|
98
|
+
from: '2026-08-01T00:00:00.000Z',
|
|
99
|
+
to: '2026-08-08T00:00:00.000Z',
|
|
100
|
+
}
|
|
101
|
+
const initial = await mastraClient.queryTraces({
|
|
102
|
+
timeRange,
|
|
103
|
+
pagination: { page: 0, perPage: 100 },
|
|
104
|
+
})
|
|
105
|
+
if (!initial.deltaCursor) throw new Error('Delta polling is unavailable')
|
|
106
|
+
|
|
107
|
+
const changes = await mastraClient.queryTraces({
|
|
108
|
+
timeRange,
|
|
109
|
+
mode: 'delta',
|
|
110
|
+
after: initial.deltaCursor,
|
|
111
|
+
limit: 100,
|
|
112
|
+
})
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
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.
|
|
116
|
+
|
|
117
|
+
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.
|
|
118
|
+
|
|
92
119
|
### Discover trace-query fields and values
|
|
93
120
|
|
|
94
121
|
`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.
|
|
@@ -52,6 +52,14 @@ interface MastraPlatformExporterConfig extends BaseExporterConfig {
|
|
|
52
52
|
|
|
53
53
|
/** Explicit feedback endpoint override */
|
|
54
54
|
feedbackEndpoint?: string
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* When false, `accessToken`, `projectId` and the traces endpoint are taken
|
|
58
|
+
* from config only and the environment variables below are ignored. Use this
|
|
59
|
+
* when embedding Mastra in another tool so a user project's `.env` cannot
|
|
60
|
+
* redirect the host's own telemetry. Default: true
|
|
61
|
+
*/
|
|
62
|
+
resolveFromEnv?: boolean
|
|
55
63
|
}
|
|
56
64
|
```
|
|
57
65
|
|
|
@@ -69,6 +77,8 @@ The exporter reads these environment variables if not provided in config:
|
|
|
69
77
|
- `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` - Observability endpoint override, read by the exporter in `@mastra/observability@1.17.4` and later. Pass either a base origin such as `https://observability.eu.mastra.ai` or a full traces publish URL ending in `/spans/publish`. The other signal endpoints are derived from it. Defaults to `https://observability.mastra.ai`
|
|
70
78
|
- `MASTRA_CLOUD_TRACES_ENDPOINT` - Legacy traces endpoint override. Takes precedence over `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` when both are set
|
|
71
79
|
|
|
80
|
+
All of these are ignored when `resolveFromEnv` is `false`.
|
|
81
|
+
|
|
72
82
|
## Properties
|
|
73
83
|
|
|
74
84
|
```typescript
|
|
@@ -67,6 +67,7 @@ interface SpanTypeMap {
|
|
|
67
67
|
CLIENT_TOOL_CALL: ClientToolCallAttributes
|
|
68
68
|
PROVIDER_TOOL_CALL: ProviderToolCallAttributes
|
|
69
69
|
MCP_TOOL_CALL: MCPToolCallAttributes
|
|
70
|
+
MCP_SERVER_REQUEST: MCPServerRequestAttributes
|
|
70
71
|
PROCESSOR_RUN: ProcessorRunAttributes
|
|
71
72
|
WORKFLOW_STEP: WorkflowStepAttributes
|
|
72
73
|
WORKFLOW_CONDITIONAL: WorkflowConditionalAttributes
|
|
@@ -390,6 +391,9 @@ enum SpanType {
|
|
|
390
391
|
/** MCP (Model Context Protocol) tool execution */
|
|
391
392
|
MCP_TOOL_CALL = 'mcp_tool_call',
|
|
392
393
|
|
|
394
|
+
/** A request served by a Mastra MCPServer (the server side of an MCP edge) */
|
|
395
|
+
MCP_SERVER_REQUEST = 'mcp_server_request',
|
|
396
|
+
|
|
393
397
|
/**
|
|
394
398
|
* Processor execution. This is the default; a processor can declare a
|
|
395
399
|
* different span type so its span names the subsystem it belongs to.
|
|
@@ -652,6 +656,35 @@ interface MCPToolCallAttributes {
|
|
|
652
656
|
}
|
|
653
657
|
```
|
|
654
658
|
|
|
659
|
+
### `MCPServerRequestAttributes`
|
|
660
|
+
|
|
661
|
+
Attributes of a request served by a Mastra `MCPServer`.
|
|
662
|
+
|
|
663
|
+
```typescript
|
|
664
|
+
interface MCPServerRequestAttributes {
|
|
665
|
+
/** MCP method served, e.g. 'tools/call', 'resources/list', 'prompts/get' */
|
|
666
|
+
mcpMethod: string
|
|
667
|
+
|
|
668
|
+
/** Name or URI of the tool, prompt, or resource requested. Absent on list-style calls. */
|
|
669
|
+
targetName?: string
|
|
670
|
+
|
|
671
|
+
/** Configured MCPServer name */
|
|
672
|
+
mcpServer: string
|
|
673
|
+
|
|
674
|
+
/** Configured MCPServer version */
|
|
675
|
+
serverVersion?: string
|
|
676
|
+
|
|
677
|
+
/** Negotiated MCP protocol revision for this request */
|
|
678
|
+
mcpProtocolVersion?: string
|
|
679
|
+
|
|
680
|
+
/** Client implementation name, when the client reported one */
|
|
681
|
+
clientName?: string
|
|
682
|
+
|
|
683
|
+
/** Client implementation version, when the client reported one */
|
|
684
|
+
clientVersion?: string
|
|
685
|
+
}
|
|
686
|
+
```
|
|
687
|
+
|
|
655
688
|
### `ProcessorRunAttributes`
|
|
656
689
|
|
|
657
690
|
Processor attributes.
|
|
@@ -236,12 +236,16 @@ Both routes require `observability:read` and use the configured observability st
|
|
|
236
236
|
|
|
237
237
|
### Trace queries
|
|
238
238
|
|
|
239
|
-
| Field
|
|
240
|
-
|
|
|
241
|
-
| `timeRange`
|
|
242
|
-
| `where`
|
|
243
|
-
| `orderBy`
|
|
244
|
-
| `page`
|
|
239
|
+
| Field | Required | Description |
|
|
240
|
+
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
241
|
+
| `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. |
|
|
242
|
+
| `where` | No | Recursive trace predicate. Supports scalar conditions and `spans`, `scores`, and `feedback` `some` or `none` clauses. |
|
|
243
|
+
| `orderBy` | No | One item ordering results by `startedAt` or `endedAt`, in `asc` or `desc` order. Defaults to `startedAt desc`. Not accepted in delta mode. |
|
|
244
|
+
| `page` | No | `{ limit, after }`. `limit` defaults to 100 and has a maximum of 1000. Pass the opaque `page.next` value as `after`. |
|
|
245
|
+
| `pagination` | No | Numbered pages: `{ page, perPage }`. Defaults to page 0 and 10 results. `perPage` has a maximum of 100. |
|
|
246
|
+
| `mode` | No | Set to `'delta'` to poll using a delta cursor instead of `page` or `pagination`. |
|
|
247
|
+
| `after` | No | Delta mode only. Opaque `deltaCursor` from a numbered page or previous poll. Omit to establish the current watermark. |
|
|
248
|
+
| `limit` | No | Delta mode only. Maximum results per batch. Defaults to 10 and has a maximum of 100. |
|
|
245
249
|
|
|
246
250
|
### Thread queries
|
|
247
251
|
|
|
@@ -525,9 +529,75 @@ Related evidence isn't embedded in either response. Use the trace-detail and bra
|
|
|
525
529
|
|
|
526
530
|
## Pagination and errors
|
|
527
531
|
|
|
532
|
+
### Choose a pagination mode
|
|
533
|
+
|
|
534
|
+
Trace queries support three mutually exclusive modes:
|
|
535
|
+
|
|
536
|
+
| Mode | Request fields | Response metadata |
|
|
537
|
+
| ------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
538
|
+
| Keyset, the default | `page: { limit, after }` | `page: { next }` |
|
|
539
|
+
| Numbered pages | `pagination: { page, perPage }` | `pagination: { total, page, perPage, hasMore }` and, when delta polling is supported, `deltaCursor` |
|
|
540
|
+
| Delta polling | `mode: 'delta'`, optional top-level `after` and `limit` | `delta: { limit, hasMore }` and `deltaCursor` |
|
|
541
|
+
|
|
542
|
+
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.
|
|
543
|
+
|
|
544
|
+
### Poll after loading a numbered page
|
|
545
|
+
|
|
546
|
+
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.
|
|
547
|
+
|
|
548
|
+
```typescript
|
|
549
|
+
const timeRange = {
|
|
550
|
+
from: '2026-08-01T00:00:00.000Z',
|
|
551
|
+
to: '2026-08-08T00:00:00.000Z',
|
|
552
|
+
}
|
|
553
|
+
const initial = await mastraClient.queryTraces({
|
|
554
|
+
timeRange,
|
|
555
|
+
pagination: { page: 0, perPage: 100 },
|
|
556
|
+
})
|
|
557
|
+
if (!initial.deltaCursor) throw new Error('Delta polling is unavailable')
|
|
558
|
+
|
|
559
|
+
const traces = new Map(initial.traces.map(trace => [trace.traceId, trace]))
|
|
560
|
+
let after = initial.deltaCursor
|
|
561
|
+
|
|
562
|
+
async function poll() {
|
|
563
|
+
let hasMore: boolean
|
|
564
|
+
do {
|
|
565
|
+
const result = await mastraClient.queryTraces({
|
|
566
|
+
timeRange,
|
|
567
|
+
mode: 'delta',
|
|
568
|
+
after,
|
|
569
|
+
limit: 100,
|
|
570
|
+
})
|
|
571
|
+
for (const trace of result.traces) traces.set(trace.traceId, trace)
|
|
572
|
+
after = result.deltaCursor
|
|
573
|
+
hasMore = result.delta.hasMore
|
|
574
|
+
} while (hasMore)
|
|
575
|
+
}
|
|
576
|
+
|
|
577
|
+
await poll()
|
|
578
|
+
```
|
|
579
|
+
|
|
580
|
+
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.
|
|
581
|
+
|
|
582
|
+
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`.
|
|
583
|
+
|
|
584
|
+
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.
|
|
585
|
+
|
|
586
|
+
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.
|
|
587
|
+
|
|
588
|
+
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.
|
|
589
|
+
|
|
590
|
+
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.
|
|
591
|
+
|
|
592
|
+
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.
|
|
593
|
+
|
|
594
|
+
### Keyset ordering and errors
|
|
595
|
+
|
|
528
596
|
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.
|
|
529
597
|
|
|
530
|
-
|
|
598
|
+
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.
|
|
599
|
+
|
|
600
|
+
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`.
|
|
531
601
|
|
|
532
602
|
Cursor pagination is deterministic, but it isn't a database snapshot. Traces or replacement signals written between page requests can change later pages.
|
|
533
603
|
|
|
@@ -545,7 +615,7 @@ PostgreSQL and ClickHouse stop advanced trace and thread queries after 15 second
|
|
|
545
615
|
|
|
546
616
|
## Limitations
|
|
547
617
|
|
|
548
|
-
Both operations consider completed traces only. They don't support running traces, custom projections, embedded evidence, summaries, aggregations,
|
|
618
|
+
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.
|
|
549
619
|
|
|
550
620
|
## Related
|
|
551
621
|
|
|
@@ -959,6 +959,14 @@ execute: async ({ items }, context) => {
|
|
|
959
959
|
}
|
|
960
960
|
```
|
|
961
961
|
|
|
962
|
+
## Tracing
|
|
963
|
+
|
|
964
|
+
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.
|
|
965
|
+
|
|
966
|
+
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.
|
|
967
|
+
|
|
968
|
+
A standalone `MCPServer` with no `mastra` instance produces no spans.
|
|
969
|
+
|
|
962
970
|
## Notification delivery
|
|
963
971
|
|
|
964
972
|
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
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/mcp-docs-server",
|
|
3
|
-
"version": "1.2.27
|
|
3
|
+
"version": "1.2.27",
|
|
4
4
|
"description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -27,7 +27,7 @@
|
|
|
27
27
|
"@modelcontextprotocol/sdk": "^1.27.1",
|
|
28
28
|
"local-pkg": "^1.1.2",
|
|
29
29
|
"zod": "^4.6.4",
|
|
30
|
-
"@mastra/core": "1.68.0
|
|
30
|
+
"@mastra/core": "1.68.0"
|
|
31
31
|
},
|
|
32
32
|
"devDependencies": {
|
|
33
33
|
"@hono/node-server": "^2.0.0",
|
|
@@ -42,9 +42,9 @@
|
|
|
42
42
|
"tsx": "^4.23.1",
|
|
43
43
|
"typescript": "^7.0.2",
|
|
44
44
|
"vitest": "4.1.11",
|
|
45
|
-
"@internal/lint": "0.0.
|
|
46
|
-
"@
|
|
47
|
-
"@
|
|
45
|
+
"@internal/lint": "0.0.134",
|
|
46
|
+
"@internal/types-builder": "0.0.109",
|
|
47
|
+
"@mastra/core": "1.68.0"
|
|
48
48
|
},
|
|
49
49
|
"homepage": "https://mastra.ai",
|
|
50
50
|
"repository": {
|