@mastra/mcp-docs-server 0.13.39 → 1.0.0-beta.0

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

@@ -5,18 +5,18 @@ description: "API reference for the MastraAuthClerk class, which authenticates M
 
 # MastraAuthClerk Class
 
-The `MastraAuthClerk` class provides authentication for Mastra applications using Clerk. It verifies incoming requests with Clerk-issued JWT tokens and integrates with the Mastra server using the `experimental_auth` option.
+The `MastraAuthClerk` class provides authentication for Mastra applications using Clerk. It verifies incoming requests with Clerk-issued JWT tokens and integrates with the Mastra server using the `auth` option.
 
 ## Usage example
 
 ```typescript title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { MastraAuthClerk } from "@mastra/auth-clerk";
 
 export const mastra = new Mastra({
   // ..
   server: {
-    experimental_auth: new MastraAuthClerk({
+    auth: new MastraAuthClerk({
       jwksUri: process.env.CLERK_JWKS_URI,
       publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
       secretKey: process.env.CLERK_SECRET_KEY,
@@ -71,4 +71,4 @@ export const mastra = new Mastra({
 
 ## Related
 
-[MastraAuthClerk Class](/docs/auth/clerk)
+[MastraAuthClerk Class](/docs/v1/auth/clerk)

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

@@ -5,21 +5,21 @@ description: "API reference for the MastraAuthFirebase class, which authenticate
 
 # MastraAuthFirebase Class
 
-The `MastraAuthFirebase` class provides authentication for Mastra using Firebase Authentication. It verifies incoming requests using Firebase ID tokens and integrates with the Mastra server using the `experimental_auth` option.
+The `MastraAuthFirebase` class provides authentication for Mastra using Firebase Authentication. It verifies incoming requests using Firebase ID tokens and integrates with the Mastra server using the `auth` option.
 
 ## Usage examples
 
 ### Basic usage with environment variables
 
 ```typescript title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
