@mastra/mcp-docs-server 1.1.46-alpha.2 → 1.1.46-alpha.3

package/.docs/models/gateways/custom-gateways.md

@@ -1,6 +1,6 @@
 # Custom model gateways
 
-Custom model gateways allow you to implement private or specialized LLM provider integrations by extending the `MastraModelGateway` base class.
+Custom model gateways allow you to implement private or specialized LLM provider integrations with the `MastraModelGatewayInterface` interface or the `MastraModelGateway` base class.
 
 ## Overview
 
@@ -20,7 +20,43 @@ Create custom gateways to support:
 
 ## Creating a Custom Gateway
 
-Extend the `MastraModelGateway` class and implement the required methods:
+Implement `MastraModelGatewayInterface` for a plain object gateway, or extend `MastraModelGateway` when you want base class defaults.
+
+```typescript
+import { type MastraModelGatewayInterface, type ProviderConfig } from '@mastra/core/llm';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible-v5';
+
+const myPrivateGateway: MastraModelGatewayInterface = {
+  id: 'private',
+  name: 'My Private Gateway',
+  async fetchProviders(): Promise<Record<string, ProviderConfig>> {
+    return {
+      'my-provider': {
+        name: 'My Provider',
+        models: ['openai/gpt-5.5'],
+        apiKeyEnvVar: 'MY_API_KEY',
+        gateway: 'private',
+        url: 'https://api.myprovider.com/v1',
+      },
+    };
+  },
+  buildUrl() {
+    return 'https://api.myprovider.com/v1';
+  },
+  async getApiKey() {
+    return process.env.MY_API_KEY ?? '';
+  },
+  async resolveLanguageModel({ modelId, providerId, apiKey }) {
+    return createOpenAICompatible({
+      name: providerId,
+      apiKey,
+      baseURL: 'https://api.myprovider.com/v1',
+    }).chatModel(modelId);
+  },
+};
+```
+
+The following example extends the `MastraModelGateway` class:
 
 ```typescript
 import { MastraModelGateway, type ProviderConfig } from '@mastra/core/llm';
@@ -43,7 +79,7 @@ class MyPrivateGateway extends MastraModelGateway {
     return {
       'my-provider': {
         name: 'My Provider',
-        models: ['model-1', 'model-2', 'model-3'],
+        models: ['openai/gpt-5.5', 'anthropic/claude-sonnet-4-6'],
         apiKeyEnvVar: 'MY_API_KEY',
         gateway: this.id,
         url: 'https://api.myprovider.com/v1',
@@ -97,6 +133,20 @@ class MyPrivateGateway extends MastraModelGateway {
 }
 ```
 
+### Gateway-owned authentication
+
+Add `resolveAuth` when the gateway owns credential lookup. Mastra uses this hook before falling back to `getApiKey()`.
+
+```typescript
+const myPrivateGateway: MastraModelGatewayInterface = {
+  // ...gateway fields and methods
+  async resolveAuth() {
+    const apiKey = process.env.MY_API_KEY;
+    return apiKey ? { apiKey, source: 'gateway' } : undefined;
+  },
+};
+```
+
 ## Registering Custom Gateways
 
 ### During Initialization
@@ -140,7 +190,7 @@ const agent = new Agent({
   id: 'my-agent',
   name: 'My Agent',
   instructions: 'You are a helpful assistant',
-  model: 'private/my-provider/model-1', // Uses MyPrivateGateway
+  model: 'private/my-provider/openai/gpt-5.5', // Uses MyPrivateGateway
 });
 
 mastra.addAgent(agent, 'myAgent');
@@ -150,9 +200,9 @@ When you create an agent or use a model, Mastra's model router automatically sel
 
 ### TypeScript Autocomplete
 
-**Automatic Type Generation in Development**
+#### Automatic type generation in development
 
-When running in development mode (`MASTRA_DEV=true`), Mastra automatically generates TypeScript types for your custom gateways!
+When running in development mode (`MASTRA_DEV=true`), Mastra automatically generates TypeScript types for your custom gateways.
 
 1. **Set the environment variable**:
 
@@ -185,7 +235,7 @@ When running in development mode (`MASTRA_DEV=true`), Mastra automatically gener
    });
    ```
 
-**How It Works**
+#### How it works
 
 The GatewayRegistry runs an hourly sync that:
 

package/.docs/reference/core/mastra-model-gateway.md

@@ -2,6 +2,8 @@
 
 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.
 
+Use `MastraModelGatewayInterface` when you want to provide a plain object gateway instead of extending the base class.
+
 ## Class overview
 
 ```typescript
@@ -17,7 +19,7 @@ class MyCustomGateway extends MastraModelGateway {
     return {
       'my-provider': {
         name: 'My Provider',
-        models: ['model-1', 'model-2'],
+        models: ['openai/gpt-5.5', 'anthropic/claude-sonnet-4-6'],
         apiKeyEnvVar: 'MY_API_KEY',
         gateway: this.id,
       },
@@ -107,6 +109,18 @@ Retrieves the API key for authentication.
 
 **Returns:** `Promise<string>`
 
+### `resolveAuth()`
+
+Resolves credentials before Mastra creates the language model. Implement this optional hook when a gateway owns authentication. If omitted, Mastra falls back to `getApiKey()`.
+
+**Parameters:**
+
+**request** (`GatewayAuthRequest`): Incoming request context containing gatewayId, providerId, modelId, and routerId for the gateway to inspect and validate.
+
+**Returns:** `GatewayAuthResult | undefined | Promise<GatewayAuthResult | undefined>`
+
+A `GatewayAuthResult` may include `apiKey`, `bearerToken`, `headers`, and an optional `source` field to trace where auth came from.
+
 ### `resolveLanguageModel()`
 
 Creates a language model instance.

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.1.46-alpha.3
+
+### Patch Changes
+
+- Updated dependencies [[`34839c1`](https://github.com/mastra-ai/mastra/commit/34839c1910b6964bf59ed0cee58844efebbb684e), [`053735a`](https://github.com/mastra-ai/mastra/commit/053735a75c2c18e23ce34d9468007efa4a45f4c4), [`34839c1`](https://github.com/mastra-ai/mastra/commit/34839c1910b6964bf59ed0cee58844efebbb684e), [`34839c1`](https://github.com/mastra-ai/mastra/commit/34839c1910b6964bf59ed0cee58844efebbb684e), [`a952852`](https://github.com/mastra-ai/mastra/commit/a952852c971a21fb646cd907c75fcf4443cdc963)]:
+  - @mastra/core@1.42.0-alpha.3
+
 ## 1.1.46-alpha.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.46-alpha.2",
+  "version": "1.1.46-alpha.3",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.42.0-alpha.2",
-    "@mastra/mcp": "^1.9.2-alpha.0"
+    "@mastra/mcp": "^1.9.2-alpha.0",
+    "@mastra/core": "1.42.0-alpha.3"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -45,9 +45,9 @@
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "4.1.5",
-    "@internal/types-builder": "0.0.78",
     "@internal/lint": "0.0.103",
-    "@mastra/core": "1.42.0-alpha.2"
+    "@mastra/core": "1.42.0-alpha.3",
+    "@internal/types-builder": "0.0.78"
   },
   "homepage": "https://mastra.ai",
   "repository": {