@mastra/core 1.0.0-beta.21 → 1.0.0-beta.22

package/dist/docs/tools/01-reference.md

@@ -200,6 +200,43 @@ export const tool = createTool({
 });
 ```
 
+## Example with MCP Annotations
+
+When exposing tools via MCP (Model Context Protocol), you can add annotations to describe tool behavior and customize how clients display the tool. These MCP-specific properties are grouped under the `mcp` property:
+
+```typescript title="src/mastra/tools/weather-tool.ts"
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const weatherTool = createTool({
+  id: "get-weather",
+  description: "Get current weather for a location",
+  inputSchema: z.object({
+    location: z.string().describe("City name or coordinates"),
+  }),
+  // MCP-specific properties
+  mcp: {
+    // Annotations for client behavior hints
+    annotations: {
+      title: "Weather Lookup",           // Human-readable display name
+      readOnlyHint: true,                // Tool doesn't modify environment
+      destructiveHint: false,            // Tool doesn't perform destructive updates
+      idempotentHint: true,              // Same args = same result
+      openWorldHint: true,               // Interacts with external API
+    },
+    // Custom metadata for client-specific functionality
+    _meta: {
+      version: "1.0.0",
+      category: "weather",
+    },
+  },
+  execute: async (inputData) => {
+    const weather = await fetchWeather(inputData.location);
+    return { weather };
+  },
+});
+```
+
 ## Parameters
 
 ## Returns
@@ -306,6 +343,23 @@ Additionally:
 
 Hook errors are caught and logged automatically, but do not prevent tool execution from continuing. If a hook throws an error, it will be logged to the console but will not fail the tool call.
 
+## MCP Tool Annotations
+
+When exposing tools via the Model Context Protocol (MCP), you can provide annotations that describe tool behavior. These annotations help MCP clients like OpenAI Apps SDK understand how to present and handle your tools.
+
+MCP-specific properties are grouped under the `mcp` property, which includes `annotations` and `_meta`:
+
+```typescript
+mcp: {
+  annotations: { /* behavior hints */ },
+  _meta: { /* custom metadata */ },
+}
+```
+
+### ToolAnnotations Properties
+
+These annotations follow the [MCP specification](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#tool-annotations) and are passed through when tools are listed via MCP.
+
 ## Related
 
 - [MCP Overview](https://mastra.ai/docs/v1/mcp/overview)
@@ -793,7 +847,7 @@ Retrieves all tools from all configured servers, with tool names namespaced by t
 Intended to be passed onto an Agent definition.
 
 ```ts
