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

package/.docs/raw/reference/ai-sdk/to-ai-sdk-v5-messages.mdx

@@ -0,0 +1,107 @@
+---
+title: "Reference: toAISdkV5Messages() | AI SDK"
+description: API reference for toAISdkV5Messages(), a function to convert Mastra messages to AI SDK v5 UI messages.
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# toAISdkV5Messages()
+
+Converts messages from various input formats to AI SDK V5 UI message format. This function accepts messages in multiple formats (strings, AI SDK V4/V5 messages, Mastra DB messages, etc.) and normalizes them to the AI SDK V5 `UIMessage` format, which is suitable for use with AI SDK UI components like `useChat()`.
+
+## Usage example
+
+```typescript title="app/chat/page.tsx"
+import { toAISdkV5Messages } from "@mastra/ai-sdk";
+import { useChat } from "ai/react";
+
+// Stored messages from your database, memory or API
+const storedMessages = [
+  { id: "1", role: "user", content: "Hello", parts: [{ type: "text", text: "Hello" }] },
+  { id: "2", role: "assistant", content: "Hi there!", parts: [{ type: "text", text: "Hi there!" }] }
+];
+
+export default function Chat() {
+  const { messages } = useChat({
+    initialMessages: toAISdkV5Messages(storedMessages)
+  });
+
+  return (
+    <div>
+      {messages.map((message) => (
+        <div key={message.id}>
+          {message.role}: {message.parts.map(part => 
+            part.type === "text" ? part.text : null
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "messages",
+      type: "MessageListInput",
+      description: "Messages to convert. Can be a string, array of strings, a single message object, or an array of message objects in any supported format.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+Returns an array of AI SDK V5 `UIMessage` objects with the following structure:
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique message identifier.",
+    },
+    {
+      name: "role",
+      type: "'user' | 'assistant' | 'system'",
+      description: "The role of the message sender.",
+    },
+    {
+      name: "parts",
+      type: "UIMessagePart[]",
+      description: "Array of UI parts including text, tool results, files, reasoning, sources, and step markers.",
+    },
+    {
+      name: "metadata",
+      type: "Record<string, unknown>",
+      description: "Optional metadata including createdAt, threadId, resourceId, and custom fields.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Examples
+
+### Converting simple text messages
+
+```typescript
+import { toAISdkV5Messages } from "@mastra/ai-sdk";
+
+const messages = toAISdkV5Messages(["Hello", "How can I help you today?"]);
+// Returns array of UIMessage objects with user role
+```
+
+### Loading messages with Mastra client
+
+```typescript
+import { MastraClient } from "@mastra/client-js";
+import { toAISdkV5Messages } from "@mastra/ai-sdk";
+
+const client = new MastraClient();
+
+const { messages } = await client.listThreadMessages("thread-id", { agentId: "myAgent" });
+const uiMessages = toAISdkV5Messages(messages);
+```

package/.docs/raw/reference/ai-sdk/with-mastra.mdx

@@ -11,7 +11,7 @@ Wraps an AI SDK model with Mastra processors and/or memory.
 
 ## Usage example
 
-```typescript title="src/example.ts" copy
+```typescript title="src/example.ts"
 import { openai } from '@ai-sdk/openai';
 import { generateText } from 'ai';
 import { withMastra } from '@mastra/ai-sdk';

package/.docs/raw/reference/ai-sdk/workflow-route.mdx

@@ -7,7 +7,7 @@ import PropertiesTable from "@site/src/components/PropertiesTable";
 
 # workflowRoute()
 
-Creates a workflow route handler for streaming workflow execution using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts input data, executes a workflow, and streams the response back to the client in AI SDK-compatible format. You have to use it inside a [custom API route](/docs/v1/server-db/custom-api-routes).
+Creates a workflow route handler for streaming workflow execution using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts input data, executes a workflow, and streams the response back to the client in AI SDK-compatible format. You have to use it inside a [custom API route](/docs/v1/server/custom-api-routes).
 
 Use [`handleWorkflowStream()`](/reference/v1/ai-sdk/handle-workflow-stream) if you need a framework-agnostic handler.
 
@@ -23,7 +23,7 @@ See [Workflow Streaming](/docs/v1/streaming/workflow-streaming#streaming-agent-t
 
 This example shows how to set up a workflow route at the `/workflow` endpoint that uses a workflow with the ID `weatherWorkflow`.
 
-```typescript title="src/mastra/index.ts" copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { workflowRoute } from "@mastra/ai-sdk";
 
