@mastra/mcp-docs-server 1.0.0-beta.1 → 1.0.0-beta.10

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

@@ -0,0 +1,183 @@
+---
+title: "Reference: Mastra.getStoredAgentById() | Core"
+description: "Documentation for the `Mastra.getStoredAgentById()` method in Mastra, which retrieves an agent from storage and creates an executable Agent instance."
+---
+
+# Mastra.getStoredAgentById()
+
+The `.getStoredAgentById()` method retrieves an agent configuration from storage by its ID and creates an executable `Agent` instance. Stored agents allow you to persist agent configurations in a database and dynamically load them at runtime.
+
+## Usage example
+
+```typescript copy
+// Get an Agent instance from storage
+const agent = await mastra.getStoredAgentById("my-stored-agent");
+
+if (agent) {
+  const response = await agent.generate({ messages: "Hello!" });
+  console.log(response.text);
+}
+```
+
+```typescript copy
+// Get the raw storage data instead of an Agent instance
+const storedConfig = await mastra.getStoredAgentById("my-stored-agent", { raw: true });
+
+if (storedConfig) {
+  console.log(storedConfig.instructions);
+  console.log(storedConfig.createdAt);
+}
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description:
+        "The unique identifier of the stored agent to retrieve.",
+    },
+    {
+      name: "options",
+      type: "{ raw?: boolean }",
+      description:
+        "Optional configuration object.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "raw",
+      type: "boolean",
+      description:
+        "When `true`, returns the raw `StorageAgentType` object from storage instead of creating an `Agent` instance. Useful for inspecting stored configuration or metadata.",
+      isOptional: true,
+      defaultValue: "false",
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "result",
+      type: "Agent | StorageAgentType | null",
+      description:
+        "Returns an `Agent` instance by default, or `StorageAgentType` when `raw: true`. Returns `null` if no agent with the given ID exists.",
+    },
+  ]}
+/>
+
+## Primitive Resolution
+
+When creating an `Agent` instance from stored configuration, the method resolves references to registered primitives:
+
+- **Tools**: Resolved from `tools` registered in Mastra config
+- **Workflows**: Resolved from `workflows` registered in Mastra config
+- **Sub-agents**: Resolved from `agents` registered in Mastra config
+- **Memory**: Resolved from `memory` registered in Mastra config
+- **Scorers**: Resolved from `scorers` registered in Mastra config, including sampling configuration
+
+If a referenced primitive is not found in the registry, a warning is logged but the agent is still created.
+
+## StorageAgentType
+
+When using `raw: true`, the returned object has the following structure:
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier for the agent.",
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Display name of the agent.",
+    },
+    {
+      name: "description",
+      type: "string",
+      description: "Optional description of the agent.",
+      isOptional: true,
+    },
+    {
+      name: "instructions",
+      type: "string",
+      description: "System instructions for the agent.",
+    },
+    {
+      name: "model",
+      type: "Record<string, unknown>",
+      description: "Model configuration with provider and name.",
+    },
+    {
+      name: "tools",
+      type: "Record<string, unknown>",
+      description: "Tool references to resolve from registry.",
+      isOptional: true,
+    },
+    {
+      name: "workflows",
+      type: "Record<string, unknown>",
+      description: "Workflow references to resolve from registry.",
+      isOptional: true,
+    },
+    {
+      name: "agents",
+      type: "Record<string, unknown>",
+      description: "Sub-agent references to resolve from registry.",
+      isOptional: true,
+    },
+    {
+      name: "memory",
+      type: "Record<string, unknown>",
+      description: "Memory reference to resolve from registry.",
+      isOptional: true,
+    },
+    {
+      name: "scorers",
+      type: "Record<string, unknown>",
+      description: "Scorer references with optional sampling config.",
+      isOptional: true,
+    },
+    {
+      name: "defaultOptions",
+      type: "Record<string, unknown>",
+      description: "Default options passed to agent execution.",
+      isOptional: true,
+    },
+    {
+      name: "metadata",
+      type: "Record<string, unknown>",
+      description: "Custom metadata stored with the agent.",
+      isOptional: true,
+    },
+    {
+      name: "createdAt",
+      type: "Date",
+      description: "Timestamp when the agent was created.",
+    },
+    {
+      name: "updatedAt",
+      type: "Date",
+      description: "Timestamp when the agent was last updated.",
+    },
+  ]}
+/>
+
+## Related
+
+- [Mastra.listStoredAgents()](/reference/v1/core/listStoredAgents)
+- [Storage overview](/docs/v1/server-db/storage)
+- [Agents overview](/docs/v1/agents/overview)

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.getTelemetry() | Core | Mastra Docs"
+title: "Reference: Mastra.getTelemetry() | Core"
 description: "Documentation for the `Mastra.getTelemetry()` method in Mastra, which retrieves the configured telemetry instance."
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.getVector() | Core | Mastra Docs"
+title: "Reference: Mastra.getVector() | Core"
 description: "Documentation for the `Mastra.getVector()` method in Mastra, which retrieves a vector store by name."
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.getWorkflow() | Core | Mastra Docs"
+title: "Reference: Mastra.getWorkflow() | Core"
 description: "Documentation for the `Mastra.getWorkflow()` method in Mastra, which retrieves a workflow by ID."
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.listAgents() | Core | Mastra Docs"
+title: "Reference: Mastra.listAgents() | Core"
 description: "Documentation for the `Mastra.listAgents()` method in Mastra, which retrieves all configured agents."
 ---
 

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

@@ -0,0 +1,53 @@
+---
+title: "Reference: Mastra.listGateways() | Core"
+description: "List all registered gateways"
+---
+
+# Mastra.listGateways()
+
+Returns a record of all registered gateways, indexed by their registration keys.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core';
+
+const mastra = new Mastra({
+  gateways: {
+    myGateway: new MyCustomGateway(),
+    anotherGateway: new AnotherGateway(),
+  },
+});
+
+const gateways = mastra.listGateways();
+console.log(Object.keys(gateways)); // ['myGateway', 'anotherGateway']
+
+// Iterate over all gateways
+for (const [key, gateway] of Object.entries(gateways)) {
+  console.log(`${key}: ${gateway.name}`);
+}
+```
+
+## Parameters
+
+None.
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'gateways',
+      type: 'Record<string, MastraModelGateway>',
+      description: 'A record of gateway instances indexed by registration key',
+    },
+  ]}
+/>
+
+## Related
+
+- [Mastra.getGateway()](/reference/v1/core/getGateway) - Get gateway by registration key
+- [Mastra.getGatewayById()](/reference/v1/core/getGatewayById) - Get gateway by ID
+- [Mastra.addGateway()](/reference/v1/core/addGateway) - Add a gateway
+- [MastraModelGateway](/reference/v1/core/mastra-model-gateway) - Gateway base class
+- [Custom Gateways Guide](/models/v1/gateways/custom-gateways) - Creating custom gateways

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.listLogs() | Core | Mastra Docs"
+title: "Reference: Mastra.listLogs() | Core"
 description: "Documentation for the `Mastra.listLogs()` method in Mastra, which retrieves all logs for a specific transport ID."
 ---
 
