@mastra/mcp-docs-server 1.0.0-beta.2 → 1.0.0-beta.3

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

@@ -0,0 +1,62 @@
+---
+title: "Reference: Mastra.getGatewayById() | Core"
+description: "Retrieve a registered gateway by its unique ID"
+---
+
+# Mastra.getGatewayById()
+
+Retrieves a gateway by its unique ID (the `id` property of the gateway instance). This is useful when you need to find a gateway by its intrinsic identifier rather than its registration key.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core';
+
+const mastra = new Mastra({
+  gateways: {
+    customKey: new MyCustomGateway(), // id = 'my-custom-gateway'
+  },
+});
+
+// Retrieve by ID (not registration key)
+const gateway = mastra.getGatewayById('my-custom-gateway');
+console.log(gateway.name); // 'My Custom Gateway'
+```
+
+## Use Cases
+
+- Gateway versioning: Different versions with unique IDs (`'gateway-v1'`, `'gateway-v2'`)
+- Finding gateways when registration keys are unknown
+- Identifying gateways across different Mastra instances
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'id',
+      type: 'string',
+      description: 'The unique ID of the gateway (gateway.id property)',
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'gateway',
+      type: 'MastraModelGateway | undefined',
+      description: 'The gateway instance, or undefined if not found',
+    },
+  ]}
+/>
+
+## Related
+
+- [Mastra.getGateway()](/reference/v1/core/getGateway) - Get gateway by registration key
+- [Mastra.listGateways()](/reference/v1/core/listGateways) - List all gateways
+- [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/getLogger.mdx

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

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.getMCPServer() | Core | Mastra Docs"
+title: "Reference: Mastra.getMCPServer() | Core"
 description: "Documentation for the `Mastra.getMCPServer()` method in Mastra, which retrieves a specific MCP server instance by ID and optional version."
 ---
 
@@ -64,5 +64,5 @@ const serverById = mastra.getMCPServerById('my-mcp-server');
 
 ## 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/getMCPServerById.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.getMCPServerById() | Core | Mastra Docs"
+title: "Reference: Mastra.getMCPServerById() | Core"
 description: "Documentation for the `Mastra.getMCPServerById()` method in Mastra, which retrieves a specific MCP server instance by its intrinsic id property."
 ---
 
@@ -77,5 +77,5 @@ const serverByKey = mastra.getMCPServer('customKey');
 
 ## 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/getScorer.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: getScorer() | Core | Mastra Docs"
+title: "Reference: getScorer() | Core"
 description: "Documentation for the `getScorer()` method in Mastra, which retrieves a specific scorer by its registration key."
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: getScorerById() | Core | Mastra Docs"
+title: "Reference: getScorerById() | Core"
 description: "Documentation for the `getScorerById()` method in Mastra, which retrieves a scorer by its id property rather than registration key."
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.getServer() | Core | Mastra Docs"
+title: "Reference: Mastra.getServer() | Core"
 description: "Documentation for the `Mastra.getServer()` method in Mastra, which retrieves the configured server configuration."
 ---
 
@@ -32,5 +32,5 @@ This method does not accept any parameters.
 
 ## Related
 
-- [Server deployment](/docs/v1/deployment/server-deployment)
+- [Server deployment](/docs/v1/deployment/building-mastra)
 - [Server configuration](/docs/v1/server-db/custom-api-routes)

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

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

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."
 ---
 

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."
 ---
 

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/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/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,13 @@ 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: "{}",
+    },
   ]}
 />

package/.docs/raw/reference/core/mastra-model-gateway.mdx

@@ -0,0 +1,241 @@
+---
+title: "Reference: MastraModelGateway | Core"
+description: "Base class for creating custom model gateways"
+---
+
+# MastraModelGateway
+
+Abstract base class for implementing custom model gateways. Gateways handle provider-specific logic for accessing language models, including provider configuration, authentication, URL construction, and model instantiation.
+
+## Class Overview
+
+```typescript
+import { MastraModelGateway, type ProviderConfig } from '@mastra/core/llm';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible-v5';
+import type { LanguageModelV2 } from '@ai-sdk/provider-v5';
+
+class MyCustomGateway extends MastraModelGateway {
+  readonly id = 'my-custom-gateway';
+  readonly name = 'My Custom Gateway';
+  readonly prefix = 'custom';
+
+  async fetchProviders(): Promise<Record<string, ProviderConfig>> {
+    return {
+      'my-provider': {
+        name: 'My Provider',
+        models: ['model-1', 'model-2'],
+        apiKeyEnvVar: 'MY_API_KEY',
+        gateway: this.id,
+      },
+    };
+  }
+
+  buildUrl(modelId: string, envVars?: Record<string, string>): string {
+    return 'https://api.my-provider.com/v1';
+  }
+
+  async getApiKey(modelId: string): Promise<string> {
+    const apiKey = process.env.MY_API_KEY;
+    if (!apiKey) throw new Error('MY_API_KEY not set');
+    return apiKey;
+  }
+
+  async resolveLanguageModel({
+    modelId,
+    providerId,
+    apiKey,
+  }: {
+    modelId: string;
+    providerId: string;
+    apiKey: string;
+  }): Promise<LanguageModelV2> {
+    const baseURL = this.buildUrl(`${providerId}/${modelId}`);
+    return createOpenAICompatible({
+      name: providerId,
+      apiKey,
+      baseURL,
+    }).chatModel(modelId);
+  }
+}
+```
+
+## Required Properties
+
+<PropertiesTable
+  content={[
+    {
+      name: 'id',
+      type: 'string',
+      description: 'Unique identifier for the gateway. Used for versioning and identification.',
+    },
+    {
+      name: 'name',
+      type: 'string',
+      description: 'Human-readable name for the gateway.',
+    },
+  ]}
+/>
+
+## Optional Properties
+
+<PropertiesTable
+  content={[
+    {
+      name: 'prefix',
+      type: 'string | undefined',
+      description: 'Optional prefix for provider IDs. If set, all providers from this gateway will be prefixed (e.g., "netlify/openai"). Registry gateways typically don\'t have a prefix.',
+    },
+  ]}
+/>
+
+## Required Methods
+
+### fetchProviders()
+
+Fetches provider configurations from the gateway.
+
+**Returns:** `Promise<Record<string, ProviderConfig>>`
+
+**ProviderConfig Structure:**
+<PropertiesTable
+  content={[
+    {
+      name: 'name',
+      type: 'string',
+      description: 'Display name of the provider',
+    },
+    {
+      name: 'models',
+      type: 'string[]',
+      description: 'Array of available model IDs',
+    },
+    {
+      name: 'apiKeyEnvVar',
+      type: 'string | string[]',
+      description: 'Environment variable(s) for API key',
+    },
+    {
+      name: 'gateway',
+      type: 'string',
+      description: 'Gateway identifier',
+    },
+    {
+      name: 'url',
+      type: 'string',
+      isOptional: true,
+      description: 'Optional base API URL',
+    },
+    {
+      name: 'apiKeyHeader',
+      type: 'string',
+      isOptional: true,
+      description: 'Optional custom auth header name',
+    },
+    {
+      name: 'docUrl',
+      type: 'string',
+      isOptional: true,
+      description: 'Optional documentation URL',
+    },
+  ]}
+/>
+
+### buildUrl()
+
+Builds the API URL for a specific model/provider combination.
+
+**Parameters:**
+<PropertiesTable
+  content={[
+    {
+      name: 'modelId',
+      type: 'string',
+      description: 'Full model ID (e.g., "custom/my-provider/model-1")',
+    },
+    {
+      name: 'envVars',
+      type: 'Record<string, string>',
+      isOptional: true,
+      description: 'Optional environment variables',
+    },
+  ]}
+/>
+
+**Returns:** `string | undefined | Promise<string | undefined>`
+
+### getApiKey()
+
+Retrieves the API key for authentication.
+
+**Parameters:**
+<PropertiesTable
+  content={[
+    {
+      name: 'modelId',
+      type: 'string',
+      description: 'Full model ID',
+    },
+  ]}
+/>
+
+**Returns:** `Promise<string>`
+
+### resolveLanguageModel()
+
+Creates a language model instance.
+
+**Parameters:**
+<PropertiesTable
+  content={[
+    {
+      name: 'modelId',
+      type: 'string',
+      description: 'The model ID',
+    },
+    {
+      name: 'providerId',
+      type: 'string',
+      description: 'The provider ID',
+    },
+    {
+      name: 'apiKey',
+      type: 'string',
+      description: 'The API key for authentication',
+    },
+  ]}
+/>
+
+**Returns:** `Promise<LanguageModelV2> | LanguageModelV2`
+
+## Instance Methods
+
+### getId()
+
+Returns the gateway's unique identifier.
+
+**Returns:** `string` - The gateway's `id` property
+
+## Model ID Format
+
+When a gateway has a prefix, models are accessed using this format:
+
+```
+[prefix]/[provider]/[model]
+```
+
+Examples:
+- With prefix `'custom'`: `'custom/my-provider/model-1'`
+- Without prefix: `'my-provider/model-1'`
+
+## Built-in Implementations
+
+- **NetlifyGateway** - Netlify AI Gateway integration
+- **ModelsDevGateway** - Registry of OpenAI-compatible providers
+
+## Related
+
+- [Custom Gateways Guide](/models/v1/gateways/custom-gateways) - Complete guide to creating custom gateways
+- [Mastra.addGateway()](/reference/v1/core/addGateway) - Add a gateway to Mastra
+- [Mastra.getGateway()](/reference/v1/core/getGateway) - Get gateway by registration key
+- [Mastra.getGatewayById()](/reference/v1/core/getGatewayById) - Get gateway by ID
+- [Mastra.listGateways()](/reference/v1/core/listGateways) - List all gateways

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.setLogger() | Core | Mastra Docs"
+title: "Reference: Mastra.setLogger() | Core"
 description: "Documentation for the `Mastra.setLogger()` method in Mastra, which sets the logger for all components (agents, workflows, etc.)."
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.setStorage() | Core | Mastra Docs"
+title: "Reference: Mastra.setStorage() | Core"
 description: "Documentation for the `Mastra.setStorage()` method in Mastra, which sets the storage instance for the Mastra instance."
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.setTelemetry() | Core | Mastra Docs"
+title: "Reference: Mastra.setTelemetry() | Core"
 description: "Documentation for the `Mastra.setTelemetry()` method in Mastra, which sets the telemetry configuration for all components."
 ---
 

package/.docs/raw/reference/deployer/cloudflare.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: CloudflareDeployer | Deployer | Mastra Docs"
+title: "Reference: CloudflareDeployer | Deployer"
 description: "Documentation for the CloudflareDeployer class, which deploys Mastra applications to Cloudflare Workers."
 ---
 

package/.docs/raw/reference/deployer/deployer.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Deployer | Deployer | Mastra Docs"
+title: "Reference: Deployer | Deployer"
 description: Documentation for the Deployer abstract class, which handles packaging and deployment of Mastra applications.
 asIndexPage: true
 ---

package/.docs/raw/reference/deployer/netlify.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: NetlifyDeployer | Deployer | Mastra Docs"
+title: "Reference: NetlifyDeployer | Deployer"
 description: "Documentation for the NetlifyDeployer class, which deploys Mastra applications to Netlify Functions."
 ---
 

package/.docs/raw/reference/deployer/vercel.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: VercelDeployer | Deployer | Mastra Docs"
+title: "Reference: VercelDeployer | Deployer"
 description: "Documentation for the VercelDeployer class, which deploys Mastra applications to Vercel."
 ---
 

package/.docs/raw/reference/evals/answer-relevancy.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Answer Relevancy Scorer | Evals | Mastra Docs"
+title: "Reference: Answer Relevancy Scorer | Evals"
 description: Documentation for the Answer Relevancy Scorer in Mastra, which evaluates how well LLM outputs address the input query.
 ---
 

package/.docs/raw/reference/evals/answer-similarity.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Answer Similarity Scorer | Evals | Mastra Docs"
+title: "Reference: Answer Similarity Scorer | Evals"
 description: Documentation for the Answer Similarity Scorer in Mastra, which compares agent outputs against ground truth answers for CI/CD testing.
 ---
 

package/.docs/raw/reference/evals/bias.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Bias Scorer | Evals | Mastra Docs"
+title: "Reference: Bias Scorer | Evals"
 description: Documentation for the Bias Scorer in Mastra, which evaluates LLM outputs for various forms of bias, including gender, political, racial/ethnic, or geographical bias.
 ---
 

package/.docs/raw/reference/evals/completeness.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Completeness Scorer | Evals | Mastra Docs"
+title: "Reference: Completeness Scorer | Evals"
 description: Documentation for the Completeness Scorer in Mastra, which evaluates how thoroughly LLM outputs cover key elements present in the input.
 ---
 

package/.docs/raw/reference/evals/content-similarity.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Content Similarity Scorer | Evals | Mastra Docs"
+title: "Reference: Content Similarity Scorer | Evals"
 description: Documentation for the Content Similarity Scorer in Mastra, which measures textual similarity between strings and provides a matching score.
 ---
 

package/.docs/raw/reference/evals/context-precision.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Context Precision Scorer | Evals | Mastra Docs"
+title: "Reference: Context Precision Scorer | Evals"
 description: Documentation for the Context Precision Scorer in Mastra. Evaluates the relevance and precision of retrieved context for generating expected outputs using Mean Average Precision.
 ---
 

package/.docs/raw/reference/evals/context-relevance.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Context Relevance Scorer | Evals | Mastra Docs"
+title: "Reference: Context Relevance Scorer | Evals"
 description: Documentation for the Context Relevance Scorer in Mastra. Evaluates the relevance and utility of provided context for generating agent responses using weighted relevance scoring.
 ---
 

package/.docs/raw/reference/evals/create-scorer.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: createScorer | Evals | Mastra Docs"
+title: "Reference: createScorer | Evals"
 description: Documentation for creating custom scorers in Mastra, allowing users to define their own evaluation logic using either JavaScript functions or LLM-based prompts.
 ---