@@ -41,7 +41,7 @@ export const mastra = new Mastra({
 
 You can also use dynamic workflow routing based on a `workflowId`. The URL `/workflow/weatherWorkflow` will resolve to the workflow with the ID `weatherWorkflow`.
 
-```typescript title="src/mastra/index.ts" copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { workflowRoute } from "@mastra/ai-sdk";
 

package/.docs/raw/reference/auth/auth0.mdx

@@ -9,12 +9,11 @@ The `MastraAuthAuth0` class provides authentication for Mastra using Auth0. It v
 
 ## Usage example
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { MastraAuthAuth0 } from "@mastra/auth-auth0";
 
 export const mastra = new Mastra({
-  // ..
   server: {
     auth: new MastraAuthAuth0({
       domain: process.env.AUTH0_DOMAIN,
@@ -118,4 +117,4 @@ The exact properties available depend on your Auth0 configuration, scopes reques
 
 ## Related
 
-[MastraAuthAuth0 Class](/docs/v1/auth/auth0)
+[MastraAuthAuth0 Class](/docs/v1/server/auth/auth0)

package/.docs/raw/reference/auth/clerk.mdx

@@ -9,12 +9,11 @@ The `MastraAuthClerk` class provides authentication for Mastra applications usin
 
 ## Usage example
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { MastraAuthClerk } from "@mastra/auth-clerk";
 
 export const mastra = new Mastra({
-  // ..
   server: {
     auth: new MastraAuthClerk({
       jwksUri: process.env.CLERK_JWKS_URI,
@@ -71,4 +70,4 @@ export const mastra = new Mastra({
 
 ## Related
 
-[MastraAuthClerk Class](/docs/v1/auth/clerk)
+[MastraAuthClerk Class](/docs/v1/server/auth/clerk)

package/.docs/raw/reference/auth/firebase.mdx

@@ -11,13 +11,12 @@ The `MastraAuthFirebase` class provides authentication for Mastra using Firebase
 
 ### Basic usage with environment variables
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { MastraAuthFirebase } from "@mastra/auth-firebase";
 
 // Automatically uses FIREBASE_SERVICE_ACCOUNT and FIRESTORE_DATABASE_ID env vars
 export const mastra = new Mastra({
-  // ..
   server: {
     auth: new MastraAuthFirebase(),
   },
@@ -26,12 +25,11 @@ export const mastra = new Mastra({
 
 ### Custom configuration
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { MastraAuthFirebase } from "@mastra/auth-firebase";
 
 export const mastra = new Mastra({
-  // ..
   server: {
     auth: new MastraAuthFirebase({
       serviceAccount: "/path/to/service-account-key.json",
@@ -132,4 +130,4 @@ The `FirebaseUser` type used in the `authorizeUser` function corresponds to Fire
 
 ## Related
 
-[MastraAuthFirebase Class](/docs/v1/auth/firebase)
+[MastraAuthFirebase Class](/docs/v1/server/auth/firebase)

package/.docs/raw/reference/auth/jwt.mdx

@@ -9,12 +9,11 @@ The `MastraJwtAuth` class provides a lightweight authentication mechanism for Ma
 
 ## Usage example
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { MastraJwtAuth } from "@mastra/auth";
 
 export const mastra = new Mastra({
-  // ..
   server: {
     auth: new MastraJwtAuth({
       secret: "<your-secret>",
@@ -39,4 +38,4 @@ export const mastra = new Mastra({
 
 ## Related
 
-[MastraJwtAuth](/docs/v1/auth/jwt)
+[MastraJwtAuth](/docs/v1/server/auth/jwt)

package/.docs/raw/reference/auth/supabase.mdx

@@ -9,12 +9,11 @@ The `MastraAuthSupabase` class provides authentication for Mastra using Supabase
 
 ## Usage example
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { MastraAuthSupabase } from "@mastra/auth-supabase";
 
 export const mastra = new Mastra({
-  // ..
   server: {
     auth: new MastraAuthSupabase({
       url: process.env.SUPABASE_URL,
@@ -62,4 +61,4 @@ export const mastra = new Mastra({
 
 ## Related
 
-[MastraAuthSupabase](/docs/v1/auth/supabase)
+[MastraAuthSupabase](/docs/v1/server/auth/supabase)

package/.docs/raw/reference/auth/workos.mdx

@@ -9,12 +9,11 @@ The `MastraAuthWorkos` class provides authentication for Mastra using WorkOS. It
 
 ## Usage example
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { MastraAuthWorkos } from "@mastra/auth-workos";
 
 export const mastra = new Mastra({
-  // ..
   server: {
     auth: new MastraAuthWorkos({
       apiKey: process.env.WORKOS_API_KEY,
@@ -129,4 +128,4 @@ The properties with `urn:myapp:` prefixes are custom claims configured in your W
 
 ## Related
 
-[MastraAuthWorkos Class](/docs/v1/auth/workos)
+[MastraAuthWorkos Class](/docs/v1/server/auth/workos)

package/.docs/raw/reference/cli/create-mastra.mdx

@@ -15,28 +15,28 @@ The `create-mastra` command **creates** a new standalone Mastra project. Use thi
 <Tabs>
 <TabItem value="npm" label="npm">
 
-```bash copy
+```bash
 npx create-mastra@beta
 ```
 
 </TabItem>
 <TabItem value="yarn" label="yarn">
 
-```bash copy
+```bash
 yarn dlx create-mastra@beta
 ```
 
 </TabItem>
 <TabItem value="pnpm" label="pnpm">
 
-```bash copy
+```bash
 pnpm create mastra@beta
 ```
 
 </TabItem>
 <TabItem value="bun" label="bun">
 
-```bash copy
+```bash
 bun create mastra@beta
 ```
 
@@ -48,28 +48,28 @@ bun create mastra@beta
 <Tabs>
 <TabItem value="npm" label="npm">
 
-```bash copy
+```bash
 npx create-mastra@beta my-mastra-project -- --template coding-agent
 ```
 
 </TabItem>
 <TabItem value="yarn" label="yarn">
 
-```bash copy
+```bash
 yarn dlx create-mastra@beta --template coding-agent
 ```
 
 </TabItem>
 <TabItem value="pnpm" label="pnpm">
 
-```bash copy
+```bash
 pnpm create mastra@beta --template coding-agent
 ```
 
 </TabItem>
 <TabItem value="bun" label="bun">
 
-```bash copy
+```bash
 bun create mastra@beta --template coding-agent
 ```
 
@@ -183,12 +183,12 @@ By default, Mastra collects anonymous information about your project like your O
 
 You can opt out of the CLI analytics by setting an environment variable:
 
-```bash copy
+```bash
 MASTRA_TELEMETRY_DISABLED=1
 ```
 
 You can also set this while using other `mastra` commands:
 
-```bash copy
+```bash
 MASTRA_TELEMETRY_DISABLED=1 npx create-mastra@beta
 ```

package/.docs/raw/reference/cli/mastra.mdx

@@ -41,7 +41,7 @@ You can set certain environment variables to modify the behavior of `mastra dev`
 
 Set `MASTRA_DEV_NO_CACHE=1` to force a full rebuild rather than using the cached assets under `.mastra/`:
 
-```bash copy
+```bash
 MASTRA_DEV_NO_CACHE=1 mastra dev
 ```
 
@@ -51,7 +51,7 @@ This helps when you are debugging bundler plugins or suspect stale output.
 
 `MASTRA_CONCURRENCY` caps how many expensive operations run in parallel (primarily build and evaluation steps). For example:
 
-```bash copy
+```bash
 MASTRA_CONCURRENCY=4 mastra dev
 ```
 
@@ -61,7 +61,7 @@ Leave it unset to let the CLI pick a sensible default for the machine.
 
 When using providers supported by the Vercel AI SDK you can redirect requests through proxies or internal gateways by setting a base URL. For OpenAI:
 
-```bash copy
+```bash
 OPENAI_API_KEY=<your-api-key> \
 OPENAI_BASE_URL=https://openrouter.example/v1 \
 mastra dev
@@ -69,7 +69,7 @@ mastra dev
 
 For Anthropic:
 
-```bash copy
+```bash
 ANTHROPIC_API_KEY=<your-api-key> \
 ANTHROPIC_BASE_URL=https://anthropic.internal \
 mastra dev
@@ -86,7 +86,7 @@ Under the hood Mastra's Rollup server locates your Mastra entry file and bundles
 
 The output in `.mastra` can be deployed to any cloud server using [`mastra start`](#mastra-start).
 
-If you're deploying to a [serverless platform](/docs/v1/deployment/cloud-providers) you need to install the correct deployer in order to receive the correct output in `.mastra`.
+If you're deploying to a [serverless platform](/guides/v1/deployment) you need to install the correct deployer in order to receive the correct output in `.mastra`.
 
 It accepts [common flags][common-flags].
 
@@ -98,7 +98,7 @@ You can set certain environment variables to modify the behavior of `mastra buil
 
 For CI or when running in resource constrained environments you can cap how many expensive tasks run at once by setting `MASTRA_CONCURRENCY`.
 
-```bash copy
+```bash
 MASTRA_CONCURRENCY=2 mastra build
 ```
 
@@ -152,13 +152,13 @@ Read the [Scorers overview](/docs/v1/evals/overview) to learn more.
 
 Add a new scorer to your project. You can use an interactive prompt:
 
-```bash copy
+```bash
 mastra scorers add
 ```
 
 Or provide a scorer name directly:
 
-```bash copy
+```bash
 mastra scorers add answer-relevancy
 ```
 
@@ -258,13 +258,13 @@ By default, Mastra collects anonymous information about your project like your O
 
 You can opt out of the CLI analytics by setting an environment variable:
 
-```bash copy
+```bash
 MASTRA_TELEMETRY_DISABLED=1
 ```
 
 You can also set this while using other `mastra` commands:
 
-```bash copy
+```bash
 MASTRA_TELEMETRY_DISABLED=1 mastra dev
 ```
 

package/.docs/raw/reference/client-js/agents.mdx

@@ -24,7 +24,6 @@ Get an instance of a specific agent by its ID:
 ```typescript title="src/mastra/agents/my-agent.ts"
 export const myAgent = new Agent({
   id: "my-agent",
-  // ...
 });
 ```
 
@@ -123,7 +122,7 @@ while (true) {
 
 To stream AI SDK-formatted parts on the client from an `agent.stream(...)` response, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and use `toAISdkStream`:
 
-```typescript title="client-ai-sdk-transform.ts" copy
+```typescript title="client-ai-sdk-transform.ts"
 import { createUIMessageStream } from "ai";
 import { toAISdkStream } from "@mastra/ai-sdk";
 import type { ChunkType, MastraModelOutput } from "@mastra/core/stream";

package/.docs/raw/reference/client-js/mastra-client.mdx

@@ -5,11 +5,11 @@ description: Learn how to interact with Mastra using the client-js SDK.
 
 # Mastra Client SDK
 
-The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](/docs/v1/deployment/building-mastra) from your client environment.
+The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](/docs/v1/deployment/mastra-server) from your client environment.
 
 ## Usage example
 
-```typescript title="lib/mastra/mastra-client.ts" showLineNumbers copy
+```typescript title="lib/mastra/mastra-client.ts"
 import { MastraClient } from "@mastra/client-js";
 
 export const mastraClient = new MastraClient({

package/.docs/raw/reference/client-js/workflows.mdx

@@ -48,8 +48,16 @@ const run = await workflow.createRun();
 
 // Or with an existing runId
 const run = await workflow.createRun({ runId: "existing-run-id" });
+
+// Or with a resourceId to associate the run with a specific resource
+const run = await workflow.createRun({
+  runId: "my-run-id",
+  resourceId: "user-123"
+});
 ```
 
+The `resourceId` parameter associates the workflow run with a specific resource (e.g., user ID, tenant ID). This value is persisted with the run and can be used for filtering and querying runs later.
+
 ### startAsync()
 
 Start a workflow run and await the full result:
@@ -80,6 +88,18 @@ const result = await run.startAsync({
 
 The `initialState` object should match the structure defined in the workflow's `stateSchema`. See [Workflow State](/docs/v1/workflows/workflow-state) for more details.
 
+To associate a run with a specific resource, pass `resourceId` to `createRun()`:
+
+```typescript
+const run = await workflow.createRun({ resourceId: "user-123" });
+
+const result = await run.startAsync({
+  inputData: {
+    city: "New York",
+  },
+});
+```
+
 ### start()
 
 Start a workflow run without waiting for completion:

package/.docs/raw/reference/core/getAgent.mdx

@@ -9,7 +9,7 @@ The `.getAgent()` method is used to retrieve an agent. The method accepts a sing
 
 ## Usage example
 
-```typescript copy
+```typescript
 mastra.getAgent("testAgent");
 ```
 

package/.docs/raw/reference/core/getAgentById.mdx

@@ -9,7 +9,7 @@ The `.getAgentById()` method is used to retrieve an agent by its ID. The method
 
 ## Usage example
 
-```typescript copy
+```typescript
 mastra.getAgentById("test-agent-123");
 ```
 

package/.docs/raw/reference/core/getDeployer.mdx

@@ -9,7 +9,7 @@ The `.getDeployer()` method is used to retrieve the deployer instance that has b
 
 ## Usage example
 
-```typescript copy
+```typescript
 mastra.getDeployer();
 ```
 

package/.docs/raw/reference/core/getLogger.mdx

@@ -9,7 +9,7 @@ The `.getLogger()` method is used to retrieve the logger instance that has been
 
 ## Usage example
 
-```typescript copy
+```typescript
 mastra.getLogger();
 ```
 

package/.docs/raw/reference/core/getMCPServer.mdx

@@ -9,7 +9,7 @@ The `.getMCPServer()` method retrieves an MCP server instance by its registry ke
 
 ## Usage example
 
-```typescript copy
+```typescript
 // Register an MCP server with a registry key
 const myServer = new MCPServer({
   id: 'my-mcp-server',

package/.docs/raw/reference/core/getMCPServerById.mdx

@@ -9,7 +9,7 @@ The `.getMCPServerById()` method retrieves an MCP server instance by its intrins
 
 ## Usage example
 
-```typescript copy
+```typescript
 // Register an MCP server with a registry key
 const myServer = new MCPServer({
   id: 'my-mcp-server',

package/.docs/raw/reference/core/getMemory.mdx

@@ -9,7 +9,7 @@ The `.getMemory()` method retrieves a memory instance from the Mastra registry b
 
 ## Usage example
 
-```typescript copy
+```typescript
 const memory = mastra.getMemory("conversationMemory");
 
 // Use the memory instance
@@ -47,7 +47,7 @@ const thread = await memory.createThread({
 
 ## Example: Registering and Retrieving Memory
 
-```typescript copy
+```typescript
 import { Mastra } from "@mastra/core";
 import { Memory } from "@mastra/memory";
 import { LibSQLStore } from "@mastra/libsql";

package/.docs/raw/reference/core/getServer.mdx

@@ -9,7 +9,7 @@ The `.getServer()` method is used to retrieve the server configuration that has
 
 ## Usage example
 
-```typescript copy
+```typescript
 mastra.getServer();
 ```
 
@@ -32,5 +32,5 @@ This method does not accept any parameters.
 
 ## Related
 
-- [Server deployment](/docs/v1/deployment/building-mastra)
-- [Server configuration](/docs/v1/server-db/custom-api-routes)
+- [Server deployment](/docs/v1/deployment/mastra-server)
+- [Server configuration](/docs/v1/server/custom-api-routes)

package/.docs/raw/reference/core/getStorage.mdx

@@ -9,7 +9,7 @@ The `.getStorage()` method is used to retrieve the storage instance that has bee
 
 ## Usage example
 
-```typescript copy
+```typescript
 mastra.getStorage();
 ```
 
@@ -32,5 +32,5 @@ This method does not accept any parameters.
 
 ## Related
 
-- [Storage overview](/docs/v1/server-db/storage)
+- [Storage overview](/reference/v1/storage/overview)
 - [Storage reference](/reference/v1/storage/libsql)

package/.docs/raw/reference/core/getStoredAgentById.mdx

@@ -9,7 +9,7 @@ The `.getStoredAgentById()` method retrieves an agent configuration from storage
 
 ## Usage example
 
-```typescript copy
+```typescript
 // Get an Agent instance from storage
 const agent = await mastra.getStoredAgentById("my-stored-agent");
 
@@ -19,7 +19,7 @@ if (agent) {
 }
 ```
 
-```typescript copy
+```typescript
 // Get the raw storage data instead of an Agent instance
 const storedConfig = await mastra.getStoredAgentById("my-stored-agent", { raw: true });
 
@@ -179,5 +179,5 @@ When using `raw: true`, the returned object has the following structure:
 ## Related
 
 - [Mastra.listStoredAgents()](/reference/v1/core/listStoredAgents)
-- [Storage overview](/docs/v1/server-db/storage)
+- [Storage overview](/reference/v1/storage/overview)
 - [Agents overview](/docs/v1/agents/overview)

package/.docs/raw/reference/core/getTelemetry.mdx

@@ -9,7 +9,7 @@ The `.getTelemetry()` method is used to retrieve the telemetry instance that has
 
 ## Usage example
 
-```typescript copy
+```typescript
 mastra.getTelemetry();
 ```