@mastra/mcp-docs-server 1.1.38 → 1.1.39-alpha.10

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.
Files changed (31) hide show
  1. package/.docs/docs/agents/a2a.md +115 -88
  2. package/.docs/docs/agents/acp.md +238 -0
  3. package/.docs/docs/agents/response-caching.md +2 -0
  4. package/.docs/docs/agents/signals.md +1 -1
  5. package/.docs/docs/build-with-ai/skills.md +28 -0
  6. package/.docs/docs/evals/evals-with-memory.md +146 -0
  7. package/.docs/docs/evals/running-in-ci.md +1 -0
  8. package/.docs/docs/server/auth/fga.md +55 -10
  9. package/.docs/models/gateways/openrouter.md +2 -10
  10. package/.docs/models/gateways/vercel.md +1 -8
  11. package/.docs/models/index.md +1 -1
  12. package/.docs/models/providers/berget.md +2 -1
  13. package/.docs/models/providers/kilo.md +9 -22
  14. package/.docs/models/providers/lilac.md +74 -0
  15. package/.docs/models/providers/llmgateway.md +1 -8
  16. package/.docs/models/providers/neuralwatt.md +3 -3
  17. package/.docs/models/providers/novita-ai.md +7 -7
  18. package/.docs/models/providers/opencode.md +1 -1
  19. package/.docs/models/providers/routing-run.md +107 -0
  20. package/.docs/models/providers/xai.md +4 -15
  21. package/.docs/models/providers/xpersona.md +3 -3
  22. package/.docs/models/providers.md +2 -0
  23. package/.docs/reference/agents/agent.md +1 -1
  24. package/.docs/reference/agents/channels.md +6 -0
  25. package/.docs/reference/client-js/agents.md +1 -1
  26. package/.docs/reference/configuration.md +10 -10
  27. package/.docs/reference/server/register-api-route.md +19 -0
  28. package/.docs/reference/storage/convex.md +74 -12
  29. package/.docs/reference/vectors/convex.md +129 -7
  30. package/CHANGELOG.md +35 -0
  31. package/package.json +6 -6
package/.docs/models/providers/novita-ai.md CHANGED
@@ -15,7 +15,7 @@ const agent = new Agent({
15
15
  id: "my-agent",
16
16
  name: "My Agent",
17
17
  instructions: "You are a helpful assistant",
18
- model: "novita-ai/Sao10K/L3-8B-Stheno-v3.2"
18
+ model: "novita-ai/baichuan/baichuan-m2-32b"
19
19
  });
20
20
 
21
21
  // Generate a response
