@mastra/mcp 1.0.0-beta.9 → 1.0.0

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

@@ -46,9 +46,13 @@ 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 `.getTools()` in the `tools` parameter. This loads from the defined MCP servers, making them available to the 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.
 
 ```typescript {3,15} title="src/mastra/agents/test-agent.ts"
 import { Agent } from "@mastra/core/agent";
@@ -56,6 +60,7 @@ import { Agent } from "@mastra/core/agent";
 import { testMcpClient } from "../mcp/test-mcp-client";
 
 export const testAgent = new Agent({
+  id: "test-agent",
   name: "Test Agent",
   description: "You are a helpful AI assistant",
   instructions: `
@@ -65,7 +70,7 @@ export const testAgent = new Agent({
 
       Answer questions using the information you find using the MCP Servers.`,
   model: "openai/gpt-5.1",
-  tools: await testMcpClient.getTools(),
+  tools: await testMcpClient.listTools(),
 });
 ```
 
@@ -98,6 +103,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.
+
 ## Registering an `MCPServer`
 
 To make an MCP server available to other systems or agents that support the protocol, register it in the main `Mastra` instance using `mcpServers`.
@@ -116,20 +125,20 @@ export const mastra = new Mastra({
 
 `MCPClient` offers two approaches to retrieving tools from connected servers, suitable for different application architectures:
 
-| Feature           | Static Configuration (`await mcp.getTools()`) | Dynamic Configuration (`await mcp.getToolsets()`)    |
-| :---------------- | :-------------------------------------------- | :--------------------------------------------------- |
-| **Use Case**      | Single-user, static config (e.g., CLI tool)   | Multi-user, dynamic config (e.g., SaaS app)          |
-| **Configuration** | Fixed at agent initialization                 | Per-request, dynamic                                 |
-| **Credentials**   | Shared across all uses                        | Can vary per user/request                            |
-| **Agent Setup**   | Tools added in `Agent` constructor            | Tools passed in `.generate()` or `.stream()` options |
+| Feature           | Static Configuration (`await mcp.listTools()`) | Dynamic Configuration (`await mcp.listToolsets()`)   |
+| :---------------- | :--------------------------------------------- | :--------------------------------------------------- |
+| **Use Case**      | Single-user, static config (e.g., CLI tool)    | Multi-user, dynamic config (e.g., SaaS app)          |
+| **Configuration** | Fixed at agent initialization                  | Per-request, dynamic                                 |
+| **Credentials**   | Shared across all uses                         | Can vary per user/request                            |
+| **Agent Setup**   | Tools added in `Agent` constructor             | Tools passed in `.generate()` or `.stream()` options |
 
 ### Static tools
 
-Use the `.getTools()` method to fetch tools from all configured MCP servers. This is suitable when configuration (such as API keys) is static and consistent across users or requests. Call it once and pass the result to the `tools` property when defining your agent.
+Use the `.listTools()` method to fetch tools from all configured MCP servers. This is suitable when configuration (such as API keys) is static and consistent across users or requests. Call it once and pass the result to the `tools` property when defining your agent.
 
 > **Note:**
 
-Visit [getTools()](https://mastra.ai/reference/v1/tools/mcp-client#gettools) for more information.
+Visit [listTools()](https://mastra.ai/reference/v1/tools/mcp-client#listtools) for more information.
 
 ```typescript {6} title="src/mastra/agents/test-agent.ts"
 import { Agent } from "@mastra/core/agent";
@@ -137,13 +146,14 @@ import { Agent } from "@mastra/core/agent";
 import { testMcpClient } from "../mcp/test-mcp-client";
 
 export const testAgent = new Agent({
-  tools: await testMcpClient.getTools(),
+  id: "test-agent",
+  tools: await testMcpClient.listTools(),
 });
 ```
 
 ### Dynamic tools
 
-Use the `.getToolsets()` method when tool configuration may vary by request or user, such as in a multi-tenant system where each user provides their own API key. This method returns toolsets that can be passed to the `toolsets` option in the agent's `.generate()` or `.stream()` calls.
+Use the `.listToolsets()` method when tool configuration may vary by request or user, such as in a multi-tenant system where each user provides their own API key. This method returns toolsets that can be passed to the `toolsets` option in the agent's `.generate()` or `.stream()` calls.
 
 ```typescript {5-16,21}
 import { MCPClient } from "@mastra/mcp";
@@ -166,7 +176,7 @@ async function handleRequest(userPrompt: string, userApiKey: string) {
   const agent = mastra.getAgent("testAgent");
 
   const response = await agent.generate(userPrompt, {
-    toolsets: await userMcp.getToolsets(),
+    toolsets: await userMcp.listToolsets(),
   });
 
   await userMcp.disconnect();
@@ -179,7 +189,7 @@ async function handleRequest(userPrompt: string, userApiKey: string) {
 
 > **Note:**
 
-Visit [getToolsets()](https://mastra.ai/reference/v1/tools/mcp-client#gettoolsets) for more information.
+Visit [listToolsets()](https://mastra.ai/reference/v1/tools/mcp-client#listtoolsets) for more information.
 
 ## Connecting to an MCP registry
 

package/dist/docs/mcp/02-publishing-mcp-server.md

@@ -104,8 +104,8 @@ const mcp = new MCPClient({
 });
 
 // You can then get tools or toolsets from this configuration to use in your agent
-const tools = await mcp.getTools();
-const toolsets = await mcp.getToolsets();
+const tools = await mcp.listTools();
+const toolsets = await mcp.listToolsets();
 ```
 
 Note: If you published without an organization scope, the `args` might just be `["-y", "your-package-name@latest"]`.

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

@@ -46,7 +46,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()
@@ -591,6 +591,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
@@ -622,6 +720,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",
@@ -677,6 +776,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",
@@ -1760,44 +1860,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

@@ -46,6 +46,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.
@@ -99,6 +103,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.