+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: {
-    experimental_auth: new MastraAuthFirebase(),
+    auth: new MastraAuthFirebase(),
   },
 });
 ```
@@ -27,13 +27,13 @@ export const mastra = new Mastra({
 ### Custom configuration
 
 ```typescript title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { MastraAuthFirebase } from "@mastra/auth-firebase";
 
 export const mastra = new Mastra({
   // ..
   server: {
-    experimental_auth: new MastraAuthFirebase({
+    auth: new MastraAuthFirebase({
       serviceAccount: "/path/to/service-account-key.json",
       databaseId: "your-database-id",
     }),
@@ -132,4 +132,4 @@ The `FirebaseUser` type used in the `authorizeUser` function corresponds to Fire
 
 ## Related
 
-[MastraAuthFirebase Class](/docs/auth/firebase)
+[MastraAuthFirebase Class](/docs/v1/auth/firebase)

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

@@ -5,18 +5,18 @@ description: "API reference for the MastraJwtAuth class, which authenticates Mas
 
 # MastraJwtAuth Class
 
-The `MastraJwtAuth` class provides a lightweight authentication mechanism for Mastra using JSON Web Tokens (JWTs). It verifies incoming requests based on a shared secret and integrates with the Mastra server using the `experimental_auth` option.
+The `MastraJwtAuth` class provides a lightweight authentication mechanism for Mastra using JSON Web Tokens (JWTs). It verifies incoming requests based on a shared secret and integrates with the Mastra server using the `auth` option.
 
 ## Usage example
 
 ```typescript title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { MastraJwtAuth } from "@mastra/auth";
 
 export const mastra = new Mastra({
   // ..
   server: {
-    experimental_auth: new MastraJwtAuth({
+    auth: new MastraJwtAuth({
       secret: "<your-secret>",
     }),
   },
@@ -39,4 +39,4 @@ export const mastra = new Mastra({
 
 ## Related
 
-[MastraJwtAuth](/docs/auth/jwt)
+[MastraJwtAuth](/docs/v1/auth/jwt)

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

@@ -5,18 +5,18 @@ description: "API reference for the MastraAuthSupabase class, which authenticate
 
 # MastraAuthSupabase Class
 
-The `MastraAuthSupabase` class provides authentication for Mastra using Supabase Auth. It verifies incoming requests using Supabase's authentication system and integrates with the Mastra server using the `experimental_auth` option.
+The `MastraAuthSupabase` class provides authentication for Mastra using Supabase Auth. It verifies incoming requests using Supabase's authentication system and integrates with the Mastra server using the `auth` option.
 
 ## Usage example
 
 ```typescript title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { MastraAuthSupabase } from "@mastra/auth-supabase";
 
 export const mastra = new Mastra({
   // ..
   server: {
-    experimental_auth: new MastraAuthSupabase({
+    auth: new MastraAuthSupabase({
       url: process.env.SUPABASE_URL,
       anonKey: process.env.SUPABASE_ANON_KEY,
     }),
@@ -62,4 +62,4 @@ export const mastra = new Mastra({
 
 ## Related
 
-[MastraAuthSupabase](/docs/auth/supabase)
+[MastraAuthSupabase](/docs/v1/auth/supabase)

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

@@ -5,18 +5,18 @@ description: "API reference for the MastraAuthWorkos class, which authenticates
 
 # MastraAuthWorkos Class
 
-The `MastraAuthWorkos` class provides authentication for Mastra using WorkOS. It verifies incoming requests using WorkOS access tokens and integrates with the Mastra server using the `experimental_auth` option.
+The `MastraAuthWorkos` class provides authentication for Mastra using WorkOS. It verifies incoming requests using WorkOS access tokens and integrates with the Mastra server using the `auth` option.
 
 ## Usage example
 
 ```typescript title="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
+import { Mastra } from "@mastra/core";
 import { MastraAuthWorkos } from "@mastra/auth-workos";
 
 export const mastra = new Mastra({
   // ..
   server: {
-    experimental_auth: new MastraAuthWorkos({
+    auth: new MastraAuthWorkos({
       apiKey: process.env.WORKOS_API_KEY,
       clientId: process.env.WORKOS_CLIENT_ID,
     }),
@@ -129,4 +129,4 @@ The properties with `urn:myapp:` prefixes are custom claims configured in your W
 
 ## Related
 
-[MastraAuthWorkos Class](/docs/auth/workos)
+[MastraAuthWorkos Class](/docs/v1/auth/workos)

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

@@ -9,9 +9,9 @@ You can use the Command-Line Interface (CLI) provided by Mastra to develop, buil
 
 ## `mastra dev`
 
-Starts a server which exposes [Studio](/docs/getting-started/studio) and REST endpoints for your agents, tools, and workflows. You can visit [http://localhost:4111/swagger-ui](http://localhost:4111/swagger-ui) for an overview of all available endpoints once `mastra dev` is running.
+Starts a server which exposes [Studio]/docs/v1/getting-started/studio) and REST endpoints for your agents, tools, and workflows. You can visit [http://localhost:4111/swagger-ui](http://localhost:4111/swagger-ui) for an overview of all available endpoints once `mastra dev` is running.
 
-You can also [configure the server](/docs/getting-started/studio#configuration).
+You can also [configure the server]/docs/v1/getting-started/studio#configuration).
 
 ### Flags
 
@@ -19,7 +19,7 @@ The command accepts [common flags][common-flags] and the following additional fl
 
 #### `--https`
 
-Enable local HTTPS support. [Learn more](/docs/getting-started/studio#local-https).
+Enable local HTTPS support. [Learn more]/docs/v1/getting-started/studio#local-https).
 
 #### `--inspect`
 
@@ -85,7 +85,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/deployment/serverless-platforms) you need to install the correct deployer in order to receive the correct output in `.mastra`.
+If you're deploying to a [serverless platform]/docs/v1/deployment/serverless-platforms) you need to install the correct deployer in order to receive the correct output in `.mastra`.
 
 It accepts [common flags][common-flags].
 
@@ -109,7 +109,7 @@ You need to run `mastra build` before using `mastra start`.
 
 :::
 
-Starts a local server to serve your built Mastra application in production mode. By default, [OTEL Tracing](/docs/observability/ai-tracing/overview) is enabled.
+Starts a local server to serve your built Mastra application in production mode. By default, [OTEL Tracing]/docs/v1/observability/tracing/overview) is enabled.
 
 ### Flags
 
@@ -121,7 +121,7 @@ The path to your built Mastra output directory. Defaults to `.mastra/output`.
 
 #### `--no-telemetry`
 
-Disable the [OTEL Tracing](/docs/observability/ai-tracing/overview).
+Disable the [OTEL Tracing]/docs/v1/observability/tracing/overview).
 
 ## `mastra lint`
 
@@ -133,7 +133,7 @@ It accepts [common flags][common-flags].
 
 The `mastra scorers` command provides management capabilities for evaluation scorers that measure the quality, accuracy, and performance of AI-generated outputs.
 
-Read the [Scorers overview](/docs/scorers/overview) to learn more.
+Read the [Scorers overview]/docs/v1/evals/overview) to learn more.
 
 ### `add`
 

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

@@ -15,6 +15,8 @@ Retrieve a list of all available agents:
 const agents = await mastraClient.listAgents();
 ```
 
+Returns a record of agent IDs to their serialized agent configurations. See the [Agent class reference](/reference/v1/agents/agent) for details on agent properties.
+
 ## Working with a Specific Agent
 
 Get an instance of a specific agent:
@@ -33,6 +35,8 @@ Retrieve detailed information about an agent:
 const details = await agent.details();
 ```
 
+Returns the serialized agent configuration. See the [Agent class reference](/reference/v1/agents/agent) for details on agent properties.
+
 ### Generate Response
 
 Generate a response from the agent:
@@ -97,8 +101,8 @@ const colorChangeTool = createTool({
   inputSchema: z.object({
     color: z.string(),
   }),
-  execute: async ({ context }) => {
-    document.body.style.backgroundColor = context.color;
+  execute: async (inputData) => {
+    document.body.style.backgroundColor = inputData.color;
     return { success: true };
   },
 });

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

@@ -5,7 +5,7 @@ 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/deployment/server-deployment) from your client environment.
+The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](/docs/v1/deployment/server-deployment) from your client environment.
 
 ## Usage example
 
@@ -150,16 +150,16 @@ export const mastraClient = new MastraClient({
       description: "Returns the list of configured log transport types.",
     },
     {
-      name: "getAITrace(traceId)",
-      type: "Promise<AITraceRecord>",
+      name: "getTrace(traceId)",
+      type: "Promise<TraceRecord>",
       description:
-        "Retrieves a specific AI trace by ID, including all its spans and details.",
+        "Retrieves a specific trace by ID, including all its spans and details.",
     },
     {
-      name: "getAITraces(params)",
-      type: "Promise<GetAITracesResponse>",
+      name: "getTraces(params)",
+      type: "Promise<GetTracesResponse>",
       description:
-        "Retrieves paginated list of AI trace root spans with optional filtering. Use getAITrace() to get complete traces with all spans.",
+        "Retrieves paginated list of trace root spans with optional filtering. Use getTrace() to get complete traces with all spans.",
     },
   ]}
 />

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

@@ -83,8 +83,9 @@ const savedMessages = await mastraClient.saveMessageToMemory({
       content: "Hello!",
       id: "1",
       threadId: "thread-1",
+      resourceId: "resource-1",
       createdAt: new Date(),
-      type: "text",
+      format: 2,
     },
   ],
   agentId: "agent-1",
@@ -96,33 +97,40 @@ const savedMessages = await mastraClient.saveMessageToMemory({
 Get messages associated with a memory thread:
 
 ```typescript
-// Get all messages in the thread
-const { messages } = await thread.getMessages();
+// Get all messages in the thread (paginated)
+const result = await thread.listMessages();
+console.log(result.messages); // Array of messages
+console.log(result.total); // Total count
+console.log(result.hasMore); // Whether more pages exist
+
+// Get messages with pagination
+const result = await thread.listMessages({
+  page: 0,
+  perPage: 20
+});
 
-// Limit the number of messages retrieved
-const { messages } = await thread.getMessages({ limit: 10 });
+// Get messages with ordering
+const result = await thread.listMessages({
+  orderBy: { field: 'createdAt', direction: 'ASC' }
+});
 ```
 
-### Delete a Message
+### Delete Messages
 
-Delete a specific message from a thread:
+Delete one or more messages from a thread:
 
 ```typescript
-const result = await thread.deleteMessage("message-id");
-// Returns: { success: true, message: "Message deleted successfully" }
-```
-
-### Delete Multiple Messages
+// Delete a single message
+const result = await thread.deleteMessages("message-id");
 
-Delete multiple messages from a thread in a single operation:
-
-```typescript
+// Delete multiple messages
 const result = await thread.deleteMessages([
   "message-1",
   "message-2",
   "message-3",
 ]);
-// Returns: { success: true, message: "3 messages deleted successfully" }
+
+// Returns: { success: true, message: "Message deleted successfully" }
 ```
 
 ### Get Memory Status

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

@@ -1,26 +1,26 @@
 ---
 title: "Reference: Observability API | Client SDK | Mastra Docs"
-description: Learn how to retrieve AI traces, monitor application performance, and score traces using the client-js SDK.
+description: Learn how to retrieve traces, monitor application performance, and score traces using the client-js SDK.
 ---
 
 # Observability API
 
-The Observability API provides methods to retrieve AI traces, monitor your application's performance, and score traces for evaluation. This helps you understand how your AI agents and workflows are performing.
+The Observability API provides methods to retrieve traces, monitor your application's performance, and score traces for evaluation. This helps you understand how your AI agents and workflows are performing.
 
-## Getting a Specific AI Trace
+## Getting a Specific Trace
 
-Retrieve a specific AI trace by its ID, including all its spans and details:
+Retrieve a specific trace by its ID, including all its spans and details:
 
 ```typescript
-const trace = await mastraClient.getAITrace("trace-id-123");
+const trace = await mastraClient.getTrace("trace-id-123");
 ```
 
-## Getting AI Traces with Filtering
+## Getting Traces with Filtering
 
-Retrieve a paginated list of AI trace root spans with optional filtering:
+Retrieve a paginated list of trace root spans with optional filtering:
 
 ```typescript
-const traces = await mastraClient.getAITraces({
+const traces = await mastraClient.getTraces({
   pagination: {
     page: 1,
     perPage: 20,
@@ -40,8 +40,8 @@ const traces = await mastraClient.getAITraces({
 console.log(`Found ${traces.spans.length} root spans`);
 console.log(`Total pages: ${traces.pagination.totalPages}`);
 
-// To get the complete trace with all spans, use getAITrace
-const completeTrace = await mastraClient.getAITrace(traces.spans[0].traceId);
+// To get the complete trace with all spans, use getTrace
+const completeTrace = await mastraClient.getTrace(traces.spans[0].traceId);
 ```
 
 ## Scoring Traces
@@ -63,7 +63,7 @@ const result = await mastraClient.score({
 Retrieve scores for a specific span within a trace:
 
 ```typescript
-const scores = await mastraClient.getScoresBySpan({
+const scores = await mastraClient.listScoresBySpan({
   traceId: "trace-123",
   spanId: "span-456",
   page: 1,

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

@@ -44,7 +44,7 @@ const details = await workflow.details();
 Start a workflow run with inputData and await full run results:
 
 ```typescript
-const run = await workflow.createRunAsync();
+const run = await workflow.createRun();
 
 const result = await run.startAsync({
   inputData: {
@@ -58,7 +58,7 @@ const result = await run.startAsync({
 Resume a suspended workflow step and await full run result:
 
 ```typescript
-const run = await workflow.createRunAsync();
+const run = await workflow.createRun();
 
 const result = await run.resumeAsync({
   step: "step-id",
@@ -66,43 +66,15 @@ const result = await run.resumeAsync({
 });
 ```
 
-### Watch Workflow
-
-Watch workflow transitions:
-
-```typescript
-try {
-  const workflow = mastraClient.getWorkflow("testWorkflow");
-
-  const run = await workflow.createRunAsync();
-
-  run.watch((record) => {
-    console.log(record);
-  });
-
-  const result = await run.start({
-    inputData: {
-      city: "New York",
-    },
-  });
-} catch (e) {
-  console.error(e);
-}
-```
-
 ### Resume Workflow
 
-Resume workflow run and watch workflow step transitions:
+Resume workflow run:
 
 ```typescript
 try {
   const workflow = mastraClient.getWorkflow("testWorkflow");
 
-  const run = await workflow.createRunAsync({ runId: prevRunId });
-
-  run.watch((record) => {
-    console.log(record);
-  });
+  const run = await workflow.createRun({ runId: prevRunId });
 
   run.resume({
     step: "step-id",
@@ -121,7 +93,7 @@ Stream workflow execution for real-time updates:
 try {
   const workflow = mastraClient.getWorkflow("testWorkflow");
 
-  const run = await workflow.createRunAsync();
+  const run = await workflow.createRun();
 
   const stream = await run.stream({
     inputData: {
@@ -145,7 +117,7 @@ Get the result of a workflow run:
 try {
   const workflow = mastraClient.getWorkflow("testWorkflow");
 
-  const run = await workflow.createRunAsync();
+  const run = await workflow.createRun();
 
   // start the workflow run
   const startResult = await run.start({

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

@@ -41,4 +41,4 @@ mastra.getAgent("testAgent");
 
 ## Related
 
-- [Agents overview](/docs/agents/overview)
+- [Agents overview](/docs/v1/agents/overview)

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

@@ -41,4 +41,4 @@ mastra.getAgentById("test-agent-123");
 
 ## Related
 
-- [Agents overview](/docs/agents/overview)
+- [Agents overview](/docs/v1/agents/overview)

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

@@ -32,5 +32,5 @@ This method does not accept any parameters.
 
 ## Related
 
-- [Deployment overview](/docs/deployment/overview)
-- [Deployer reference](/reference/deployer/)
+- [Deployment overview](/docs/v1/deployment/overview)
+- [Deployer reference](/reference/v1/deployer/)

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

@@ -32,5 +32,5 @@ This method does not accept any parameters.
 
 ## Related
 
-- [Logging overview](/docs/observability/logging)
-- [Logger reference](/reference/observability/logging/pino-logger)
+- [Logging overview]/docs/v1/logging)
+- [Logger reference]/reference/v1/logging/pino-logger)

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

@@ -5,12 +5,30 @@ description: "Documentation for the `Mastra.getMCPServer()` method in Mastra, wh
 
 # Mastra.getMCPServer()
 
-The `.getMCPServer()` method is used to retrieve a specific MCP server instance by its logical ID and optional version. If a version is provided, it attempts to find the server with that exact logical ID and version. If no version is provided, it returns the server with the specified logical ID that has the most recent releaseDate.
+The `.getMCPServer()` method retrieves an MCP server instance by its registry key (the key used when registering the server in the `mcpServers` configuration). For retrieving by the server's intrinsic `id` property, use `.getMCPServerById()` instead.
 
 ## Usage example
 
 ```typescript copy
-mastra.getMCPServer("1.2.0");
+// Register an MCP server with a registry key
+const myServer = new MCPServer({
+  id: 'my-mcp-server',
+  name: 'My Server',
+  version: '1.0.0',
+  tools: { /* ... */ },
+});
+
+export const mastra = new Mastra({
+  mcpServers: {
+    customKey: myServer,  // 'customKey' is the registry key
+  },
+});
+
+// Retrieve by registry key
+const server = mastra.getMCPServer('customKey');
+
+// Alternatively, retrieve by intrinsic ID
+const serverById = mastra.getMCPServerById('my-mcp-server');
 ```
 
 ## Parameters
@@ -18,17 +36,10 @@ mastra.getMCPServer("1.2.0");
 <PropertiesTable
   content={[
     {
-      name: "serverId",
+      name: "registryKey",
       type: "string",
       description:
-        "The logical ID of the MCP server to retrieve. Should match the `id` property of the MCPServer instance.",
-    },
-    {
-      name: "version",
-      type: "string",
-      description:
-        "Optional specific version of the MCP server to retrieve. If not provided, returns the server with the most recent releaseDate.",
-      optional: true,
+        "The registry key used when registering the MCP server in the mcpServers configuration object. This is the key in the key-value pair, not the server's intrinsic id property.",
     },
   ]}
 />
@@ -41,12 +52,17 @@ mastra.getMCPServer("1.2.0");
       name: "server",
       type: "MCPServerBase | undefined",
       description:
-        "The MCP server instance with the specified ID and version, or undefined if not found or if the specific version is not found.",
+        "The MCP server instance with the specified registry key, or undefined if not found.",
     },
   ]}
 />
 
-## Related
+## Related Methods
+
+- [Mastra.getMCPServerById()]/reference/v1/core/getMCPServerById) - Retrieve an MCP server by its intrinsic `id` property
+- [Mastra.listMCPServers()]/reference/v1/core/listMCPServers) - List all registered MCP servers
+
+## See Also
 
-- [MCP overview](/docs/tools-mcp/mcp-overview)
-- [MCP server reference](/reference/tools/mcp-server)
+- [MCP overview](/docs/v1/tools-mcp/mcp-overview)
+- [MCP server reference](/reference/v1/tools/mcp-server)