@@ -92,5 +92,5 @@ mastra.listLogs("456");
 
 ## Related
 
-- [Logging overview](/docs/v1/logging)
+- [Logging overview](/docs/v1/observability/logging)
 - [Logger reference](/reference/v1/logging/pino-logger)

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.listLogsByRunId() | Core | Mastra Docs"
+title: "Reference: Mastra.listLogsByRunId() | Core"
 description: "Documentation for the `Mastra.listLogsByRunId()` method in Mastra, which retrieves logs for a specific run ID and transport ID."
 ---
 
@@ -83,5 +83,5 @@ mastra.listLogsByRunId({ runId: "123", transportId: "456" });
 
 ## Related
 
-- [Logging overview](/docs/v1/logging)
+- [Logging overview](/docs/v1/observability/logging)
 - [Logger reference](/reference/v1/logging/pino-logger)

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.listMCPServers() | Core | Mastra Docs"
+title: "Reference: Mastra.listMCPServers() | Core"
 description: "Documentation for the `Mastra.listMCPServers()` method in Mastra, which retrieves all registered MCP server instances."
 ---
 
@@ -61,5 +61,5 @@ This method does not accept any parameters.
 
 ## See Also
 
-- [MCP overview](/docs/v1/tools-mcp/mcp-overview)
+- [MCP overview](/docs/v1/mcp/overview)
 - [MCP server reference](/reference/v1/tools/mcp-server)

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

