@mastra/mcp-docs-server 1.0.0-beta.11 → 1.0.0-beta.13

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 (159) hide show
  1. package/.docs/organized/changelogs/%40mastra%2Fagent-builder.md +12 -12
  2. package/.docs/organized/changelogs/%40mastra%2Fai-sdk.md +24 -24
  3. package/.docs/organized/changelogs/%40mastra%2Fclickhouse.md +45 -45
  4. package/.docs/organized/changelogs/%40mastra%2Fclient-js.md +83 -83
  5. package/.docs/organized/changelogs/%40mastra%2Fcloudflare-d1.md +39 -39
  6. package/.docs/organized/changelogs/%40mastra%2Fcloudflare.md +39 -39
  7. package/.docs/organized/changelogs/%40mastra%2Fconvex.md +38 -0
  8. package/.docs/organized/changelogs/%40mastra%2Fcore.md +174 -174
  9. package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloud.md +17 -17
  10. package/.docs/organized/changelogs/%40mastra%2Fdeployer.md +27 -27
  11. package/.docs/organized/changelogs/%40mastra%2Fdynamodb.md +39 -39
  12. package/.docs/organized/changelogs/%40mastra%2Ffastembed.md +6 -0
  13. package/.docs/organized/changelogs/%40mastra%2Flance.md +39 -39
  14. package/.docs/organized/changelogs/%40mastra%2Flibsql.md +45 -45
  15. package/.docs/organized/changelogs/%40mastra%2Fmcp-docs-server.md +15 -15
  16. package/.docs/organized/changelogs/%40mastra%2Fmemory.md +13 -13
  17. package/.docs/organized/changelogs/%40mastra%2Fmongodb.md +39 -39
  18. package/.docs/organized/changelogs/%40mastra%2Fmssql.md +39 -39
  19. package/.docs/organized/changelogs/%40mastra%2Fpg.md +45 -45
  20. package/.docs/organized/changelogs/%40mastra%2Fplayground-ui.md +75 -75
  21. package/.docs/organized/changelogs/%40mastra%2Freact.md +40 -0
  22. package/.docs/organized/changelogs/%40mastra%2Fschema-compat.md +6 -0
  23. package/.docs/organized/changelogs/%40mastra%2Fserver.md +29 -29
  24. package/.docs/organized/changelogs/%40mastra%2Fupstash.md +39 -39
  25. package/.docs/organized/changelogs/create-mastra.md +29 -29
  26. package/.docs/organized/changelogs/mastra.md +35 -35
  27. package/.docs/organized/code-examples/quick-start.md +0 -4
  28. package/.docs/organized/code-examples/stock-price-tool.md +21 -2
  29. package/.docs/raw/agents/agent-approval.mdx +136 -2
  30. package/.docs/raw/agents/agent-memory.mdx +4 -4
  31. package/.docs/raw/agents/guardrails.mdx +1 -1
  32. package/.docs/raw/agents/networks.mdx +1 -1
  33. package/.docs/raw/agents/overview.mdx +2 -2
  34. package/.docs/raw/agents/using-tools.mdx +1 -1
  35. package/.docs/raw/course/01-first-agent/07-creating-your-agent.md +1 -2
  36. package/.docs/raw/course/01-first-agent/12-connecting-tool-to-agent.md +1 -1
  37. package/.docs/raw/course/01-first-agent/16-adding-memory-to-agent.md +1 -2
  38. package/.docs/raw/course/02-agent-tools-mcp/05-updating-your-agent.md +1 -1
  39. package/.docs/raw/course/02-agent-tools-mcp/10-updating-agent-instructions-zapier.md +1 -1
  40. package/.docs/raw/course/02-agent-tools-mcp/16-updating-agent-instructions-github.md +1 -1
  41. package/.docs/raw/course/02-agent-tools-mcp/21-updating-agent-instructions-hackernews.md +1 -1
  42. package/.docs/raw/course/02-agent-tools-mcp/27-updating-agent-instructions-filesystem.md +1 -1
  43. package/.docs/raw/course/02-agent-tools-mcp/31-enhancing-memory-configuration.md +2 -2
  44. package/.docs/raw/course/03-agent-memory/04-creating-basic-memory-agent.md +1 -2
  45. package/.docs/raw/course/03-agent-memory/08-configuring-conversation-history.md +1 -2
  46. package/.docs/raw/course/03-agent-memory/16-configuring-semantic-recall.md +3 -4
  47. package/.docs/raw/course/03-agent-memory/21-configuring-working-memory.md +2 -3
  48. package/.docs/raw/course/03-agent-memory/22-custom-working-memory-templates.md +2 -3
  49. package/.docs/raw/course/03-agent-memory/25-combining-memory-features.md +1 -2
  50. package/.docs/raw/course/03-agent-memory/27-creating-learning-assistant.md +2 -3
  51. package/.docs/raw/course/04-workflows/11-creating-an-ai-agent.md +2 -3
  52. package/.docs/raw/deployment/cloud-providers.mdx +20 -0
  53. package/.docs/raw/deployment/{building-mastra.mdx → mastra-server.mdx} +2 -2
  54. package/.docs/raw/deployment/monorepo.mdx +23 -44
  55. package/.docs/raw/deployment/overview.mdx +28 -53
  56. package/.docs/raw/deployment/web-framework.mdx +12 -14
  57. package/.docs/raw/getting-started/start.mdx +10 -1
  58. package/.docs/raw/getting-started/studio.mdx +1 -1
  59. package/.docs/raw/guides/build-your-ui/ai-sdk-ui.mdx +1021 -67
  60. package/.docs/raw/{deployment/cloud-providers → guides/deployment}/aws-lambda.mdx +3 -6
  61. package/.docs/raw/{deployment/cloud-providers → guides/deployment}/azure-app-services.mdx +4 -6
  62. package/.docs/raw/{deployment/cloud-providers → guides/deployment}/cloudflare-deployer.mdx +4 -0
  63. package/.docs/raw/{deployment/cloud-providers → guides/deployment}/digital-ocean.mdx +3 -6
  64. package/.docs/raw/guides/deployment/index.mdx +32 -0
  65. package/.docs/raw/{deployment/cloud-providers → guides/deployment}/netlify-deployer.mdx +4 -0
  66. package/.docs/raw/{deployment/cloud-providers → guides/deployment}/vercel-deployer.mdx +4 -0
  67. package/.docs/raw/guides/getting-started/express.mdx +71 -152
  68. package/.docs/raw/guides/getting-started/hono.mdx +227 -0
  69. package/.docs/raw/guides/getting-started/next-js.mdx +173 -63
  70. package/.docs/raw/guides/getting-started/vite-react.mdx +307 -137
  71. package/.docs/raw/guides/guide/research-assistant.mdx +4 -4
  72. package/.docs/raw/guides/migrations/upgrade-to-v1/client.mdx +17 -0
  73. package/.docs/raw/guides/migrations/upgrade-to-v1/overview.mdx +6 -0
  74. package/.docs/raw/index.mdx +1 -1
  75. package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/dashboard.mdx +2 -6
  76. package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/observability.mdx +1 -5
  77. package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/overview.mdx +2 -6
  78. package/.docs/raw/{deployment/mastra-cloud → mastra-cloud}/setting-up.mdx +3 -6
  79. package/.docs/raw/memory/overview.mdx +1 -1
  80. package/.docs/raw/memory/storage/memory-with-libsql.mdx +1 -1
  81. package/.docs/raw/memory/storage/memory-with-mongodb.mdx +1 -1
  82. package/.docs/raw/memory/storage/memory-with-pg.mdx +1 -1
  83. package/.docs/raw/memory/storage/memory-with-upstash.mdx +1 -1
  84. package/.docs/raw/{server-db/storage.mdx → memory/storage/overview.mdx} +2 -2
  85. package/.docs/raw/observability/logging.mdx +1 -1
  86. package/.docs/raw/observability/tracing/exporters/cloud.mdx +1 -1
  87. package/.docs/raw/observability/tracing/exporters/default.mdx +1 -1
  88. package/.docs/raw/rag/chunking-and-embedding.mdx +12 -25
  89. package/.docs/raw/rag/graph-rag.mdx +220 -0
  90. package/.docs/raw/rag/overview.mdx +1 -2
  91. package/.docs/raw/rag/retrieval.mdx +13 -29
  92. package/.docs/raw/rag/vector-databases.mdx +7 -3
  93. package/.docs/raw/reference/agents/getDefaultGenerateOptions.mdx +1 -1
  94. package/.docs/raw/reference/agents/getDefaultOptions.mdx +1 -1
  95. package/.docs/raw/reference/agents/getDefaultStreamOptions.mdx +1 -1
  96. package/.docs/raw/reference/agents/getInstructions.mdx +1 -1
  97. package/.docs/raw/reference/agents/getLLM.mdx +1 -1
  98. package/.docs/raw/reference/agents/getMemory.mdx +1 -1
  99. package/.docs/raw/reference/agents/getModel.mdx +1 -1
  100. package/.docs/raw/reference/agents/listScorers.mdx +1 -1
  101. package/.docs/raw/reference/ai-sdk/chat-route.mdx +1 -1
  102. package/.docs/raw/reference/ai-sdk/handle-chat-stream.mdx +1 -1
  103. package/.docs/raw/reference/ai-sdk/handle-network-stream.mdx +1 -1
  104. package/.docs/raw/reference/ai-sdk/handle-workflow-stream.mdx +1 -1
  105. package/.docs/raw/reference/ai-sdk/network-route.mdx +1 -1
  106. package/.docs/raw/reference/ai-sdk/to-ai-sdk-v4-messages.mdx +127 -0
  107. package/.docs/raw/reference/ai-sdk/to-ai-sdk-v5-messages.mdx +107 -0
  108. package/.docs/raw/reference/ai-sdk/workflow-route.mdx +1 -1
  109. package/.docs/raw/reference/auth/auth0.mdx +1 -1
  110. package/.docs/raw/reference/auth/clerk.mdx +1 -1
  111. package/.docs/raw/reference/auth/firebase.mdx +1 -1
  112. package/.docs/raw/reference/auth/jwt.mdx +1 -1
  113. package/.docs/raw/reference/auth/supabase.mdx +1 -1
  114. package/.docs/raw/reference/auth/workos.mdx +1 -1
  115. package/.docs/raw/reference/cli/mastra.mdx +1 -1
  116. package/.docs/raw/reference/client-js/mastra-client.mdx +1 -1
  117. package/.docs/raw/reference/client-js/workflows.mdx +20 -0
  118. package/.docs/raw/reference/core/getServer.mdx +2 -2
  119. package/.docs/raw/reference/core/getStorage.mdx +1 -1
  120. package/.docs/raw/reference/core/getStoredAgentById.mdx +1 -1
  121. package/.docs/raw/reference/core/listStoredAgents.mdx +1 -1
  122. package/.docs/raw/reference/core/setStorage.mdx +1 -1
  123. package/.docs/raw/reference/logging/pino-logger.mdx +1 -1
  124. package/.docs/raw/reference/rag/database-config.mdx +1 -1
  125. package/.docs/raw/reference/server/create-route.mdx +1 -1
  126. package/.docs/raw/reference/server/express-adapter.mdx +4 -4
  127. package/.docs/raw/reference/server/hono-adapter.mdx +4 -4
  128. package/.docs/raw/reference/server/mastra-server.mdx +2 -2
  129. package/.docs/raw/reference/server/routes.mdx +28 -1
  130. package/.docs/raw/reference/streaming/agents/stream.mdx +22 -0
  131. package/.docs/raw/reference/streaming/workflows/stream.mdx +33 -20
  132. package/.docs/raw/reference/tools/create-tool.mdx +23 -1
  133. package/.docs/raw/reference/tools/graph-rag-tool.mdx +3 -3
  134. package/.docs/raw/reference/tools/vector-query-tool.mdx +3 -3
  135. package/.docs/raw/reference/workflows/run-methods/startAsync.mdx +143 -0
  136. package/.docs/raw/reference/workflows/workflow-methods/create-run.mdx +35 -0
  137. package/.docs/raw/reference/workflows/workflow.mdx +14 -0
  138. package/.docs/raw/{auth → server/auth}/auth0.mdx +1 -1
  139. package/.docs/raw/{auth → server/auth}/clerk.mdx +1 -1
  140. package/.docs/raw/{auth → server/auth}/firebase.mdx +1 -1
  141. package/.docs/raw/{auth → server/auth}/index.mdx +6 -6
  142. package/.docs/raw/{auth → server/auth}/jwt.mdx +1 -1
  143. package/.docs/raw/{auth → server/auth}/supabase.mdx +1 -1
  144. package/.docs/raw/{auth → server/auth}/workos.mdx +1 -1
  145. package/.docs/raw/{server-db → server}/custom-adapters.mdx +3 -3
  146. package/.docs/raw/{server-db → server}/custom-api-routes.mdx +1 -1
  147. package/.docs/raw/{server-db → server}/mastra-client.mdx +2 -2
  148. package/.docs/raw/{server-db → server}/mastra-server.mdx +5 -5
  149. package/.docs/raw/{server-db → server}/middleware.mdx +2 -2
  150. package/.docs/raw/{server-db → server}/request-context.mdx +3 -3
  151. package/.docs/raw/{server-db → server}/server-adapters.mdx +6 -6
  152. package/.docs/raw/tools-mcp/overview.mdx +2 -2
  153. package/.docs/raw/workflows/error-handling.mdx +162 -1
  154. package/.docs/raw/workflows/overview.mdx +2 -2
  155. package/CHANGELOG.md +14 -0
  156. package/package.json +3 -3
  157. package/.docs/organized/changelogs/%40internal%2Fai-sdk-v4.md +0 -1
  158. package/.docs/raw/deployment/cloud-providers/index.mdx +0 -55
  159. /package/.docs/raw/{deployment/cloud-providers → guides/deployment}/amazon-ec2.mdx +0 -0
