@mastra/mcp-docs-server 0.13.23 → 0.13.24-alpha.2

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

@@ -0,0 +1,235 @@
+---
+title: "MastraAuthAuth0 Class"
+description: "Documentation for the MastraAuthAuth0 class, which authenticates Mastra applications using Auth0 authentication."
+---
+
+import { Tabs, Tab } from "@/components/tabs";
+
+# MastraAuthAuth0 Class
+
+The `MastraAuthAuth0` class provides authentication for Mastra using Auth0. It verifies incoming requests using Auth0-issued JWT tokens and integrates with the Mastra server using the `experimental_auth` option.
+
+## Prerequisites
+
+This example uses Auth0 authentication. Make sure to:
+
+1. Create an Auth0 account at [auth0.com](https://auth0.com/)
+2. Set up an Application in your Auth0 Dashboard
+3. Configure an API in your Auth0 Dashboard with an identifier (audience)
+4. Configure your application's allowed callback URLs, web origins, and logout URLs
+
+```env filename=".env" copy
+AUTH0_DOMAIN=your-tenant.auth0.com
+AUTH0_AUDIENCE=your-api-identifier
+```
+
+> **Note:** You can find your domain in the Auth0 Dashboard under Applications > Settings. The audience is the identifier of your API configured in Auth0 Dashboard > APIs.
+
+> For detailed setup instructions, refer to the [Auth0 quickstarts](https://auth0.com/docs/quickstarts) for your specific platform.
+
+## Installation
+
+Before you can use the `MastraAuthAuth0` class you have to install the `@mastra/auth-auth0` package.
+
+```bash copy
+npm install @mastra/auth-auth0@latest
+```
+
+## Usage examples
+
+### Basic usage with environment variables
+
+```typescript {2,7} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthAuth0 } from '@mastra/auth-auth0';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraAuthAuth0(),
+  },
+});
+```
+
+### Custom configuration
+
+```typescript {2,7-10} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthAuth0 } from '@mastra/auth-auth0';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraAuthAuth0({
+      domain: process.env.AUTH0_DOMAIN,
+      audience: process.env.AUTH0_AUDIENCE
+    }),
+  },
+});
+```
+
+## Configuration
+
+### User Authorization
+
+By default, `MastraAuthAuth0` allows all authenticated users who have valid Auth0 tokens for the specified audience. The token verification ensures that:
+
+1. The token is properly signed by Auth0
+2. The token is not expired
+3. The token audience matches your configured audience
+4. The token issuer matches your Auth0 domain
+
+To customize user authorization, provide a custom `authorizeUser` function:
+
+```typescript filename="src/mastra/auth.ts" showLineNumbers copy
+import { MastraAuthAuth0 } from '@mastra/auth-auth0';
+
+const auth0Provider = new MastraAuthAuth0({
+  authorizeUser: async (user) => {
+    // Custom authorization logic
+    return user.email?.endsWith('@yourcompany.com') || false;
+  }
+});
+```
+
+> See the [MastraAuthAuth0](/reference/auth/auth0.mdx) API reference for all available configuration options.
+
+## Client-side setup
+
+When using Auth0 auth, you'll need to set up the Auth0 React SDK, authenticate users, and retrieve their access tokens to pass to your Mastra requests.
+
+### Setting up Auth0 React SDK
+
+First, install and configure the Auth0 React SDK in your application:
+
+```bash copy
+npm install @auth0/auth0-react
+```
+
+```typescript filename="src/auth0-provider.tsx" showLineNumbers copy
+import React from 'react';
+import { Auth0Provider } from '@auth0/auth0-react';
+
+const Auth0ProviderWithHistory = ({ children }) => {
+  return (
+    <Auth0Provider
+      domain={process.env.REACT_APP_AUTH0_DOMAIN}
+      clientId={process.env.REACT_APP_AUTH0_CLIENT_ID}
+      authorizationParams={{
+        redirect_uri: window.location.origin,
+        audience: process.env.REACT_APP_AUTH0_AUDIENCE,
+        scope: "read:current_user update:current_user_metadata"
+      }}
+    >
+      {children}
+    </Auth0Provider>
+  );
+};
+
+export default Auth0ProviderWithHistory;
+```
+
+### Retrieving access tokens
+
+Use the Auth0 React SDK to authenticate users and retrieve their access tokens:
+
+```typescript filename="lib/auth.ts" showLineNumbers copy
+import { useAuth0 } from '@auth0/auth0-react';
+
+export const useAuth0Token = () => {
+  const { getAccessTokenSilently } = useAuth0();
+
+  const getAccessToken = async () => {
+    const token = await getAccessTokenSilently();
+    return token;
+  };
+
+  return { getAccessToken };
+};
+```
+
+> Refer to the [Auth0 React SDK documentation](https://auth0.com/docs/libraries/auth0-react) for more authentication methods and configuration options.
+
+## Configuring `MastraClient`
+
+When `experimental_auth` is enabled, all requests made with `MastraClient` must include a valid Auth0 access token in the `Authorization` header:
+
+```typescript filename="lib/mastra/mastra-client.ts" showLineNumbers copy
+import { MastraClient } from "@mastra/client-js";
+
+export const createMastraClient = (accessToken: string) => {
+  return new MastraClient({
+    baseUrl: "https://<mastra-api-url>",
+    headers: {
+      Authorization: `Bearer ${accessToken}`
+    }
+  });
+};
+```
+
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
+
+> See [Mastra Client SDK](/docs/server-db/mastra-client.mdx) for more configuration options.
+
+### Making authenticated requests
+
+Once `MastraClient` is configured with the Auth0 access token, you can send authenticated requests:
+
+<Tabs items={["React Component", "curl"]}>
+  <Tab>
+    ```tsx filename="src/components/mastra-api-test.tsx" showLineNumbers copy
+    import React, { useState } from 'react';
+    import { useAuth0 } from '@auth0/auth0-react';
+    import { MastraClient } from '@mastra/client-js';
+
+    export const MastraApiTest = () => {
+      const { getAccessTokenSilently } = useAuth0();
+      const [result, setResult] = useState(null);
+
+      const callMastraApi = async () => {
+        const token = await getAccessTokenSilently();
+
+        const mastra = new MastraClient({
+          baseUrl: "http://localhost:4111",
+          headers: {
+            Authorization: `Bearer ${token}`
+          }
+        });
+
+        const weatherAgent = mastra.getAgent("weatherAgent");
+        const response = await weatherAgent.generate({
+          messages: "What's the weather like in New York"
+        });
+
+        setResult(response.text);
+      };
+
+      return (
+        <div>
+          <button onClick={callMastraApi}>
+            Test Mastra API
+          </button>
+
+          {result && (
+            <div className="result">
+              <h6>Result:</h6>
+              <pre>{result}</pre>
+            </div>
+          )}
+        </div>
+      );
+    };
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
+      -H "Content-Type: application/json" \
+      -H "Authorization: Bearer <your-auth0-access-token>" \
+      -d '{
+        "messages": "Weather in London"
+      }'
+    ```
+  </Tab>
+</Tabs>
+

package/.docs/raw/auth/index.mdx

@@ -15,10 +15,5 @@ You can start with simple shared secret JWT authentication and switch to provide
 - [Clerk](/docs/auth/clerk)
 - [Supabase](/docs/auth/supabase)
 - [Firebase](/docs/auth/firebase)
-
-### Coming soon
-
-The following providers will be available soon:
-
-- Auth0
-- WorkOS
+- [WorkOS](/docs/auth/workos)
+- [Auth0](/docs/auth/auth0)

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

@@ -0,0 +1,198 @@
+---
+title: "MastraAuthWorkos Class"
+description: "Documentation for the MastraAuthWorkos class, which authenticates Mastra applications using WorkOS authentication."
+---
+
+import { Tabs, Tab } from "@/components/tabs";
+
+# 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.
+
+## Prerequisites
+
+This example uses WorkOS authentication. Make sure to:
+
+1. Create a WorkOS account at [workos.com](https://workos.com/)
+2. Set up an Application in your WorkOS Dashboard
+3. Configure your redirect URIs and allowed origins
+4. Set up Organizations and configure user roles as needed
+
+```env filename=".env" copy
+WORKOS_API_KEY=sk_live_...
+WORKOS_CLIENT_ID=client_...
+```
+
+> **Note:** You can find your API key and Client ID in the WorkOS Dashboard under API Keys and Applications respectively.
+
+> For detailed setup instructions, refer to the [WorkOS documentation](https://workos.com/docs) for your specific platform.
+
+## Installation
+
+Before you can use the `MastraAuthWorkos` class you have to install the `@mastra/auth-workos` package.
+
+```bash copy
+npm install @mastra/auth-workos@latest
+```
+
+## Usage examples
+
+### Basic usage with environment variables
+
+```typescript {2,7} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthWorkos } from '@mastra/auth-workos';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraAuthWorkos(),
+  },
+});
+```
+
+### Custom configuration
+
+```typescript {2,7-10} filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthWorkos } from '@mastra/auth-workos';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraAuthWorkos({
+      apiKey: process.env.WORKOS_API_KEY,
+      clientId: process.env.WORKOS_CLIENT_ID
+    }),
+  },
+});
+```
+
+## Configuration
+
+### User Authorization
+
+By default, `MastraAuthWorkos` checks whether the authenticated user has an 'admin' role in any of their organization memberships. The authorization process:
+
+1. Retrieves the user's organization memberships using their user ID
+2. Extracts all roles from their memberships
+3. Checks if any role has the slug 'admin'
+4. Grants access only if the user has admin role in at least one organization
+
+To customize user authorization, provide a custom `authorizeUser` function:
+
+```typescript filename="src/mastra/auth.ts" showLineNumbers copy
+import { MastraAuthWorkos } from '@mastra/auth-workos';
+
+const workosAuth = new MastraAuthWorkos({
+  apiKey: process.env.WORKOS_API_KEY,
+  clientId: process.env.WORKOS_CLIENT_ID,
+  authorizeUser: async (user) => {
+    return !!user;
+  },
+});
+```
+
+> See the [MastraAuthWorkos](/reference/auth/workos) API reference for all available configuration options.
+
+## Client-side setup
+
+When using WorkOS auth, you'll need to implement the WorkOS authentication flow to exchange an authorization code for an access token, then use that token with your Mastra requests.
+
+### Installing WorkOS SDK
+
+First, install the WorkOS SDK in your application:
+
+```bash copy
+npm install @workos-inc/node
+```
+
+### Exchanging code for access token
+
+After users complete the WorkOS authentication flow and return with an authorization code, exchange it for an access token:
+
+```typescript filename="lib/auth.ts" showLineNumbers copy
+import { WorkOS } from '@workos-inc/node';
+
+const workos = new WorkOS(process.env.WORKOS_API_KEY);
+
+export const authenticateWithWorkos = async (code: string, clientId: string) => {
+  const authenticationResponse = await workos.userManagement.authenticateWithCode({
+    code,
+    clientId,
+  });
+
+  return authenticationResponse.accessToken;
+};
+```
+
+> Refer to the [WorkOS User Management documentation](https://workos.com/docs/authkit/vanilla/nodejs) for more authentication methods and configuration options.
+
+## Configuring `MastraClient`
+
+When `experimental_auth` is enabled, all requests made with `MastraClient` must include a valid WorkOS access token in the `Authorization` header:
+
+```typescript filename="lib/mastra/mastra-client.ts" showLineNumbers copy
+import { MastraClient } from "@mastra/client-js";
+
+export const createMastraClient = (accessToken: string) => {
+  return new MastraClient({
+    baseUrl: "https://<mastra-api-url>",
+    headers: {
+      Authorization: `Bearer ${accessToken}`
+    }
+  });
+};
+```
+
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
+
+> See [Mastra Client SDK](/docs/server-db/mastra-client) for more configuration options.
+
+### Making authenticated requests
+
+Once `MastraClient` is configured with the WorkOS access token, you can send authenticated requests:
+
+<Tabs items={["JavaScript/Node.js", "curl"]}>
+  <Tab>
+    ```typescript filename="src/api/agents.ts" showLineNumbers copy
+    import { WorkOS } from '@workos-inc/node';
+    import { MastraClient } from '@mastra/client-js';
+
+    const workos = new WorkOS(process.env.WORKOS_API_KEY);
+
+    export const callMastraWithWorkos = async (code: string, clientId: string) => {
+      const authenticationResponse = await workos.userManagement.authenticateWithCode({
+        code,
+        clientId,
+      });
+
+      const token = authenticationResponse.accessToken;
+
+      const mastra = new MastraClient({
+        baseUrl: "http://localhost:4111",
+        headers: {
+          Authorization: `Bearer ${token}`,
+        },
+      });
+
+      const weatherAgent = mastra.getAgent("weatherAgent");
+      const response = await weatherAgent.generate({
+        messages: "What's the weather like in Nairobi",
+      });
+
+      return response.text;
+    };
+    ```
+  </Tab>
+  <Tab>
+    ```bash copy
+    curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
+      -H "Content-Type: application/json" \
+      -H "Authorization: Bearer <your-workos-access-token>" \
+      -d '{
+        "messages": "Weather in London"
+      }'
+    ```
+  </Tab>
+</Tabs>

package/.docs/raw/reference/agents/agent.mdx

@@ -7,19 +7,94 @@ description: "Documentation for the `Agent` class in Mastra, which provides the
 
 The `Agent` class is the foundation for creating AI agents in Mastra. It provides methods for generating responses, streaming interactions, and handling voice capabilities.
 
-## Usage example
+## Usage examples
 
-```typescript filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
+### Basic string instructions
+
+```typescript filename="src/mastra/agents/string-agent.ts" showLineNumbers copy
 import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 
+// String instructions
 export const agent = new Agent({
   name: "test-agent",
-  instructions: 'message for agent',
+  instructions: 'You are a helpful assistant that provides concise answers.',
+  model: openai("gpt-4o")
+});
+
+// System message object
+export const agent2 = new Agent({
+  name: "test-agent-2",
+  instructions: { 
+    role: "system", 
+    content: "You are an expert programmer" 
+  },
+  model: openai("gpt-4o")
+});
+
+// Array of system messages
+export const agent3 = new Agent({
+  name: "test-agent-3",
+  instructions: [
+    { role: "system", content: "You are a helpful assistant" },
+    { role: "system", content: "You have expertise in TypeScript" }
+  ],
   model: openai("gpt-4o")
 });
 ```
 
+### Single CoreSystemMessage
+
+Use CoreSystemMessage format to access additional properties like `providerOptions` for provider-specific configurations:
+
+```typescript filename="src/mastra/agents/core-message-agent.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+
+export const agent = new Agent({
+  name: "core-message-agent",
+  instructions: {
+    role: 'system',
+    content: 'You are a helpful assistant specialized in technical documentation.',
+    providerOptions: {
+      openai: { 
+        reasoningEffort: 'low'
+      }
+    }
+  },
+  model: openai("gpt-5")
+});
+```
+
+### Multiple CoreSystemMessages
+
+```typescript filename="src/mastra/agents/multi-message-agent.ts" showLineNumbers copy
+import { anthropic } from "@ai-sdk/anthropic";
+import { Agent } from "@mastra/core/agent";
+
+// This could be customizable based on the user
+const preferredTone = { 
+  role: 'system', 
+  content: 'Always maintain a professional and empathetic tone.',
+};
+
+export const agent = new Agent({
+  name: "multi-message-agent",
+  instructions: [
+    { role: 'system', content: 'You are a customer service representative.' },
+    preferredTone,
+    { 
+      role: 'system', 
+      content: 'Escalate complex issues to human agents when needed.',
+      providerOptions: {
+        anthropic: { cacheControl: { type: 'ephemeral' } },
+      },
+    },
+  ],
+  model: anthropic('claude-sonnet-4-20250514'),
+});
+```
+
 ## Constructor parameters
 
 <PropertiesTable
@@ -44,9 +119,11 @@ export const agent = new Agent({
     },
     {
       name: "instructions",
-      type: "string | ({ runtimeContext: RuntimeContext }) => string | Promise<string>",
+      type: "SystemMessage | ({ runtimeContext: RuntimeContext }) => SystemMessage | Promise<SystemMessage>",
       isOptional: false,
-      description: "Instructions that guide the agent's behavior. Can be a static string or a function that returns a string dynamically.",
+      description: `Instructions that guide the agent's behavior. Can be a string, array of strings, system message object, 
+        array of system messages, or a function that returns any of these types dynamically. 
+        SystemMessage types: string | string[] | CoreSystemMessage | CoreSystemMessage[] | SystemModelMessage | SystemModelMessage[]`,
     },
     {
       name: "model",

package/.docs/raw/reference/agents/getInstructions.mdx

@@ -33,8 +33,8 @@ await agent.getInstructions();
   content={[
     {
       name: "instructions",
-      type: "string | Promise<string>",
-      description: "The instructions configured for the agent, either as a direct string or a promise that resolves to the instructions.",
+      type: "SystemMessage | Promise<SystemMessage>",
+      description: "The instructions configured for the agent. SystemMessage can be: string | string[] | CoreSystemMessage | CoreSystemMessage[] | SystemModelMessage | SystemModelMessage[]. Returns either directly or as a promise that resolves to the instructions.",
     },
   ]}
 />

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

@@ -0,0 +1,117 @@
+---
+title: "MastraAuthAuth0 Class"
+description: "API reference for the MastraAuthAuth0 class, which authenticates Mastra applications using Auth0 authentication."
+---
+
+# MastraAuthAuth0 Class
+
+The `MastraAuthAuth0` class provides authentication for Mastra using Auth0. It verifies incoming requests using Auth0-issued JWT tokens and integrates with the Mastra server using the `experimental_auth` option.
+
+## Usage example
+
+```typescript filename="src/mastra/index.ts" showLineNumbers copy
+import { Mastra } from "@mastra/core/mastra";
+import { MastraAuthAuth0 } from '@mastra/auth-auth0';
+
+export const mastra = new Mastra({
+  // ..
+  server: {
+    experimental_auth: new MastraAuthAuth0({
+      domain: process.env.AUTH0_DOMAIN,
+      audience: process.env.AUTH0_AUDIENCE
+    }),
+  },
+});
+```
+
+> **Note:** You can omit the constructor parameters if you have the appropriately named environment variables (`AUTH0_DOMAIN` and `AUTH0_AUDIENCE`) set. In that case, simply use `new MastraAuthAuth0()` without any arguments.
+
+## Constructor parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "domain",
+      type: "string",
+      description: "Your Auth0 domain (e.g., your-tenant.auth0.com). This is used to verify JWT tokens issued by your Auth0 tenant.",
+      isOptional: true,
+      defaultValue: "process.env.AUTH0_DOMAIN"
+    },
+    {
+      name: "audience",
+      type: "string",
+      description: "Your Auth0 API identifier/audience. This ensures tokens are intended for your specific API.",
+      isOptional: true,
+      defaultValue: "process.env.AUTH0_AUDIENCE"
+    },
+    {
+      name: "name",
+      type: "string",
+      description: "Custom name for the auth provider instance.",
+      isOptional: true,
+      defaultValue: '"auth0"'
+    },
+    {
+      name: "authorizeUser",
+      type: "(user: Auth0User) => Promise<boolean> | boolean",
+      description: "Custom authorization function to determine if a user should be granted access. Called after token verification. By default, allows all authenticated users with valid tokens.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Environment Variables
+
+The following environment variables are automatically used when constructor options are not provided:
+
+<PropertiesTable
+  content={[
+    {
+      name: "AUTH0_DOMAIN",
+      type: "string",
+      description: "Your Auth0 domain. Can be found in your Auth0 Dashboard under Applications > Settings.",
+      isOptional: true,
+    },
+    {
+      name: "AUTH0_AUDIENCE",
+      type: "string",
+      description: "Your Auth0 API identifier. This is the identifier you set when creating an API in your Auth0 Dashboard.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Default Authorization Behavior
+
+By default, `MastraAuthAuth0` validates Auth0 JWT tokens and allows access to all authenticated users:
+
+1. **Token Verification**: The JWT token is verified using Auth0's public keys (JWKS)
+2. **Signature Validation**: Ensures the token was signed by your Auth0 tenant
+3. **Expiration Check**: Verifies the token has not expired
+4. **Audience Validation**: Confirms the token was issued for your specific API (audience)
+5. **Issuer Validation**: Ensures the token was issued by your Auth0 domain
+
+If all validations pass, the user is considered authorized. To implement custom authorization logic (e.g., role-based access control), provide a custom `authorizeUser` function.
+
+## Auth0 User Type
+
+The `Auth0User` type used in the `authorizeUser` function corresponds to the decoded JWT token payload, which typically includes:
+
+- `sub`: The user's unique identifier (subject)
+- `email`: The user's email address (if included in token)
+- `email_verified`: Whether the email is verified
+- `name`: The user's display name (if available)
+- `picture`: URL to the user's profile picture (if available)
+- `iss`: Token issuer (your Auth0 domain)
+- `aud`: Token audience (your API identifier)
+- `iat`: Token issued at timestamp
+- `exp`: Token expiration timestamp
+- `scope`: Granted scopes for the token
+- Custom claims and app metadata configured in your Auth0 tenant
+
+The exact properties available depend on your Auth0 configuration, scopes requested, and any custom claims you've configured.
+
+## Related
+
+[MastraAuthAuth0 Class](/docs/auth/auth0.mdx)
+