@@ -0,0 +1,70 @@
+---
+title: "Reference: Mastra.listMemory() | Core"
+description: "Documentation for the `Mastra.listMemory()` method in Mastra, which returns all registered memory instances."
+---
+
+# Mastra.listMemory()
+
+The `.listMemory()` method returns all memory instances registered with the Mastra instance.
+
+## Usage example
+
+```typescript copy
+const memoryInstances = mastra.listMemory();
+
+for (const [key, memory] of Object.entries(memoryInstances)) {
+  console.log(`Memory "${key}": ${memory.id}`);
+}
+```
+
+## Parameters
+
+This method takes no parameters.
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "memory",
+      type: "Record<string, MastraMemory>",
+      description:
+        "An object containing all registered memory instances, keyed by their registry keys.",
+    },
+  ]}
+/>
+
+## Example: Checking Registered Memory
+
+```typescript copy
+import { Mastra } from "@mastra/core";
+import { Memory } from "@mastra/memory";
+import { LibSQLStore } from "@mastra/libsql";
+
+const conversationMemory = new Memory({
+  id: "conversation-memory",
+  storage: new LibSQLStore({ url: ":memory:" }),
+});
+
+const analyticsMemory = new Memory({
+  id: "analytics-memory",
+  storage: new LibSQLStore({ url: ":memory:" }),
+});
+
+const mastra = new Mastra({
+  memory: {
+    conversationMemory,
+    analyticsMemory,
+  },
+});
+
+// List all registered memory instances
+const allMemory = mastra.listMemory();
+console.log(Object.keys(allMemory)); // ["conversationMemory", "analyticsMemory"]
+```
+
+## Related
+
+- [Mastra.getMemory()](/reference/v1/core/getMemory)
+- [Memory overview](/docs/v1/memory/overview)
+- [Agent Memory](/docs/v1/agents/agent-memory)

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: listScorers() | Core | Mastra Docs"
+title: "Reference: listScorers() | Core"
 description: "Documentation for the `listScorers()` method in Mastra, which returns all registered scorers for evaluating AI outputs."
 ---
 

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