@@ -5,18 +5,22 @@ description: Documentation for the `Run.stream()` method in workflows, which ena
5
5
 
6
6
  # Run.stream()
7
7
 
8
- The `.stream()` method enables real-time streaming of responses from a workflow.
8
+ The `.stream()` method enables real-time streaming of responses from a workflow. It returns a `ReadableStream` of events directly.
9
9
 
10
10
  ## Usage example
11
11
 
12
12
  ```typescript showLineNumbers copy
13
13
  const run = await workflow.createRun();
14
14
 
15
- const stream = run.stream({
15
+ const stream = await run.stream({
16
16
  inputData: {
17
17
  value: "initial data",
18
18
  },
19
19
  });
20
+
21
+ for await (const chunk of stream) {
22
+ console.log(chunk);
23
+ }
20
24
  ```
21
25
 
22
26
  ## Parameters
@@ -129,35 +133,30 @@ const stream = run.stream({
129
133
 
130
134
  ## Returns
131
135
 
136
+ Returns a `WorkflowRunOutput` object that implements the async iterable interface (can be used directly in `for await...of` loops) and provides access to the stream and workflow execution results.
137
+
132
138
  <PropertiesTable
133
139
  content={[
134
140
  {
135
- name: "stream",
136
- type: "MastraWorkflowStream<ChunkType>",
141
+ name: "fullStream",
142
+ type: "ReadableStream<WorkflowStreamEvent>",
137
143
  description:
138
- "A custom stream that extends ReadableStream<ChunkType> with additional workflow-specific properties",
144
+ "A ReadableStream of workflow events that you can iterate over to track progress in real-time. You can also iterate over the WorkflowRunOutput object directly.",
139
145
  },
140
146
  {
141
- name: "stream.status",
142
- type: "Promise<RunStatus>",
143
- description: "A promise that resolves to the current workflow run status",
144
- },
145
- {
146
- name: "stream.result",
147
- type: "Promise<WorkflowResult<TState, TOutput, TSteps>>",
147
+ name: "result",
148
+ type: "Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>",
148
149
  description: "A promise that resolves to the final workflow result",
149
150
  },
150
151
  {
151
- name: "stream.usage",
152
- type: "Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cacheInputTokens?: number }>",
153
- description: "A promise that resolves to token usage statistics",
152
+ name: "status",
153
+ type: "WorkflowRunStatus",
154
+ description: "The current workflow run status ('running', 'suspended', 'success', 'failed', 'canceled', or 'tripwire')",
154
155
  },
155
156
  {
156
- name: "stream.traceId",
157
- type: "string",
158
- isOptional: true,
159
- description:
160
- "The trace ID associated with this execution when Tracing is enabled.",
157
+ name: "usage",
158
+ type: "Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cachedInputTokens?: number }>",
159
+ description: "A promise that resolves to token usage statistics",
161
160
  },
162
161
  ]}
163
162
  />
@@ -173,7 +172,21 @@ const stream = run.stream({
173
172
  },
174
173
  });
175
174
 
175
+ // Iterate over stream events (you can iterate over stream directly or use stream.fullStream)
176
+ for await (const chunk of stream) {
177
+ console.log(chunk);
178
+ }
179
+
180
+ // Access the final result
176
181
  const result = await stream.result;
182
+ console.log("Final result:", result);
183
+
184
+ // Access token usage
185
+ const usage = await stream.usage;
186
+ console.log("Token usage:", usage);
187
+
188
+ // Check current status
189
+ console.log("Status:", stream.status);
177
190
  ```
178
191
 
179
192
  ## Stream Events
@@ -63,6 +63,27 @@ export const tool = createTool({
63
63
  "A Zod schema defining the expected output structure of the tool's `execute` function.",
64
64
  isOptional: true,
65
65
  },
66
+ {
67
+ name: "suspendSchema",
68
+ type: "Zod schema",
69
+ description:
70
+ "A Zod schema defining the structure of the payload passed to `suspend()`. This payload is returned to the client when the tool suspends execution.",
71
+ isOptional: true,
72
+ },
73
+ {
74
+ name: "resumeSchema",
75
+ type: "Zod schema",
76
+ description:
77
+ "A Zod schema defining the expected structure of `resumeData` when the tool is resumed. Used by the agent to extract data from user messages when `autoResumeSuspendedTools` is enabled.",
78
+ isOptional: true,
79
+ },
80
+ {
81
+ name: "requireApproval",
82
+ type: "boolean",
83
+ description:
84
+ "When true, the tool requires explicit approval before execution. The agent will emit a `tool-call-approval` chunk and pause until approved or declined.",
85
+ isOptional: true,
86
+ },
66
87
  {
67
88
  name: "execute",
68
89
  type: "function",
@@ -284,5 +305,6 @@ Hook errors are caught and logged automatically, but do not prevent tool executi
284
305
 
285
306
  - [MCP Overview](/docs/v1/mcp/overview)
286
307
  - [Using Tools with Agents](/docs/v1/agents/using-tools)
308
+ - [Agent Approval](/docs/v1/agents/agent-approval)
287
309
  - [Tool Streaming](/docs/v1/streaming/tool-streaming)
288
- - [Request Context](/docs/v1/server-db/request-context#accessing-values-with-tools)
310
+ - [Request Context](/docs/v1/server/request-context#accessing-values-with-tools)
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  title: "Reference: createGraphRAGTool() | Tools & MCP"
3
- description: Documentation for the Graph RAG Tool in Mastra, which enhances RAG by building a graph of semantic relationships between documents.
3
+ description: Documentation for the GraphRAG Tool in Mastra, which enhances RAG by building a graph of semantic relationships between documents.
4
4
  ---
5
5
 
6
6
  # createGraphRAGTool()
@@ -253,8 +253,8 @@ const response = await agent.generate(
253
253
 
254
254
  For more information on request context, please see:
255
255
 
256
- - [Agent Request Context](/docs/v1/server-db/request-context)
257
- - [Request Context](/docs/v1/server-db/request-context#accessing-values-with-tools)
256
+ - [Agent Request Context](/docs/v1/server/request-context)
257
+ - [Request Context](/docs/v1/server/request-context#accessing-values-with-tools)
258
258
 
259
259
  ## Related
260
260
 
@@ -326,7 +326,7 @@ This agent-driven approach:
326
326
 
327
327
  For detailed filter syntax and store-specific capabilities, see the [Metadata Filters](../rag/metadata-filters) documentation.
328
328
 
329
- For an example of how agent-driven filtering works, see the [Agent-Driven Metadata Filtering](/examples/v1/rag/usage/filter-rag) example.
329
+ For an example of how agent-driven filtering works, see the [Agent-Driven Metadata Filtering](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/filter-rag) example.
330
330
 
331
331
  ## Example with Reranking
332
332
 
@@ -567,8 +567,8 @@ const response = await agent.generate(
567
567
 
568
568
  For more information on request context, please see:
569
569
 
570
- - [Agent Request Context](/docs/v1/server-db/request-context)
571
- - [Request Context](/docs/v1/server-db/request-context#accessing-values-with-tools)
570
+ - [Agent Request Context](/docs/v1/server/request-context)
571
+ - [Request Context](/docs/v1/server/request-context#accessing-values-with-tools)
572
572
 
573
573
  ## Usage Without a Mastra Server
574
574
 
@@ -0,0 +1,143 @@
1
+ ---
2
+ title: "Reference: Run.startAsync() | Workflows"
3
+ description: Documentation for the `Run.startAsync()` method in workflows, which starts a workflow run without waiting for completion (fire-and-forget).
4
+ ---
5
+
6
+ # Run.startAsync()
7
+
8
+ The `.startAsync()` method starts a workflow run without waiting for completion. It returns immediately with the `runId`, allowing the workflow to execute in the background. This is useful for long-running workflows, scheduled tasks, or when you want to avoid blocking on workflow completion.
9
+
10
+ ## Usage example
11
+
12
+ ```typescript showLineNumbers copy
13
+ const run = await workflow.createRun();
14
+
15
+ // Fire-and-forget - returns immediately
16
+ const { runId } = await run.startAsync({
17
+ inputData: {
18
+ value: "initial data",
19
+ },
20
+ });
21
+
22
+ // Optionally poll for completion later
23
+ const result = await workflow.getWorkflowRunExecutionResult(runId);
24
+ ```
25
+
26
+ ## Parameters
27
+
28
+ <PropertiesTable
29
+ content={[
30
+ {
31
+ name: "inputData",
32
+ type: "z.infer<TInput>",
33
+ description: "Input data that matches the workflow's input schema",
34
+ isOptional: true,
35
+ },
36
+ {
37
+ name: "requestContext",
38
+ type: "RequestContext",
39
+ description: "Request Context data to use during workflow execution",
40
+ isOptional: true,
41
+ },
42
+ {
43
+ name: "initialState",
44
+ type: "z.infer<TState>",
45
+ description: "Initial state to use for the workflow execution",
46
+ isOptional: true,
47
+ },
48
+ {
49
+ name: "tracingOptions",
50
+ type: "TracingOptions",
51
+ isOptional: true,
52
+ description: "Options for Tracing configuration.",
53
+ properties: [
54
+ {
55
+ parameters: [
56
+ {
57
+ name: "metadata",
58
+ type: "Record<string, any>",
59
+ isOptional: true,
60
+ description:
61
+ "Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.",
62
+ },
63
+ ],
64
+ },
65
+ {
66
+ parameters: [
67
+ {
68
+ name: "traceId",
69
+ type: "string",
70
+ isOptional: true,
71
+ description:
72
+ "Trace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.",
73
+ },
74
+ ],
75
+ },
76
+ ],
77
+ },
78
+ {
79
+ name: "outputOptions",
80
+ type: "OutputOptions",
81
+ isOptional: true,
82
+ description: "Options for output configuration.",
83
+ properties: [
84
+ {
85
+ parameters: [
86
+ {
87
+ name: "includeState",
88
+ type: "boolean",
89
+ isOptional: true,
90
+ description:
91
+ "Whether to include the workflow run state in the result.",
92
+ },
93
+ ],
94
+ },
95
+ ],
96
+ },
97
+ ]}
98
+ />
99
+
100
+ ## Returns
101
+
102
+ <PropertiesTable
103
+ content={[
104
+ {
105
+ name: "runId",
106
+ type: "string",
107
+ description:
108
+ "The unique identifier for this workflow run. Use this to check status or retrieve results later.",
109
+ },
110
+ ]}
111
+ />
112
+
113
+ ## When to use startAsync()
114
+
115
+ Use `startAsync()` instead of `start()` when:
116
+
117
+ - **Long-running workflows**: The workflow may take minutes or hours to complete
118
+ - **Scheduled/cron triggers**: You want to trigger a workflow without blocking the scheduler
119
+ - **Avoiding polling failures**: With Inngest workflows, `start()` polls for completion which can fail and cause retries. `startAsync()` avoids this issue
120
+ - **Background processing**: You want to queue work and handle results asynchronously
121
+
122
+ ## Checking workflow status
123
+
124
+ After calling `startAsync()`, you can check the workflow status using:
125
+
126
+ ```typescript showLineNumbers copy
127
+ // Get the execution result (including step outputs)
128
+ const result = await workflow.getWorkflowRunExecutionResult(runId);
129
+
130
+ if (result?.status === 'success') {
131
+ console.log('Workflow completed:', result.steps);
132
+ } else if (result?.status === 'failed') {
133
+ console.log('Workflow failed:', result.error);
134
+ } else if (result?.status === 'running') {
135
+ console.log('Workflow still running...');
136
+ }
137
+ ```
138
+
139
+ ## Related
140
+
141
+ - [Run.start()](./start) - Start a workflow and wait for completion
142
+ - [Workflows overview](/docs/v1/workflows/overview)
143
+ - [Workflow.createRun()](../workflow-methods/create-run)
@@ -23,6 +23,18 @@ await workflow.createRun();
23
23
  description: "Optional custom identifier for the workflow run",
24
24
  isOptional: true,
25
25
  },
26
+ {
27
+ name: "resourceId",
28
+ type: "string",
29
+ description: "Optional identifier to associate the workflow run with a specific resource (e.g., user ID, tenant ID). This value is persisted with the workflow run and can be used for filtering and querying runs.",
30
+ isOptional: true,
31
+ },
32
+ {
33
+ name: "disableScorers",
34
+ type: "boolean",
35
+ description: "Optional flag to disable scorers for this workflow run",
36
+ isOptional: true,
37
+ },
26
38
  ]}
27
39
  />
28
40
 
@@ -53,6 +65,29 @@ const result = await run.start({
53
65
  });
54
66
  ```
55
67
 
68
+ ## Using resourceId
69
+
70
+ The `resourceId` parameter associates a workflow run with a specific resource, such as a user or tenant. This is useful for multi-tenant applications or when you need to track which user initiated a workflow.
71
+
72
+ ```typescript showLineNumbers copy
73
+ const workflow = mastra.getWorkflow("workflow");
74
+
75
+ // Create a run associated with a specific user
76
+ const run = await workflow.createRun({
77
+ resourceId: "user-123",
78
+ });
79
+
80
+ const result = await run.start({
81
+ inputData: {
82
+ value: 10,
83
+ },
84
+ });
85
+
86
+ // Later, retrieve the run and access the resourceId
87
+ const storedRun = await workflow.getWorkflowRunById(run.runId);
88
+ console.log(storedRun.resourceId); // "user-123"
89
+ ```
90
+
56
91
  ## Related
57
92
 
58
93
  - [Run Class](../run)
@@ -85,6 +85,20 @@ export const workflow = createWorkflow({
85
85
  isOptional: true,
86
86
  defaultValue: "() => true",
87
87
  },
88
+ {
89
+ name: "onFinish",
90
+ type: "(result: WorkflowFinishCallbackResult) => void | Promise<void>",
91
+ description:
92
+ "Callback invoked when workflow completes with any status (success, failed, suspended, tripwire). Receives the workflow result including status, output, error, and step results. Errors thrown in this callback are caught and logged, not propagated.",
93
+ isOptional: true,
94
+ },
95
+ {
96
+ name: "onError",
97
+ type: "(errorInfo: WorkflowErrorCallbackInfo) => void | Promise<void>",
98
+ description:
99
+ "Callback invoked only when workflow fails (failed or tripwire status). Receives error details and step results. Errors thrown in this callback are caught and logged, not propagated.",
100
+ isOptional: true,
101
+ },
88
102
  ]}