-new Agent({ tools: await mcp.listTools() });
+new Agent({ id: "agent", tools: await mcp.listTools() });
 ```
 
 ### listToolsets()
@@ -1338,6 +1392,104 @@ await mcpClient.elicitation.onRequest("interactiveServer", async (request) => {
 - **Clear UI**: Make it obvious what information is being requested and why
 - **Security**: Never auto-accept requests for sensitive information
 
+## OAuth Authentication
+
+For connecting to MCP servers that require OAuth authentication per the [MCP Auth Specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization), use the `MCPOAuthClientProvider`:
+
+```typescript
+import { MCPClient, MCPOAuthClientProvider } from "@mastra/mcp";
+
+// Create an OAuth provider
+const oauthProvider = new MCPOAuthClientProvider({
+  redirectUrl: "http://localhost:3000/oauth/callback",
+  clientMetadata: {
+    redirect_uris: ["http://localhost:3000/oauth/callback"],
+    client_name: "My MCP Client",
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+  },
+  onRedirectToAuthorization: (url) => {
+    // Handle authorization redirect (open browser, redirect response, etc.)
+    console.log(`Please visit: ${url}`);
+  },
+});
+
+// Use the provider with MCPClient
+const client = new MCPClient({
+  servers: {
+    protectedServer: {
+      url: new URL("https://mcp.example.com/mcp"),
+      authProvider: oauthProvider,
+    },
+  },
+});
+```
+
+### Quick Token Provider
+
+For testing or when you already have a valid access token:
+
+```typescript
+import { MCPClient, createSimpleTokenProvider } from "@mastra/mcp";
+
+const provider = createSimpleTokenProvider("your-access-token", {
+  redirectUrl: "http://localhost:3000/callback",
+  clientMetadata: {
+    redirect_uris: ["http://localhost:3000/callback"],
+    client_name: "Test Client",
+  },
+});
+
+const client = new MCPClient({
+  servers: {
+    testServer: {
+      url: new URL("https://mcp.example.com/mcp"),
+      authProvider: provider,
+    },
+  },
+});
+```
+
+### Custom Token Storage
+
+For persistent token storage across sessions, implement the `OAuthStorage` interface:
+
+```typescript
+import { MCPOAuthClientProvider, OAuthStorage } from "@mastra/mcp";
+
+class DatabaseOAuthStorage implements OAuthStorage {
+  constructor(private db: Database, private userId: string) {}
+
+  async set(key: string, value: string): Promise<void> {
+    await this.db.query(
+      "INSERT INTO oauth_tokens (user_id, key, value) VALUES (?, ?, ?) ON CONFLICT DO UPDATE SET value = ?",
+      [this.userId, key, value, value]
+    );
+  }
+
+  async get(key: string): Promise<string | undefined> {
+    const result = await this.db.query(
+      "SELECT value FROM oauth_tokens WHERE user_id = ? AND key = ?",
+      [this.userId, key]
+    );
+    return result?.[0]?.value;
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.db.query(
+      "DELETE FROM oauth_tokens WHERE user_id = ? AND key = ?",
+      [this.userId, key]
+    );
+  }
+}
+
+const provider = new MCPOAuthClientProvider({
+  redirectUrl: "http://localhost:3000/callback",
+  clientMetadata: { /* ... */ },
+  storage: new DatabaseOAuthStorage(db, "user-123"),
+});
+```
+
 ## Examples
 
 ### Static Tool Configuration
@@ -1369,6 +1521,7 @@ const mcp = new MCPClient({
 
 // Create an agent with access to all tools
 const agent = new Agent({
+  id: "multi-tool-agent",
   name: "Multi-tool Agent",
   instructions: "You have access to multiple tool servers.",
   model: "openai/gpt-5.1",
@@ -1424,6 +1577,7 @@ import { MCPClient } from "@mastra/mcp";
 
 // Create the agent first, without any tools
 const agent = new Agent({
+  id: "multi-tool-agent",
   name: "Multi-tool Agent",
   instructions: "You help users check stocks and weather.",
   model: "openai/gpt-5.1",
@@ -2507,44 +2661,245 @@ type ElicitResult = {
 };
 ```
 