@@ -118,10 +118,10 @@ for await (const chunk of stream) {
118
118
  | `novita-ai/qwen/qwen3.5-27b` | 262K | | | | | | $0.30 | $2 |
119
119
  | `novita-ai/qwen/qwen3.5-35b-a3b` | 262K | | | | | | $0.25 | $2 |
120
120
  | `novita-ai/qwen/qwen3.5-397b-a17b` | 262K | | | | | | $0.60 | $4 |
121
- | `novita-ai/sao10k/l3-70b-euryale-v2.1` | 8K | | | | | | $1 | $1 |
122
- | `novita-ai/sao10k/l3-8b-lunaris` | 8K | | | | | | $0.05 | $0.05 |
123
- | `novita-ai/Sao10K/L3-8B-Stheno-v3.2` | 8K | | | | | | $0.05 | $0.05 |
124
- | `novita-ai/sao10k/l31-70b-euryale-v2.2` | 8K | | | | | | $1 | $1 |
121
+ | `novita-ai/sao10K/l3-70b-euryale-v2.1` | 8K | | | | | | $1 | $1 |
122
+ | `novita-ai/sao10K/l3-8b-lunaris` | 8K | | | | | | $0.05 | $0.05 |
123
+ | `novita-ai/sao10K/L3-8B-stheno-v3.2` | 8K | | | | | | $0.05 | $0.05 |
124
+ | `novita-ai/sao10K/l31-70b-euryale-v2.2` | 8K | | | | | | $1 | $1 |
125
125
  | `novita-ai/xiaomimimo/mimo-v2-flash` | 262K | | | | | | $0.10 | $0.30 |
126
126
  | `novita-ai/zai-org/autoglm-phone-9b-multilingual` | 66K | | | | | | $0.04 | $0.14 |
127
127
  | `novita-ai/zai-org/glm-4.5` | 131K | | | | | | $0.60 | $2 |
@@ -144,7 +144,7 @@ const agent = new Agent({
144
144
  name: "custom-agent",
145
145
  model: {
146
146
  url: "https://api.novita.ai/openai",
147
- id: "novita-ai/Sao10K/L3-8B-Stheno-v3.2",
147
+ id: "novita-ai/baichuan/baichuan-m2-32b",
148
148
  apiKey: process.env.NOVITA_API_KEY,
149
149
  headers: {
150
150
  "X-Custom-Header": "value"
@@ -163,7 +163,7 @@ const agent = new Agent({
163
163
  const useAdvanced = requestContext.task === "complex";
164
164
  return useAdvanced
165
165
  ? "novita-ai/zai-org/glm-5.1"
166
- : "novita-ai/Sao10K/L3-8B-Stheno-v3.2";
166
+ : "novita-ai/baichuan/baichuan-m2-32b";
167
167
  }
168
168
  });
169
169
  ```
package/.docs/models/providers/opencode.md CHANGED
@@ -43,7 +43,7 @@ for await (const chunk of stream) {
43
43
  | `opencode/claude-sonnet-4` | 1.0M | | | | | | $3 | $15 |
44
44
  | `opencode/claude-sonnet-4-5` | 1.0M | | | | | | $3 | $15 |
45
45
  | `opencode/claude-sonnet-4-6` | 1.0M | | | | | | $3 | $15 |
46
- | `opencode/deepseek-v4-flash-free` | 1.0M | | | | | | — | — |
46
+ | `opencode/deepseek-v4-flash-free` | 200K | | | | | | — | — |
47
47
  | `opencode/gemini-3-flash` | 1.0M | | | | | | $0.50 | $3 |
48
48
  | `opencode/gemini-3.1-pro` | 1.0M | | | | | | $2 | $12 |
49
49
  | `opencode/glm-5` | 205K | | | | | | $1 | $3 |
package/.docs/models/providers/routing-run.md ADDED
@@ -0,0 +1,107 @@
1
+ # ![routing.run logo](https://models.dev/logos/routing-run.svg)routing.run
2
+
3
+ Access 37 routing.run models through Mastra's model router. Authentication is handled automatically using the `ROUTING_RUN_API_KEY` environment variable.
4
+
5
+ Learn more in the [routing.run documentation](https://docs.routing.run).
6
+
7
+ ```bash
8
+ ROUTING_RUN_API_KEY=your-api-key
9
+ ```
10
+
11
+ ```typescript
12
+ import { Agent } from "@mastra/core/agent";
13
+
14
+ const agent = new Agent({
15
+ id: "my-agent",
16
+ name: "My Agent",
17
+ instructions: "You are a helpful assistant",
18
+ model: "routing-run/route/deepseek-v3.2"
19
+ });
20
+
21
+ // Generate a response
22
+ const response = await agent.generate("Hello!");
23
+
24
+ // Stream a response
25
+ const stream = await agent.stream("Tell me a story");
26
+ for await (const chunk of stream) {
27
+ console.log(chunk);
28
+ }
29
+ ```
30
+
31
+ > **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [routing.run documentation](https://docs.routing.run) for details.
32
+
33
+ ## Models
34
+
35
+ | Model | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
36
+ | --------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
37
+ | `routing-run/route/deepseek-v3.2` | 164K | | | | | | $0.49 | $0.74 |
38
+ | `routing-run/route/deepseek-v4-flash` | 1.0M | | | | | | $0.49 | $0.74 |
39
+ | `routing-run/route/deepseek-v4-flash-full` | 1.0M | | | | | | $0.49 | $0.74 |
40
+ | `routing-run/route/deepseek-v4-pro` | 1.0M | | | | | | $0.49 | $0.74 |
41
+ | `routing-run/route/deepseek-v4-pro-precision` | 1.0M | | | | | | $0.74 | $1 |
42
+ | `routing-run/route/gemma-4-31b-it` | 131K | | | | | | $0.10 | $0.30 |
43
+ | `routing-run/route/glm-4.7` | 128K | | | | | | $1 | $4 |
44
+ | `routing-run/route/glm-4.7-flash` | 128K | | | | | | $1 | $4 |
45
+ | `routing-run/route/glm-5` | 203K | | | | | | $0.79 | $3 |
46
+ | `routing-run/route/glm-5-highspeed` | 203K | | | | | | $1 | $4 |
47
+ | `routing-run/route/glm-5.1` | 203K | | | | | | $1 | $3 |
48
+ | `routing-run/route/glm-5.1-fp16` | 203K | | | | | | $1 | $4 |
49
+ | `routing-run/route/glm-5.1-full` | 203K | | | | | | $1 | $4 |
50
+ | `routing-run/route/glm-5.1-precision` | 203K | | | | | | $1 | $4 |
51
+ | `routing-run/route/kimi-k2.5` | 262K | | | | | | $0.46 | $2 |
52
+ | `routing-run/route/kimi-k2.5-highspeed` | 131K | | | | | | $0.65 | $3 |
53
+ | `routing-run/route/kimi-k2.6` | 262K | | | | | | $0.46 | $2 |
54
+ | `routing-run/route/kimi-k2.6-full` | 262K | | | | | | $0.46 | $2 |
55
+ | `routing-run/route/kimi-k2.6-precision` | 262K | | | | | | $0.65 | $3 |
56
+ | `routing-run/route/mimo-v2.5` | 256K | | | | | | $0.40 | $2 |
57
+ | `routing-run/route/mimo-v2.5-pro` | 1.0M | | | | | | $0.45 | $1 |
58
+ | `routing-run/route/mimo-v2.5-pro-precision` | 1.0M | | | | | | $0.45 | $1 |
59
+ | `routing-run/route/minimax-m2.5` | 100K | | | | | | $0.19 | $1 |
60
+ | `routing-run/route/minimax-m2.5-highspeed` | 100K | | | | | | $0.19 | $1 |
61
+ | `routing-run/route/minimax-m2.7` | 100K | | | | | | $0.33 | $1 |
62
+ | `routing-run/route/minimax-m2.7-highspeed` | 100K | | | | | | $0.33 | $1 |
63
+ | `routing-run/route/mistral-large-3` | 128K | | | | | | $0.50 | $2 |
64
+ | `routing-run/route/mistral-medium-2505` | 128K | | | | | | $0.40 | $2 |
65
+ | `routing-run/route/mistral-small-2503` | 128K | | | | | | $0.15 | $0.60 |
66
+ | `routing-run/route/qwen3.5-397b-a17b` | 262K | | | | | | $1 | $3 |
67
+ | `routing-run/route/qwen3.5-9b` | 262K | | | | | | $0.20 | $0.60 |
68
+ | `routing-run/route/qwen3.5-9b-chat` | 262K | | | | | | $0.20 | $0.60 |
69
+ | `routing-run/route/qwen3.6-27b` | 262K | | | | | | $1 | $3 |
70
+ | `routing-run/route/step-3.5-flash` | 262K | | | | | | $0.10 | $0.29 |
71
+ | `routing-run/route/step-3.5-flash-2603` | 262K | | | | | | $0.10 | $0.30 |
72
+ | `routing-run/route/step-3.5-flash-full` | 262K | | | | | | $0.10 | $0.29 |
73
+ | `routing-run/route/stepfun-3.5-flash` | 262K | | | | | | $0.10 | $0.29 |
74
+
75
+ ## Advanced configuration
76
+
77
+ ### Custom headers
78
+
79
+ ```typescript
80
+ const agent = new Agent({
81
+ id: "custom-agent",
82
+ name: "custom-agent",
83
+ model: {
84
+ url: "https://api.routing.run/v1",
85
+ id: "routing-run/route/deepseek-v3.2",
86
+ apiKey: process.env.ROUTING_RUN_API_KEY,
87
+ headers: {
88
+ "X-Custom-Header": "value"
89
+ }
90
+ }
91
+ });
92
+ ```
93
+
94
+ ### Dynamic model selection
95
+
96
+ ```typescript
97
+ const agent = new Agent({
98
+ id: "dynamic-agent",
99
+ name: "Dynamic Agent",
100
+ model: ({ requestContext }) => {
101
+ const useAdvanced = requestContext.task === "complex";
102
+ return useAdvanced
103
+ ? "routing-run/route/stepfun-3.5-flash"
104
+ : "routing-run/route/deepseek-v3.2";
105
+ }
106
+ });
107
+ ```
package/.docs/models/providers/xai.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # ![xAI logo](https://models.dev/logos/xai.svg)xAI
2
2
 
3
- Access 26 xAI models through Mastra's model router. Authentication is handled automatically using the `XAI_API_KEY` environment variable.
3
+ Access 15 xAI models through Mastra's model router. Authentication is handled automatically using the `XAI_API_KEY` environment variable.
4
4
 
5
5
  Learn more in the [xAI documentation](https://docs.x.ai/docs/models).
6
6
 
@@ -38,25 +38,14 @@ for await (const chunk of stream) {
38
38
  | `xai/grok-2-vision` | 8K | | | | | | $2 | $10 |
39
39
  | `xai/grok-2-vision-1212` | 8K | | | | | | $2 | $10 |
40
40
  | `xai/grok-2-vision-latest` | 8K | | | | | | $2 | $10 |
41
- | `xai/grok-3` | 131K | | | | | | $3 | $15 |
42
- | `xai/grok-3-fast` | 131K | | | | | | $5 | $25 |
43
- | `xai/grok-3-fast-latest` | 131K | | | | | | $5 | $25 |
44
- | `xai/grok-3-latest` | 131K | | | | | | $3 | $15 |
45
- | `xai/grok-3-mini` | 131K | | | | | | $0.30 | $0.50 |
46
- | `xai/grok-3-mini-fast` | 131K | | | | | | $0.60 | $4 |
47
- | `xai/grok-3-mini-fast-latest` | 131K | | | | | | $0.60 | $4 |
48
- | `xai/grok-3-mini-latest` | 131K | | | | | | $0.30 | $0.50 |
49
- | `xai/grok-4` | 256K | | | | | | $3 | $15 |
50
- | `xai/grok-4-1-fast` | 2.0M | | | | | | $0.20 | $0.50 |
51
- | `xai/grok-4-1-fast-non-reasoning` | 2.0M | | | | | | $0.20 | $0.50 |
52
- | `xai/grok-4-fast` | 2.0M | | | | | | $0.20 | $0.50 |
53
- | `xai/grok-4-fast-non-reasoning` | 2.0M | | | | | | $0.20 | $0.50 |
54
41
  | `xai/grok-4.20-0309-non-reasoning` | 2.0M | | | | | | $2 | $6 |
55
42
  | `xai/grok-4.20-0309-reasoning` | 2.0M | | | | | | $2 | $6 |
56
43
  | `xai/grok-4.20-multi-agent-0309` | 2.0M | | | | | | $2 | $6 |
57
44
  | `xai/grok-4.3` | 1.0M | | | | | | $1 | $3 |
58
45
  | `xai/grok-beta` | 131K | | | | | | $5 | $15 |
59
- | `xai/grok-code-fast-1` | 256K | | | | | | $0.20 | $2 |
46
+ | `xai/grok-imagine-image` | 1K | | | | | | — | — |
47
+ | `xai/grok-imagine-image-quality` | 1K | | | | | | — | — |
48
+ | `xai/grok-imagine-video` | 1K | | | | | | — | — |
60
49
  | `xai/grok-vision-beta` | 8K | | | | | | $5 | $15 |
61
50
 
62
51
  ## Advanced configuration
package/.docs/models/providers/xpersona.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Access 1 Xpersona model through Mastra's model router. Authentication is handled automatically using the `XPERSONA_API_KEY` environment variable.
4
4
 
5
- Learn more in the [Xpersona documentation](https://xpersona.co/docs).
5
+ Learn more in the [Xpersona documentation](https://www.xpersona.co/docs).
6
6
 
7
7
  ```bash
8
8
  XPERSONA_API_KEY=your-api-key
@@ -28,7 +28,7 @@ for await (const chunk of stream) {
28
28
  }
29
29
  ```
30
30
 
31
- > **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Xpersona documentation](https://xpersona.co/docs) for details.
31
+ > **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Xpersona documentation](https://www.xpersona.co/docs) for details.
32
32
 
33
33
  ## Models
34
34
 
@@ -45,7 +45,7 @@ const agent = new Agent({
45
45
  id: "custom-agent",
46
46
  name: "custom-agent",
47
47
  model: {
48
- url: "https://xpersona.co/v1",
48
+ url: "https://www.xpersona.co/v1",
49
49
  id: "xpersona/xpersona-frieren-coder",
50
50
  apiKey: process.env.XPERSONA_API_KEY,
51
51
  headers: {
package/.docs/models/providers.md CHANGED
@@ -53,6 +53,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
53
53
  - [Kilo Gateway](https://mastra.ai/models/providers/kilo)
54
54
  - [Kimi For Coding](https://mastra.ai/models/providers/kimi-for-coding)
55
55
  - [KUAE Cloud Coding Plan](https://mastra.ai/models/providers/kuae-cloud-coding-plan)
56
+ - [Lilac](https://mastra.ai/models/providers/lilac)
56
57
  - [Llama](https://mastra.ai/models/providers/llama)
57
58
  - [LLM Gateway](https://mastra.ai/models/providers/llmgateway)
58
59
  - [LMStudio](https://mastra.ai/models/providers/lmstudio)
@@ -88,6 +89,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
88
89
  - [Qiniu](https://mastra.ai/models/providers/qiniu-ai)
89
90
  - [Regolo AI](https://mastra.ai/models/providers/regolo-ai)
90
91
  - [Requesty](https://mastra.ai/models/providers/requesty)
92
+ - [routing.run](https://mastra.ai/models/providers/routing-run)
91
93
  - [Sarvam AI](https://mastra.ai/models/providers/sarvam)
92
94
  - [Scaleway](https://mastra.ai/models/providers/scaleway)
93
95
  - [SiliconFlow](https://mastra.ai/models/providers/siliconflow)
package/.docs/reference/agents/agent.md CHANGED
@@ -143,7 +143,7 @@ agent.sendSignal(
143
143
 
144
144
  Sends a signal to an active run or memory thread.
145
145
 
146
- **signal** (`{ type: 'user-message'; contents: MessageListInput } | { type: string; contents: string }`): \`user-message\` signals are treated as user input. Other signal types are converted to XML context before the next model call.
146
+ **signal** (`{ type: 'user-message' | string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): \`user-message\` signals are treated as user input. Other signal types are wrapped in XML context (with any \`attributes\`) before the next model call. \`providerOptions\` is attached to the resulting prompt turn and persisted on the stored signal message.
147
147
 
148
148
  **options.runId** (`string`): Run ID to target directly. Use this when you already know the active run ID.
149
149
 
package/.docs/reference/agents/channels.md CHANGED
@@ -63,6 +63,10 @@ const agent = new Agent({
63
63
  discord: {
64
64
  adapter: createDiscordAdapter(),
65
65
  cards: false,
66
+ cors: {
67
+ origin: ['https://customer-saas.example'],
68
+ credentials: true,
69
+ },
66
70
  gateway: false,
67
71
  },
68
72
  slack: createSlackAdapter(), // Plain adapter uses defaults
@@ -77,6 +81,8 @@ const agent = new Agent({
77
81
 
78
82
  **cards** (`boolean`): Render tool calls as interactive rich cards with buttons. Set to \`false\` to use plain text formatting instead. When disabled and a tool requires approval, the agent uses \`autoResumeSuspendedTools\` to let the LLM decide based on conversation context. (Default: `true`)
79
83
 
84
+ **cors** (`CorsOptions`): CORS configuration for this adapter webhook route. Use this for browser-based channel adapters that need cross-origin credentials.
85
+
80
86
  **formatToolCall** (`(info: { toolName, args, result, isError? }) => PostableMessage | null`): Override how tool calls are rendered in the chat. Called once per tool invocation after the result is available. Return \`null\` to suppress the message entirely.
81
87
 
82
88
  **formatError** (`(error: Error) => PostableMessage`): Override how errors are rendered in the chat. Return a user-friendly message instead of exposing the raw error. (Default: `"❌ Error: <error.message>"`)
package/.docs/reference/client-js/agents.md CHANGED
@@ -201,7 +201,7 @@ await agent.sendSignal({
201
201
 
202
202
  Returns `{ accepted: true, runId: string }`.
203
203
 
204
- **signal** (`{ type: 'user-message'; contents: MessageListInput } | { type: string; contents: string }`): \`user-message\` signals are treated as user input. Other signal types are converted to contextual XML before the next model call.
204
+ **signal** (`{ type: 'user-message' | string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): \`user-message\` signals are treated as user input. Other signal types are wrapped in XML context (with any \`attributes\`) before the next model call. \`providerOptions\` is attached to the resulting prompt turn and persisted on the stored signal message.
205
205
 
206
206
  **runId** (`string`): Run ID to target directly.
207
207
 
package/.docs/reference/configuration.md CHANGED
@@ -684,16 +684,16 @@ export const mastra = new Mastra({
684
684
 
685
685
  **Type:** `CorsOptions | false`
686
686
 
687
- CORS (Cross-Origin Resource Sharing) configuration for the server. Set to `false` to disable CORS entirely.
688
-
689
- | Property | Type | Default | Description |
690
- | --------------- | -------------------- | ----------------------------------------------------------- | -------------------------------------------- |
691
- | `origin` | `string \| string[]` | `'*'` | Origins for CORS requests |
692
- | `allowMethods` | `string[]` | `['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']` | HTTP methods |
693
- | `allowHeaders` | `string[]` | `['Content-Type', 'Authorization', 'x-mastra-client-type']` | Request headers |
694
- | `exposeHeaders` | `string[]` | `['Content-Length', 'X-Requested-With']` | Browser headers |
695
- | `credentials` | `boolean` | `false` | Credentials (cookies, authorization headers) |
696
- | `maxAge` | `number` | `3600` | Preflight request cache duration in seconds |
687
+ CORS (Cross-Origin Resource Sharing) configuration for the server. Set to `false` to disable CORS entirely. Use this for one policy across all routes. For a custom route-specific policy, use the `cors` option in [`registerApiRoute()`](https://mastra.ai/reference/server/register-api-route).
688
+
689
+ | Property | Type | Default | Description |
690
+ | --------------- | -------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------- |
691
+ | `origin` | `string \| string[]` | `'*'` | Origins for CORS requests |
692
+ | `allowMethods` | `string[]` | `['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']` | HTTP methods |
693
+ | `allowHeaders` | `string[]` | `['Content-Type', 'Authorization', 'x-mastra-client-type', 'x-mastra-dev-playground']` | Request headers |
694
+ | `exposeHeaders` | `string[]` | `['Content-Length', 'X-Requested-With']` | Browser headers |
695
+ | `credentials` | `boolean` | `false` | Credentials (cookies, authorization headers) |
696
+ | `maxAge` | `number` | `3600` | Preflight request cache duration in seconds |
697
697
 
698
698
  ```typescript
699
699
  import { Mastra } from '@mastra/core'
package/.docs/reference/server/register-api-route.md CHANGED
@@ -30,6 +30,8 @@ registerApiRoute("/items/:itemId", { ... })
30
30
 
31
31
  **middleware** (`MiddlewareHandler | MiddlewareHandler[]`): Route-specific middleware functions
32
32
 
33
+ **cors** (`CorsOptions`): Route-specific CORS configuration. Use this when one custom route needs a different cross-origin policy from \`server.cors\`.
34
+
33
35
  **openapi** (`DescribeRouteOptions`): OpenAPI metadata for Swagger UI documentation
34
36
 
35
37
  ## OpenAPI options
@@ -154,6 +156,23 @@ registerApiRoute('/protected', {
154
156
  })
155
157
  ```
156
158
 
159
+ ### Route with CORS
160
+
161
+ Use route-specific CORS when one custom route needs cross-origin credentials, but the rest of the server should keep the global CORS policy.
162
+
163
+ ```typescript
164
+ registerApiRoute('/customer-webhook', {
165
+ method: 'POST',
166
+ cors: {
167
+ origin: ['https://customer-saas.example'],
168
+ credentials: true,
169
+ },
170
+ handler: async c => {
171
+ return c.json({ ok: true })
172
+ },
173
+ })
174
+ ```
175
+
157
176
  ### Route with OpenAPI Documentation
158
177
 
159
178
  ```typescript
package/.docs/reference/storage/convex.md CHANGED
@@ -34,7 +34,7 @@ bun add @mastra/convex@latest
34
34
 
35
35
  ## Convex setup
36
36
 
37
- Before using `ConvexStore`, you need to set up the Convex schema and storage handler in your Convex project.
37
+ Before using `ConvexStore`, set up the Convex schema and storage handler in your Convex project. The schema example below includes the full `ConvexStore` and `ConvexServerCache` setup. If you only use `ConvexStore`, omit `mastraCacheTable` and `mastraCacheListItemsTable`; if you use `ConvexServerCache`, include those tables and create the cache handler.
38
38
 
39
39
  ### 1. Set up Convex Schema
40
40
 
@@ -50,6 +50,8 @@ import {
50
50
  mastraScoresTable,
51
51
  mastraVectorIndexesTable,
52
52
  mastraVectorsTable,
53
+ mastraCacheTable,
54
+ mastraCacheListItemsTable,
53
55
  mastraDocumentsTable,
54
56
  } from '@mastra/convex/schema'
55
57
 
@@ -61,6 +63,8 @@ export default defineSchema({
61
63
  mastra_scorers: mastraScoresTable,
62
64
  mastra_vector_indexes: mastraVectorIndexesTable,
63
65
  mastra_vectors: mastraVectorsTable,
66
+ mastra_cache: mastraCacheTable,
67
+ mastra_cache_list_items: mastraCacheListItemsTable,
64
68
  mastra_documents: mastraDocumentsTable,
65
69
  })
66
70
  ```
@@ -75,6 +79,14 @@ import { mastraStorage } from '@mastra/convex/server'
75
79
  export const handle = mastraStorage
76
80
  ```
77
81
 
82
+ If you use `ConvexServerCache`, create `convex/mastra/cache.ts`:
83
+
84
+ ```typescript
85
+ import { mastraCache } from '@mastra/convex/server'
86
+
87
+ export const handle = mastraCache
88
+ ```
89
+
78
90
  ### 3. Deploy to Convex
79
91
 
80
92
  ```bash
@@ -86,16 +98,21 @@ npx convex deploy
86
98
  ## Usage
87
99
 
88
100
  ```typescript
89
- import { ConvexStore } from '@mastra/convex'
101
+ import { ConvexServerCache, ConvexStore } from '@mastra/convex'
90
102
 
91
103
  const storage = new ConvexStore({
92
104
  id: 'convex-storage',
93
105
  deploymentUrl: process.env.CONVEX_URL!,
94
106
  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
95
107
  })
108
+
109
+ const cache = new ConvexServerCache({
110
+ deploymentUrl: process.env.CONVEX_URL!,
111
+ adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
112
+ })
96
113
  ```
97
114
 
98
- ## Parameters
115
+ ## ConvexStore parameters
99
116
 
100
117
  **deploymentUrl** (`string`): Convex deployment URL (e.g., https\://your-project.convex.cloud)
101
118
 
@@ -103,10 +120,24 @@ const storage = new ConvexStore({
103
120
 
104
121
  **storageFunction** (`string`): Path to the storage mutation function (default: 'mastra/storage:handle') (Default: `mastra/storage:handle`)
105
122
 
123
+ ## ConvexServerCache parameters
124
+
125
+ **deploymentUrl** (`string`): Convex deployment URL (e.g., https\://your-project.convex.cloud)
126
+
127
+ **adminAuthToken** (`string`): Convex admin authentication token for backend access
128
+
129
+ **cacheFunction** (`string`): Path to the cache mutation function for ConvexServerCache (default: 'mastra/cache:handle') (Default: `mastra/cache:handle`)
130
+
131
+ **requestTimeoutMs** (`number`): Timeout for Convex cache mutation requests in milliseconds. Set to 0 to disable the client-side timeout. (Default: `30000`)
132
+
133
+ **keyPrefix** (`string`): Prefix applied to ConvexServerCache keys. clear() removes rows whose stored prefix exactly matches this value. (Default: `mastra:cache:`)
134
+
135
+ **ttlMs** (`number`): Default ConvexServerCache TTL in milliseconds. Set to 0 to disable expiry. (Default: `300000`)
136
+
106
137
  ## Constructor examples
107
138
 
108
139
  ```ts
109
- import { ConvexStore } from '@mastra/convex'
140
+ import { ConvexServerCache, ConvexStore } from '@mastra/convex'
110
141
 
111
142
  // Basic configuration
112
143
  const store = new ConvexStore({
@@ -122,22 +153,53 @@ const storeCustom = new ConvexStore({
122
153
  adminAuthToken: 'your-admin-token',
123
154
  storageFunction: 'custom/path:handler',
124
155
  })
156
+
157
+ // Server cache for durable stream replay and response caching
158
+ const cache = new ConvexServerCache({
159
+ deploymentUrl: 'https://your-project.convex.cloud',
160
+ adminAuthToken: 'your-admin-token',
161
+ cacheFunction: 'mastra/cache:handle',
162
+ })
125
163
  ```
126
164
 
165
+ ## Server cache
166
+
167
+ `ConvexServerCache` implements Mastra's server cache contract with Convex. Use it when you want durable cache state for features such as resumable durable-agent streams, workflow stream replay, or response caching.
168
+
169
+ `ConvexServerCache` stores list entries as separate Convex documents. This avoids growing a stream replay list inside one document and helps stay within Convex's record size limit.
170
+
171
+ Each scalar cache value and each list item is stored as one Convex row and must stay within Convex's row-size limits. Very large lists are still bounded by Convex query limits when replaying a range.
172
+
173
+ Cache cleanup and `clear()` run in bounded batches. A single client call can loop through up to 1,000 Convex mutations, with each mutation handling up to 25 list items. While `clear()` is cleaning a key, reads for that key can return empty results until cleanup finishes.
174
+
175
+ For very large cache namespaces, clear incrementally or use narrower prefixes to avoid long-running cleanup operations.
176
+
177
+ During batched cleanup, cache metadata can temporarily use an internal `deleted` state. The next cleanup pass removes those rows. Avoid writing new values with the same prefix until `clear()` finishes.
178
+
179
+ `clear()` only removes rows whose stored `keyPrefix` exactly matches the configured `keyPrefix`. It does not clear nested prefixes by string prefix matching. Each `listPush()` refreshes the list TTL using the cache's configured `ttlMs`.
180
+
181
+ Use a non-empty `keyPrefix` unless you intentionally want `clear()` to remove every cache key in the deployment. Expired list rows are reclaimed incrementally during reads and writes; `clear()` removes all rows for the prefix.
182
+
183
+ `ConvexServerCache` works best for durable replay of moderate-frequency events. For high-frequency token streams, prefer batching events or using a lower-latency cache backend.
184
+
185
+ `ConvexServerCache` does not replace a distributed pub/sub transport. If your app needs live cross-process event delivery, configure a production pub/sub backend separately.
186
+
127
187
  ## Additional notes
128
188
 
129
189
  ### Schema Management
130
190
 
131
191
  The storage implementation uses typed Convex tables for each Mastra domain:
132
192
 
133
- | Domain | Convex Table | Purpose |
134
- | --------- | --------------------------- | -------------------- |
135
- | Threads | `mastra_threads` | Conversation threads |
136
- | Messages | `mastra_messages` | Chat messages |
137
- | Resources | `mastra_resources` | User working memory |
138
- | Workflows | `mastra_workflow_snapshots` | Workflow state |
139
- | Scorers | `mastra_scorers` | Evaluation data |
140
- | Fallback | `mastra_documents` | Unknown tables |
193
+ | Domain | Convex Table | Purpose |
194
+ | ----------- | --------------------------- | ----------------------------------------- |
195
+ | Threads | `mastra_threads` | Conversation threads |
196
+ | Messages | `mastra_messages` | Chat messages |
197
+ | Resources | `mastra_resources` | User working memory |
198
+ | Workflows | `mastra_workflow_snapshots` | Workflow state |
199
+ | Scorers | `mastra_scorers` | Evaluation data |
200
+ | Cache | `mastra_cache` | Cache values, counters, and list metadata |
201
+ | Cache Items | `mastra_cache_list_items` | Cache list entries |
202
+ | Fallback | `mastra_documents` | Unknown tables |
141
203
 
142
204
  ### Architecture
143
205