89
103
  />
90
104
 
@@ -170,7 +170,7 @@ export const createMastraClient = (accessToken: string) => {
170
170
 
171
171
  > **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
172
172
 
173
- > See [Mastra Client SDK](/docs/v1/server-db/mastra-client) for more configuration options.
173
+ > See [Mastra Client SDK](/docs/v1/server/mastra-client) for more configuration options.
174
174
 
175
175
  ### Making authenticated requests
176
176
 
@@ -93,7 +93,7 @@ export const mastraClient = new MastraClient({
93
93
  ```
94
94
 
95
95
  > **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
96
- > See [Mastra Client SDK](/docs/v1/server-db/mastra-client) for more configuration options.
96
+ > See [Mastra Client SDK](/docs/v1/server/mastra-client) for more configuration options.
97
97
 
98
98
  ### Making authenticated requests
99
99
 
@@ -190,7 +190,7 @@ export const createMastraClient = (idToken: string) => {
190
190
 
191
191
  > **Note:** The ID token must be prefixed with `Bearer` in the Authorization header.
192
192
 
193
- > See [Mastra Client SDK](/docs/v1/server-db/mastra-client) for more configuration options.
193
+ > See [Mastra Client SDK](/docs/v1/server/mastra-client) for more configuration options.
194
194
 
195
195
  ### Making authenticated requests
196
196
 
@@ -11,9 +11,9 @@ You can start with simple shared secret JWT authentication and switch to provide
11
11
 
12
12
  ## Available providers
13
13
 
14
- - [JSON Web Token (JWT)](/docs/v1/auth/jwt)
15
- - [Clerk](/docs/v1/auth/clerk)
16
- - [Supabase](/docs/v1/auth/supabase)
17
- - [Firebase](/docs/v1/auth/firebase)
18
- - [WorkOS](/docs/v1/auth/workos)
19
- - [Auth0](/docs/v1/auth/auth0)
14
+ - [JSON Web Token (JWT)](/docs/v1/server/auth/jwt)
15
+ - [Clerk](/docs/v1/server/auth/clerk)
16
+ - [Supabase](/docs/v1/server/auth/supabase)
17
+ - [Firebase](/docs/v1/server/auth/firebase)
18
+ - [WorkOS](/docs/v1/server/auth/workos)
19
+ - [Auth0](/docs/v1/server/auth/auth0)
@@ -51,7 +51,7 @@ export const mastraClient = new MastraClient({
51
51
  });
52
52
  ```
53
53
 
54
- > See [Mastra Client SDK](/docs/v1/server-db/mastra-client) for more configuration options.
54
+ > See [Mastra Client SDK](/docs/v1/server/mastra-client) for more configuration options.
55
55
 
56
56
  ### Making authenticated requests
57
57
 
@@ -90,7 +90,7 @@ export const mastraClient = new MastraClient({
90
90
 
91
91
  > **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
92
92
 
93
- > See [Mastra Client SDK](/docs/v1/server-db/mastra-client) for more configuration options.
93
+ > See [Mastra Client SDK](/docs/v1/server/mastra-client) for more configuration options.
94
94
 
95
95
  ### Making authenticated requests
96
96
 
@@ -152,7 +152,7 @@ export const createMastraClient = (accessToken: string) => {
152
152
 
153
153
  > **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
154
154
 
155
- > See [Mastra Client SDK](/docs/v1/server-db/mastra-client) for more configuration options.
155
+ > See [Mastra Client SDK](/docs/v1/server/mastra-client) for more configuration options.
156
156
 
157
157
  ### Making authenticated requests
158
158
 
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: "Custom Adapters | Server & DB"
2
+ title: "Custom Adapters | Server"
3
3
  description: "Create a custom server adapter for frameworks other than Hono or Express."
4
4
  ---
5
5
 
@@ -296,7 +296,7 @@ constructor(options: {
296
296
  }
297
297
  ```
298
298
 
299
- See [Server Adapters](/docs/v1/server-db/server-adapters#constructor-options) for full documentation on each option.
299
+ See [Server Adapters](/docs/v1/server/server-adapters#constructor-options) for full documentation on each option.
300
300
 
301
301
  ## Full example
302
302
 
@@ -379,7 +379,7 @@ The existing [@mastra/hono](https://github.com/mastra-ai/mastra/blob/main/server
379
379
 
380
380
  ## Related
381
381
 
382
- - [Server Adapters](/docs/v1/server-db/server-adapters) - Overview and shared concepts
382
+ - [Server Adapters](/docs/v1/server/server-adapters) - Overview and shared concepts
383
383
  - [Hono Adapter](/reference/v1/server/hono-adapter) - Reference implementation
384
384
  - [Express Adapter](/reference/v1/server/express-adapter) - Reference implementation
385
385
  - [MastraServer Reference](/reference/v1/server/mastra-server) - Full API reference
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: "Custom API Routes | Server & DB"
2
+ title: "Custom API Routes | Server"
3
3
  description: "Expose additional HTTP endpoints from your Mastra server."
4
4
  ---
5
5
 
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: "Mastra Client SDK | Server & DB"
2
+ title: "Mastra Client SDK | Server"
3
3
  description: "Learn how to set up and use the Mastra Client SDK"
4
4
  ---
5
5
 
@@ -8,7 +8,7 @@ import TabItem from "@theme/TabItem";
8
8
 
9
9
  # Mastra Client SDK
10
10
 
11
- The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](/docs/v1/server-db/mastra-server) from your client environment.
11
+ The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](/docs/v1/server/mastra-server) from your client environment.
12
12
 
13
13
  ## Prerequisites
14
14
 
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: "Server Configuration | Server & DB"
2
+ title: "Server Configuration | Server"
3
3
  description: "Configure the Mastra server with custom settings for port, timeout, CORS, and more."
4
4
  ---
5
5
 
@@ -9,7 +9,7 @@ When deploying your Mastra application to production, it runs as an HTTP server
9
9
 
10
10
  :::info
11
11
 
12
- This page covers the `server` configuration options passed to the `Mastra` constructor. For running Mastra with your own HTTP server (Hono, Express, etc.), see [Server Adapters](/docs/v1/server-db/server-adapters).
12
+ This page covers the `server` configuration options passed to the `Mastra` constructor. For running Mastra with your own HTTP server (Hono, Express, etc.), see [Server Adapters](/docs/v1/server/server-adapters).
13
13
 
14
14
  :::
15
15
 
@@ -27,8 +27,8 @@ The server provides:
27
27
  - Configuration of port
28
28
  - Configuration of body limit
29
29
 
30
- See the [Middleware](/docs/v1/server-db/middleware) and
31
- [Custom API Routes](/docs/v1/server-db/custom-api-routes) pages for details on
30
+ See the [Middleware](/docs/v1/server/middleware) and
31
+ [Custom API Routes](/docs/v1/server/custom-api-routes) pages for details on
32
32
  adding additional server behaviour.
33
33
 
34
34
  ## Server configuration
@@ -96,4 +96,4 @@ export const mastra = new Mastra({
96
96
 
97
97
  When streaming agent responses, the HTTP streaming layer redacts system prompts, tool definitions, API keys, and similar data from each chunk before sending it to clients. This is enabled by default.
98
98
 
99
- If you're using server adapters directly, you can configure redaction behavior. See [Stream data redaction](/docs/v1/server-db/server-adapters#stream-data-redaction) in the Server Adapters docs.
99
+ If you're using server adapters directly, you can configure redaction behavior. See [Stream data redaction](/docs/v1/server/server-adapters#stream-data-redaction) in the Server Adapters docs.
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: "Middleware | Server & DB"
2
+ title: "Middleware | Server"
3
3
  description: "Apply custom middleware functions to intercept requests."
4
4
  ---
5
5
 
@@ -174,4 +174,4 @@ be inspected by middleware to tailor behavior:
174
174
 
175
175
  # Related
176
176
 
177
- - [Request Context](/docs/v1/server-db/request-context)
177
+ - [Request Context](/docs/v1/server/request-context)
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: "Request Context | Server & DB"
2
+ title: "Request Context | Server"
3
3
  description: Learn how to use Mastra's RequestContext to provide dynamic, request-specific configuration to agents.
4
4
  ---
5
5
 
@@ -99,7 +99,7 @@ export const mastra = new Mastra({
99
99
  });
100
100
  ```
101
101
 
102
- > See [Middleware](/docs/v1/server-db/middleware) for how to use server middleware.
102
+ > See [Middleware](/docs/v1/server/middleware) for how to use server middleware.
103
103
 
104
104
  ## Accessing values with agents
105
105
 
@@ -190,4 +190,4 @@ export const weatherTool = createTool({
190
190
  - [Agent Request Context](/docs/v1/agents/overview#using-requestcontext)
191
191
  - [Workflow Request Context](../workflows/overview#using-requestcontext)
192
192
  - [Tool Request Context](../mcp/overview#using-requestcontext)
193
- - [Server Middleware](/docs/v1/server-db/middleware)
193
+ - [Server Middleware](/docs/v1/server/middleware)
@@ -1,5 +1,5 @@
1
1
  ---
2
- title: "Server Adapters | Server & DB"
2
+ title: "Server Adapters | Server"
3
3
  description: "Manually configure a Mastra server using Hono or Express adapters."
4
4
  ---
5
5
 
@@ -18,7 +18,7 @@ Server adapters let you run Mastra with your own HTTP server instead of the Hono
18
18
 
19
19
  :::tip
20
20
 
21
- For simple deployments without custom server requirements, use `mastra build` instead. It configures server setup, registers middleware, and applies deployment settings based on your project configuration. See [Server Configuration](/docs/v1/server-db/mastra-server).
21
+ For deployments without custom server requirements, use `mastra build` instead. It configures server setup, registers middleware, and applies deployment settings based on your project configuration. See [Server Configuration](/docs/v1/server/mastra-server).
22
22
 
23
23
  :::
24
24
 
@@ -29,7 +29,7 @@ Mastra currently provides two official server adapters:
29
29
  - [@mastra/express](/reference/v1/server/express-adapter): Express framework adapter
30
30
  - [@mastra/hono](/reference/v1/server/hono-adapter): Hono framework adapter
31
31
 
32
- You can build your own adapter, read [Custom Adapters](/docs/v1/server-db/custom-adapters) for details.
32
+ You can build your own adapter, read [Custom Adapters](/docs/v1/server/custom-adapters) for details.
33
33
 
34
34
  ## Installation
35
35
 
@@ -305,8 +305,8 @@ See [MCP](/docs/v1/mcp/overview) for configuration details and how to set up MCP
305
305
 
306
306
  - [Hono Adapter](/reference/v1/server/hono-adapter) - Hono-specific setup
307
307
  - [Express Adapter](/reference/v1/server/express-adapter) - Express-specific setup
308
- - [Custom Adapters](/docs/v1/server-db/custom-adapters) - Building adapters for other frameworks
309
- - [Server Configuration](/docs/v1/server-db/mastra-server) - Using `mastra build` instead
310
- - [Authentication](/docs/v1/auth) - Configuring auth for your server
308
+ - [Custom Adapters](/docs/v1/server/custom-adapters) - Building adapters for other frameworks
309
+ - [Server Configuration](/docs/v1/server/mastra-server) - Using `mastra build` instead
310
+ - [Authentication](/docs/v1/server/auth) - Configuring auth for your server
311
311
  - [MastraServer Reference](/reference/v1/server/mastra-server) - Full API reference
312
312
  - [createRoute() Reference](/reference/v1/server/create-route) - Creating type-safe custom routes
@@ -56,7 +56,7 @@ To make tools available to an agent, you configure them in the agent's definitio
56
56
 
57
57
  ## Using `RequestContext`
58
58
 
59
- Use [RequestContext](/docs/v1/server-db/request-context) to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
59
+ Use [RequestContext](/docs/v1/server/request-context) to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
60
60
 
61
61
  ```typescript title="src/mastra/tools/test-tool.ts" showLineNumbers
62
62
  export type UserTier = {
@@ -81,7 +81,7 @@ export const testTool = createTool({
81
81
  });
82
82
  ```
83
83
 
84
- > See [Request Context](/docs/v1/server-db/request-context) for more information.
84
+ > See [Request Context](/docs/v1/server/request-context) for more information.
85
85
 
86
86
  ## Testing with Studio
87
87