+## OAuth Protection
+
+To protect your MCP server with OAuth authentication per the [MCP Auth Specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization), use the `createOAuthMiddleware` function:
+
+```typescript
+import http from "node:http";
+import { MCPServer, createOAuthMiddleware, createStaticTokenValidator } from "@mastra/mcp";
+
+const mcpServer = new MCPServer({
+  id: "protected-server",
+  name: "Protected MCP Server",
+  version: "1.0.0",
+  tools: { /* your tools */ },
+});
+
+// Create OAuth middleware
+const oauthMiddleware = createOAuthMiddleware({
+  oauth: {
+    resource: "https://mcp.example.com/mcp",
+    authorizationServers: ["https://auth.example.com"],
+    scopesSupported: ["mcp:read", "mcp:write"],
+    resourceName: "My Protected MCP Server",
+    validateToken: createStaticTokenValidator(["allowed-token-1"]),
+  },
+  mcpPath: "/mcp",
+});
+
+// Create HTTP server with OAuth protection
+const httpServer = http.createServer(async (req, res) => {
+  const url = new URL(req.url || "", "https://mcp.example.com");
+
+  // Apply OAuth middleware first
+  const result = await oauthMiddleware(req, res, url);
+  if (!result.proceed) return; // Middleware handled response (401, metadata, etc.)
+
+  // Token is valid, proceed to MCP handler
+  await mcpServer.startHTTP({ url, httpPath: "/mcp", req, res });
+});
+
+httpServer.listen(3000);
+```
+
+The middleware automatically:
+
+- Serves **Protected Resource Metadata** at `/.well-known/oauth-protected-resource` (RFC 9728)
+- Returns `401 Unauthorized` with proper `WWW-Authenticate` headers when authentication is required
+- Validates bearer tokens using your provided validator
+
+### Token Validation
+
+For production, use proper token validation:
+
+```typescript
+import { createOAuthMiddleware, createIntrospectionValidator } from "@mastra/mcp";
+
+// Option 1: Token introspection (RFC 7662)
+const middleware = createOAuthMiddleware({
+  oauth: {
+    resource: "https://mcp.example.com/mcp",
+    authorizationServers: ["https://auth.example.com"],
+    validateToken: createIntrospectionValidator(
+      "https://auth.example.com/oauth/introspect",
+      { clientId: "mcp-server", clientSecret: "secret" }
+    ),
+  },
+});
+
+// Option 2: Custom validation (JWT, database lookup, etc.)
+const customMiddleware = createOAuthMiddleware({
+  oauth: {
+    resource: "https://mcp.example.com/mcp",
+    authorizationServers: ["https://auth.example.com"],
+    validateToken: async (token, resource) => {
+      const decoded = await verifyJWT(token);
+      if (!decoded) {
+        return { valid: false, error: "invalid_token" };
+      }
+      return {
+        valid: true,
+        scopes: decoded.scope?.split(" ") || [],
+        subject: decoded.sub,
+      };
+    },
+  },
+});
+```
+
+### OAuth Middleware Options
+
 ## Authentication Context
 