@@ -0,0 +1,151 @@
+---
+title: "Reference: Mastra.listStoredAgents() | Core"
+description: "Documentation for the `Mastra.listStoredAgents()` method in Mastra, which retrieves a paginated list of agents from storage."
+---
+
+# Mastra.listStoredAgents()
+
+The `.listStoredAgents()` method retrieves a paginated list of agent configurations from storage. By default, it returns executable `Agent` instances, but can also return raw storage data.
+
+## Usage example
+
+```typescript copy
+// Get Agent instances from storage
+const { agents, total, hasMore } = await mastra.listStoredAgents();
+
+for (const agent of agents) {
+  console.log(agent.id, agent.name);
+  // Each agent is ready to use
+  // const response = await agent.generate({ messages: "Hello!" });
+}
+```
+
+```typescript copy
+// Get paginated results with raw storage data
+const result = await mastra.listStoredAgents({
+  page: 0,
+  perPage: 10,
+  raw: true,
+});
+
+console.log(`Showing ${result.agents.length} of ${result.total} agents`);
+console.log(`Has more: ${result.hasMore}`);
+
+for (const config of result.agents) {
+  console.log(config.id, config.name, config.createdAt);
+}
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "args",
+      type: "object",
+      description:
+        "Optional configuration object for pagination and output format.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### Args Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "page",
+      type: "number",
+      description: "Zero-indexed page number for pagination.",
+      isOptional: true,
+      defaultValue: "0",
+    },
+    {
+      name: "perPage",
+      type: "number | false",
+      description:
+        "Number of items per page. Set to `false` to fetch all records without pagination.",
+      isOptional: true,
+      defaultValue: "100",
+    },
+    {
+      name: "raw",
+      type: "boolean",
+      description:
+        "When `true`, returns raw `StorageAgentType` objects instead of `Agent` instances.",
+      isOptional: true,
+      defaultValue: "false",
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "agents",
+      type: "Agent[] | StorageAgentType[]",
+      description:
+        "Array of `Agent` instances by default, or `StorageAgentType` objects when `raw: true`.",
+    },
+    {
+      name: "total",
+      type: "number",
+      description: "Total number of stored agents across all pages.",
+    },
+    {
+      name: "page",
+      type: "number",
+      description: "Current page number (zero-indexed).",
+    },
+    {
+      name: "perPage",
+      type: "number | false",
+      description: "Number of items per page, or `false` if fetching all.",
+    },
+    {
+      name: "hasMore",
+      type: "boolean",
+      description: "Whether there are more pages available.",
+    },
+  ]}
+/>
+
+## Primitive Resolution
+
+When creating `Agent` instances (default behavior), each stored agent's configuration is resolved against registered primitives:
+
+- **Tools**: Resolved from `tools` registered in Mastra config
+- **Workflows**: Resolved from `workflows` registered in Mastra config
+- **Sub-agents**: Resolved from `agents` registered in Mastra config
+- **Memory**: Resolved from `memory` registered in Mastra config
+- **Scorers**: Resolved from `scorers` registered in Mastra config
+
+If a referenced primitive is not found, a warning is logged but the agent is still created.
+
+## Example: Iterating Through All Stored Agents
+
+```typescript copy
+async function getAllStoredAgents(mastra: Mastra) {
+  const allAgents: Agent[] = [];
+  let page = 0;
+  let hasMore = true;
+
+  while (hasMore) {
+    const result = await mastra.listStoredAgents({ page, perPage: 50 });
+    allAgents.push(...result.agents);
+    hasMore = result.hasMore;
+    page++;
+  }
+
+  return allAgents;
+}
+```
+
+## Related
+
+- [Mastra.getStoredAgentById()](/reference/v1/core/getStoredAgentById)
+- [Storage overview](/docs/v1/server-db/storage)
+- [Agents overview](/docs/v1/agents/overview)

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.listVectors() | Core | Mastra Docs"
+title: "Reference: Mastra.listVectors() | Core"
 description: "Documentation for the `Mastra.listVectors()` method in Mastra, which retrieves all configured vector stores."
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.listWorkflows() | Core | Mastra Docs"
+title: "Reference: Mastra.listWorkflows() | Core"
 description: "Documentation for the `Mastra.listWorkflows()` method in Mastra, which retrieves all configured workflows."
 ---
 

package/.docs/raw/reference/core/mastra-class.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra Class | Core | Mastra Docs"
+title: "Reference: Mastra Class | Core"
 description: "Documentation for the `Mastra` class in Mastra, the core entry point for managing agents, workflows, MCP servers, and server endpoints."
 ---
 
@@ -140,5 +140,21 @@ export const mastra = new Mastra({
       isOptional: true,
       defaultValue: "{}",
     },
+    {
+      name: "gateways",
+      type: "Record<string, MastraModelGateway>",
+      description:
+        "Custom model gateways to register for accessing AI models through alternative providers or private deployments. Structured as a key-value pair, with keys being the registry key (used for getGateway()) and values being gateway instances.",
+      isOptional: true,
+      defaultValue: "{}",
+    },
+    {
+      name: "memory",
+      type: "Record<string, MastraMemory>",
+      description:
+        "Memory instances to register. These can be referenced by stored agents and resolved at runtime. Structured as a key-value pair, with keys being the registry key and values being memory instances.",
+      isOptional: true,
+      defaultValue: "{}",
+    },
   ]}
 />