-Tools can access request metadata via `context.mcp.extra` when using HTTP-based transports:
+Tools can access request metadata via `context.mcp.extra` when using HTTP-based transports. This allows you to pass authentication info, user context, or any custom data from your HTTP middleware to your MCP tools.
+
+### How It Works
+
+Whatever you set on `req.auth` in your HTTP middleware becomes available as `context.mcp.extra.authInfo` in your tools:
+
+```
+req.auth = { ... }  →  context?.mcp?.extra?.authInfo.extra = { ... }
+```
+
+### Setting Up Authentication Middleware
+
+To pass data to your tools, populate `req.auth` on the Node.js request object in your HTTP server middleware before calling `server.startHTTP()`.
+
+```typescript
+import express from "express";
+
+const app = express();
+
+// Auth middleware - set req.auth before the MCP handler
+app.use("/mcp", (req, res, next) => {
+  const token = req.headers.authorization?.replace("Bearer ", "");
+  const user = verifyToken(token);
+
+  // This entire object becomes context.mcp.extra.authInfo
+  // @ts-ignore - req.auth is read by the MCP SDK
+  req.auth = {
+    token,
+    userId: user.userId,
+    email: user.email,
+  };
+  next();
+});
+
+app.all("/mcp", async (req, res) => {
+  const url = new URL(req.url, `http://${req.headers.host}`);
+  await server.startHTTP({ url, httpPath: "/mcp", req, res });
+});
+```
+
+### Accessing Auth Data in Tools
+
+The `req.auth` object is available as `context.mcp.extra.authInfo` in your tool's execute function:
 
 ```typescript
 execute: async (inputData, context) => {
-  if (!context.mcp?.extra?.authInfo?.token) {
-    return "Authentication required";
+  // Access the auth data you set in middleware
+  const authInfo = context?.mcp?.extra?.authInfo;
+
+  if (!authInfo?.extra?.userId) {
+    return { error: "Authentication required" };
   }
 
-  // Use the auth token
+  // Use the auth data
+  console.log("User ID:", authInfo.extra.userId);
+  console.log("Email:", authInfo.extra.email);
+
   const response = await fetch("/api/data", {
-    headers: { Authorization: `Bearer ${context.mcp.extra.authInfo.token}` },
-    signal: context.mcp.extra.signal,
+    headers: { Authorization: `Bearer ${authInfo.token}` },
+    signal: context?.mcp?.extra?.signal,
   });
 
   return response.json();
 };
 ```
 
-The `extra` object contains:
-
-- `authInfo`: Authentication info (when provided by server middleware)
-- `sessionId`: Session identifier
-- `signal`: AbortSignal for cancellation
-- `sendNotification`/`sendRequest`: MCP protocol functions
-
-> Note: To enable authentication, your HTTP server needs middleware that populates `req.auth` before calling `server.startHTTP()`. For example:
->
-> ```typescript
-> httpServer.createServer((req, res) => {
->   // Add auth middleware
->   req.auth = validateAuthToken(req.headers.authorization);
->
->   // Then pass to MCP server
->   await server.startHTTP({ url, httpPath, req, res });
-> });
-> ```
+### The `extra` Object
+
+The full `context.mcp.extra` object contains:
+
+| Property | Description |
+|----------|-------------|
+| `authInfo` | Whatever you set on `req.auth` in your middleware |
+| `sessionId` | Session identifier for the MCP connection |
+| `signal` | AbortSignal for request cancellation |
+| `sendNotification` | MCP protocol function for sending notifications |
+| `sendRequest` | MCP protocol function for sending requests |
+
+### Complete Example
+
+Here's a complete example showing the data flow from middleware to tool:
+
+```typescript
+import express from "express";
+import { MCPServer } from "@mastra/mcp";
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+const verifyToken = (token: string) => {
+  // TODO: Implement token verification
+  return {
+    userId: "123",
+    email: "test@test.com",
+  };
+};
+
+// 1. Define your tool that uses auth context
+const getUserData = createTool({
+  id: "get-user-data",
+  description: "Fetches data for the authenticated user",
+  inputSchema: z.object({}),
+  execute: async (inputData, context) => {
+    const authInfo = context?.mcp?.extra?.authInfo;
+
+    if (!authInfo?.extra?.userId) {
+      return { error: "Authentication required" };
+    }
+
+    // Access the data you set in middleware
+    return {
+      userId: authInfo.extra.userId,
+      email: authInfo.extra.email,
+    };
+  },
+});
+
+// 2. Create the MCP server with your tools
+const server = new MCPServer({
+  id: "my-server",
+  name: "My Server",
+  version: "1.0.0",
+  tools: { getUserData },
+});
+
+// 3. Set up Express with auth middleware
+const app = express();
+
+app.use("/mcp", (req, res, next) => {
+  const token = req.headers.authorization?.replace("Bearer ", "");
+  const user = verifyToken(token);
+
+  // This entire object becomes context.mcp.extra.authInfo
+  // @ts-ignore - req.auth is read by the MCP SDK
+  req.auth = {
+    token,
+    userId: user.userId,
+    email: user.email,
+  };
+  next();
+});
+
+app.all("/mcp", async (req, res) => {
+  const url = new URL(req.url, `http://${req.headers.host}`);
+  await server.startHTTP({ url, httpPath: "/mcp", req, res });
+});
+
+app.listen(3000);
+```
 
 ## Related Information
 

package/dist/docs/tools-mcp/01-mcp-overview.md

@@ -1,8 +1,8 @@
 > Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient, connect to registries, and share your own tools using MCPServer.
 
 > **Code References:**
-- `Agent`: dist/agent/agent.d.ts → dist/chunk-IC2MIQBW.js:16163
-- `Mastra`: dist/mastra/index.d.ts → dist/chunk-XBZWAUZ3.js:24
+- `Agent`: dist/agent/agent.d.ts → dist/chunk-UVOQLIWL.js:16630
+- `Mastra`: dist/mastra/index.d.ts → dist/chunk-IFPQ2MLB.js:24
 
 # MCP Overview
 
@@ -50,6 +50,10 @@ export const testMcpClient = new MCPClient({
 
 Visit [MCPClient](https://mastra.ai/reference/v1/tools/mcp-client) for a full list of configuration options.
 
+> **Note:** Authentication
+
+For connecting to OAuth-protected MCP servers, see the [OAuth Authentication](https://mastra.ai/reference/v1/tools/mcp-client#oauth-authentication) section.
+
 ## Using `MCPClient` with an agent
 
 To use tools from an MCP server in an agent, import your `MCPClient` and call `.listTools()` in the `tools` parameter. This loads from the defined MCP servers, making them available to the agent.
@@ -103,6 +107,10 @@ export const testMcpServer = new MCPServer({
 
 Visit [MCPServer](https://mastra.ai/reference/v1/tools/mcp-server) for a full list of configuration options.
 
+> **Note:** Authentication
+
+To protect your MCP server with OAuth, see the [OAuth Protection](https://mastra.ai/reference/v1/tools/mcp-server#oauth-protection) section.
+
 ### Serverless deployments
 
 `MCPServer` can be deployed in serverless environments (Cloudflare Workers, Vercel Edge Functions, AWS Lambda, etc.) by enabling the `serverless: true` option in `startHTTP()`. This runs the server in stateless mode, where each request is handled independently without session management.

package/dist/docs/tools-mcp/02-overview.md

@@ -1,8 +1,8 @@
 > Understand what tools are in Mastra, how to add them to agents, and best practices for designing effective tools.
 
 > **Code References:**
-- `createTool`: dist/tools/index.d.ts → dist/chunk-KGE3KAM7.js:285
-- `Tool`: dist/tools/tool.d.ts → dist/chunk-KGE3KAM7.js:115
+- `createTool`: dist/tools/index.d.ts → dist/chunk-N3PAHTKU.js:305
+- `Tool`: dist/tools/tool.d.ts → dist/chunk-N3PAHTKU.js:115
 
 # Using Tools
 
@@ -69,8 +69,8 @@ const advancedTools = () => {};
 const baseTools = () => {};
 
 export const testTool = createTool({
-  execute: async ({ requestContext }) => {
-    const userTier = requestContext.get("user-tier") as UserTier["user-tier"];
+  execute: async (inputData, context) => {
+    const userTier = context?.requestContext?.get("user-tier") as UserTier["user-tier"];
 
     return userTier === "enterprise" ? advancedTools : baseTools;
   },

package/dist/docs/vectors/01-reference.md

@@ -26,7 +26,7 @@ import { LibSQLVector } from "@mastra/libsql";
 // Create a new vector store instance
 const store = new LibSQLVector({
   id: 'libsql-vector',
-  connectionUrl: process.env.DATABASE_URL,
+  url: process.env.DATABASE_URL,
   // Optional: for Turso cloud databases
   authToken: process.env.DATABASE_AUTH_TOKEN,
 });
@@ -193,7 +193,7 @@ export const libsqlAgent = new Agent({
     }),
     vector: new LibSQLVector({
       id: 'libsql-agent-vector',
-      connectionUrl: "file:libsql-agent.db",
+      url: "file:libsql-agent.db",
     }),
     embedder: fastembed,
     options: {
@@ -202,9 +202,7 @@ export const libsqlAgent = new Agent({
         topK: 3,
         messageRange: 2,
       },
-      threads: {
-        generateTitle: true, // Explicitly enable automatic title generation
-      },
+      generateTitle: true, // Explicitly enable automatic title generation
     },
   }),
 });
@@ -235,8 +233,23 @@ import { MongoDBVector } from "@mastra/mongodb";
 
 const store = new MongoDBVector({
   id: 'mongodb-vector',
-  url: process.env.MONGODB_URL,
-  database: process.env.MONGODB_DATABASE,
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DATABASE,
+});
+```
+
+### Custom Embedding Field Path
+
+If you need to store embeddings in a nested field structure (e.g., to integrate with existing MongoDB collections), use the `embeddingFieldPath` option:
+
+```typescript
+import { MongoDBVector } from "@mastra/mongodb";
+
+const store = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DATABASE,
+  embeddingFieldPath: 'text.contentEmbedding', // Store embeddings at text.contentEmbedding
 });
 ```
 
@@ -370,10 +383,12 @@ export const mongodbAgent = new Agent({
   model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new MongoDBStore({
-      url: process.env.MONGODB_URI!,
+      id: 'mongodb-storage',
+      uri: process.env.MONGODB_URI!,
       dbName: process.env.MONGODB_DB_NAME!,
     }),
     vector: new MongoDBVector({
+      id: 'mongodb-vector',
       uri: process.env.MONGODB_URI!,
       dbName: process.env.MONGODB_DB_NAME!,
     }),
@@ -384,9 +399,7 @@ export const mongodbAgent = new Agent({
         topK: 3,
         messageRange: 2,
       },
-      threads: {
-        generateTitle: true, // generates descriptive thread titles automatically
-      },
+      generateTitle: true, // generates descriptive thread titles automatically
     },
   }),
 });

package/dist/docs/voice/01-overview.md

@@ -1,8 +1,8 @@
 > Overview of voice capabilities in Mastra, including text-to-speech, speech-to-text, and real-time speech-to-speech interactions.
 
 > **Code References:**
-- `Agent`: dist/agent/agent.d.ts → dist/chunk-IC2MIQBW.js:16163
-- `CompositeVoice`: dist/voice/index.d.ts → dist/chunk-EK7E4ETB.js:192
+- `Agent`: dist/agent/agent.d.ts → dist/chunk-UVOQLIWL.js:16630
+- `CompositeVoice`: dist/voice/index.d.ts → dist/chunk-TX5GUG5Q.js:192
 
 # Voice in Mastra
 

package/dist/docs/voice/05-reference.md

@@ -595,7 +595,7 @@ import { CompositeVoice } from "@mastra/core/voice";
 import { OpenAIRealtimeVoice } from "@mastra/voice-openai-realtime";
 const realtimeVoice = new OpenAIRealtimeVoice();
 const voice = new CompositeVoice({
-  realtimeProvider: realtimeVoice,
+  realtime: realtimeVoice,
 });
 // This will use the OpenAIRealtimeVoice provider
 await voice.connect();
@@ -880,7 +880,7 @@ const speaker = new Speaker({
 
 const realtimeVoice = new OpenAIRealtimeVoice();
 const voice = new CompositeVoice({
-  realtimeProvider: realtimeVoice,
+  realtime: realtimeVoice,
 });
 
 // Connect to the real-time service

package/dist/docs/workflows/01-overview.md

@@ -1,11 +1,11 @@
 > Workflows in Mastra help you orchestrate complex sequences of tasks with features like branching, parallel execution, resource suspension, and more.
 
 > **Code References:**
-- `createStep`: dist/workflows/index.d.ts → dist/chunk-IC2MIQBW.js:7656
-- `createWorkflow`: dist/workflows/index.d.ts → dist/chunk-IC2MIQBW.js:8318
-- `cloneWorkflow`: dist/workflows/index.d.ts → dist/chunk-IC2MIQBW.js:8321
-- `Mastra`: dist/mastra/index.d.ts → dist/chunk-XBZWAUZ3.js:24
-- `Workflow`: dist/workflows/workflow.d.ts → dist/chunk-IC2MIQBW.js:8334
+- `createStep`: dist/workflows/index.d.ts → dist/chunk-UVOQLIWL.js:7570
+- `createWorkflow`: dist/workflows/index.d.ts → dist/chunk-UVOQLIWL.js:8230
+- `cloneWorkflow`: dist/workflows/index.d.ts → dist/chunk-UVOQLIWL.js:8233
+- `Mastra`: dist/mastra/index.d.ts → dist/chunk-IFPQ2MLB.js:24
+- `Workflow`: dist/workflows/workflow.d.ts → dist/chunk-UVOQLIWL.js:8246
 
 # Workflows overview
 

package/dist/docs/workflows/04-agents-and-tools.md

@@ -131,12 +131,10 @@ const step2 = createStep({
   execute: async ({ inputData, requestContext }) => {
     const { formatted } = inputData;
 
-    const response = await testTool.execute({
-      context: {
-        text: formatted,
-      },
-      requestContext,
-    });
+    const response = await testTool.execute(
+      { text: formatted },
+      { requestContext },
+    );
 
     return {
       emphasized: response.emphasized,