@mastra/mcp 1.0.1 → 1.0.2-alpha.0

package/dist/docs/references/reference-tools-mcp-server.md

@@ -11,39 +11,40 @@ It supports both [stdio (subprocess) and SSE (HTTP) MCP transports](https://mode
 To create a new `MCPServer`, you need to provide some basic information about your server, the tools it will offer, and optionally, any agents you want to expose as tools.
 
 ```typescript
-import { Agent } from "@mastra/core/agent";
-import { createTool } from "@mastra/core/tools";
-import { MCPServer } from "@mastra/mcp";
-import { z } from "zod";
-import { dataProcessingWorkflow } from "../workflows/dataProcessingWorkflow";
+import { Agent } from '@mastra/core/agent'
+import { createTool } from '@mastra/core/tools'
+import { MCPServer } from '@mastra/mcp'
+import { z } from 'zod'
+import { dataProcessingWorkflow } from '../workflows/dataProcessingWorkflow'
 
 const myAgent = new Agent({
-  id: "my-example-agent",
-  name: "MyExampleAgent",
-  description: "A generalist to help with basic questions."
-  instructions: "You are a helpful assistant.",
-  model: "openai/gpt-5.1",
-});
+  id: 'my-example-agent',
+  name: 'MyExampleAgent',
+  description: 'A generalist to help with basic questions.',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5.1',
+})
 
 const weatherTool = createTool({
-  id: "getWeather",
-  description: "Gets the current weather for a location.",
+  id: 'getWeather',
+  description: 'Gets the current weather for a location.',
   inputSchema: z.object({ location: z.string() }),
-  execute: async (inputData) => `Weather in ${inputData.location} is sunny.`,
-});
+  execute: async inputData => `Weather in ${inputData.location} is sunny.`,
+})
 
 const server = new MCPServer({
-  id: "my-custom-server",
-  name: "My Custom Server",
-  version: "1.0.0",
-  description: "A server that provides weather data and agent capabilities",
-  instructions: "Use the available tools to help users with weather information and data processing tasks.",
+  id: 'my-custom-server',
+  name: 'My Custom Server',
+  version: '1.0.0',
+  description: 'A server that provides weather data and agent capabilities',
+  instructions:
+    'Use the available tools to help users with weather information and data processing tasks.',
   tools: { weatherTool },
   agents: { myAgent }, // this agent will become tool "ask_myAgent"
   workflows: {
     dataProcessingWorkflow, // this workflow will become tool "run_dataProcessingWorkflow"
-  }
-});
+  },
+})
 ```
 
 ### Configuration Properties
@@ -121,42 +122,42 @@ Tools exposed through `MCPServer` can access MCP request context (authentication
 **Universal pattern** (works in both contexts):
 
 ```typescript
-const mcpExtra = context?.mcp?.extra ?? context?.requestContext?.get("mcp.extra");
-const authInfo = mcpExtra?.authInfo;
+const mcpExtra = context?.mcp?.extra ?? context?.requestContext?.get('mcp.extra')
+const authInfo = mcpExtra?.authInfo
 ```
 
 #### Example: Tool that works in both contexts
 
 ```typescript
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
 
 const fetchUserData = createTool({
-  id: "fetchUserData",
-  description: "Fetches user data using authentication from MCP context",
+  id: 'fetchUserData',
+  description: 'Fetches user data using authentication from MCP context',
   inputSchema: z.object({
-    userId: z.string().describe("The ID of the user to fetch"),
+    userId: z.string().describe('The ID of the user to fetch'),
   }),
   execute: async (inputData, context) => {
     // Access MCP authentication context
     // When called directly via MCP: context.mcp.extra
     // When called via agent: context.requestContext.get('mcp.extra')
-    const mcpExtra = context?.mcp?.extra || context?.requestContext?.get("mcp.extra");
-    const authInfo = mcpExtra?.authInfo;
+    const mcpExtra = context?.mcp?.extra || context?.requestContext?.get('mcp.extra')
+    const authInfo = mcpExtra?.authInfo
 
     if (!authInfo?.token) {
-      throw new Error("Authentication required");
+      throw new Error('Authentication required')
     }
 
     const response = await fetch(`https://api.example.com/users/${inputData.userId}`, {
       headers: {
         Authorization: `Bearer ${authInfo.token}`,
       },
-    });
+    })
 
-    return response.json();
+    return response.json()
   },
-});
+})
 ```
 
 ## Methods
@@ -175,12 +176,14 @@ Here's how you would start the server using stdio:
 
 ```typescript
 const server = new MCPServer({
-  id: "my-server",
-  name: "My Server",
-  version: "1.0.0",
-  tools: { /* ... */ },
-});
-await server.startStdio();
+  id: 'my-server',
+  name: 'My Server',
+  version: '1.0.0',
+  tools: {
+    /* ... */
+  },
+})
+await server.startStdio()
 ```
 
 ### startSSE()
@@ -206,21 +209,21 @@ async startSSE({
 Here's an example of how you might use `startSSE` within an HTTP server request handler. In this example an MCP client could connect to your MCP server at `http://localhost:1234/sse`:
 
 ```typescript
-import http from "http";
+import http from 'http'
 
 const httpServer = http.createServer(async (req, res) => {
   await server.startSSE({
-    url: new URL(req.url || "", `http://localhost:1234`),
-    ssePath: "/sse",
-    messagePath: "/message",
+    url: new URL(req.url || '', `http://localhost:1234`),
+    ssePath: '/sse',
+    messagePath: '/message',
     req,
     res,
-  });
-});
+  })
+})
 
 httpServer.listen(PORT, () => {
-  console.log(`HTTP server listening on port ${PORT}`);
-});
+  console.log(`HTTP server listening on port ${PORT}`)
+})
 ```
 
 Here are the details for the values needed by the `startSSE` method:
@@ -258,21 +261,21 @@ async startHonoSSE({
 Here's an example of how you might use `startHonoSSE` within an HTTP server request handler. In this example an MCP client could connect to your MCP server at `http://localhost:1234/hono-sse`:
 
 ```typescript
-import http from "http";
+import http from 'http'
 
 const httpServer = http.createServer(async (req, res) => {
   await server.startHonoSSE({
-    url: new URL(req.url || "", `http://localhost:1234`),
-    ssePath: "/hono-sse",
-    messagePath: "/message",
+    url: new URL(req.url || '', `http://localhost:1234`),
+    ssePath: '/hono-sse',
+    messagePath: '/message',
     req,
     res,
-  });
-});
+  })
+})
 
 httpServer.listen(PORT, () => {
-  console.log(`HTTP server listening on port ${PORT}`);
-});
+  console.log(`HTTP server listening on port ${PORT}`)
+})
 ```
 
 Here are the details for the values needed by the `startHonoSSE` method:
@@ -310,68 +313,68 @@ async startHTTP({
 Here's an example of how you might use `startHTTP` within an HTTP server request handler. In this example an MCP client could connect to your MCP server at `http://localhost:1234/http`:
 
 ```typescript
-import http from "http";
+import http from 'http'
 
 const httpServer = http.createServer(async (req, res) => {
   await server.startHTTP({
-    url: new URL(req.url || "", "http://localhost:1234"),
+    url: new URL(req.url || '', 'http://localhost:1234'),
     httpPath: `/mcp`,
     req,
     res,
     options: {
       sessionIdGenerator: () => randomUUID(),
     },
-  });
-});
+  })
+})
 
 httpServer.listen(PORT, () => {
-  console.log(`HTTP server listening on port ${PORT}`);
-});
+  console.log(`HTTP server listening on port ${PORT}`)
+})
 ```
 
 For **serverless environments** (Supabase Edge Functions, Cloudflare Workers, Vercel Edge, etc.), use `serverless: true` to enable stateless operation:
 
 ```typescript
 // Supabase Edge Function example
-import { serve } from "https://deno.land/std@0.168.0/http/server.ts";
-import { MCPServer } from "@mastra/mcp";
+import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
+import { MCPServer } from '@mastra/mcp'
 // Note: You will need to convert req/res format from Deno to Node
-import { toReqRes, toFetchResponse } from "fetch-to-node";
+import { toReqRes, toFetchResponse } from 'fetch-to-node'
 
 const server = new MCPServer({
-  id: "my-serverless-mcp",
-  name: "My Serverless MCP",
-  version: "1.0.0",
-  tools: { /* your tools */ },
-});
+  id: 'my-serverless-mcp',
+  name: 'My Serverless MCP',
+  version: '1.0.0',
+  tools: {
+    /* your tools */
+  },
+})
 
-serve(async (req) => {
-  const url = new URL(req.url);
+serve(async req => {
+  const url = new URL(req.url)
 
-  if (url.pathname === "/mcp") {
+  if (url.pathname === '/mcp') {
     // Convert Deno Request to Node.js-compatible format
-    const { req: nodeReq, res: nodeRes } = toReqRes(req);
+    const { req: nodeReq, res: nodeRes } = toReqRes(req)
 
     await server.startHTTP({
       url,
-      httpPath: "/mcp",
+      httpPath: '/mcp',
       req: nodeReq,
       res: nodeRes,
       options: {
         serverless: true, // ← Enable stateless mode for serverless
       },
-    });
+    })
 
-    return toFetchResponse(nodeRes);
+    return toFetchResponse(nodeRes)
   }
 
-  return new Response("Not found", { status: 404 });
-});
+  return new Response('Not found', { status: 404 })
+})
 ```
 
-> **Info:** **When to use `serverless: true`**
->
-> Use `serverless: true` when deploying to environments where each request runs in a fresh, stateless execution context:
+> **When to use serverless: true:** Use `serverless: true` when deploying to environments where each request runs in a fresh, stateless execution context:
 >
 > - Supabase Edge Functions
 > - Cloudflare Workers
@@ -550,70 +553,66 @@ The `resources` option takes an object of type `MCPServerResources`. This type d
 ```typescript
 export type MCPServerResources = {
   // Callback to list available resources
-  listResources: () => Promise<Resource[]>;
+  listResources: () => Promise<Resource[]>
 
   // Callback to get the content of a specific resource
   getResourceContent: ({
     uri,
   }: {
-    uri: string;
-  }) => Promise<MCPServerResourceContent | MCPServerResourceContent[]>;
+    uri: string
+  }) => Promise<MCPServerResourceContent | MCPServerResourceContent[]>
 
   // Optional callback to list available resource templates
-  resourceTemplates?: () => Promise<ResourceTemplate[]>;
-};
+  resourceTemplates?: () => Promise<ResourceTemplate[]>
+}
 
-export type MCPServerResourceContent = { text?: string } | { blob?: string };
+export type MCPServerResourceContent = { text?: string } | { blob?: string }
 ```
 
 Example:
 
 ```typescript
-import { MCPServer } from "@mastra/mcp";
-import type {
-  MCPServerResourceContent,
-  Resource,
-  ResourceTemplate,
-} from "@mastra/mcp";
+import { MCPServer } from '@mastra/mcp'
+import type { MCPServerResourceContent, Resource, ResourceTemplate } from '@mastra/mcp'
 
 // Resources/resource templates will generally be dynamically fetched.
 const myResources: Resource[] = [
-  { uri: "file://data/123.txt", name: "Data File", mimeType: "text/plain" },
-];
+  { uri: 'file://data/123.txt', name: 'Data File', mimeType: 'text/plain' },
+]
 
 const myResourceContents: Record<string, MCPServerResourceContent> = {
-  "file://data.txt/123": { text: "This is the content of the data file." },
-};
+  'file://data.txt/123': { text: 'This is the content of the data file.' },
+}
 
 const myResourceTemplates: ResourceTemplate[] = [
   {
-    uriTemplate: "file://data/{id}",
-    name: "Data File",
-    description: "A file containing data.",
-    mimeType: "text/plain",
+    uriTemplate: 'file://data/{id}',
+    name: 'Data File',
+    description: 'A file containing data.',
+    mimeType: 'text/plain',
   },
-];
+]
 
 const myResourceHandlers: MCPServerResources = {
   listResources: async () => myResources,
   getResourceContent: async ({ uri }) => {
     if (myResourceContents[uri]) {
-      return myResourceContents[uri];
+      return myResourceContents[uri]
     }
-    throw new Error(`Resource content not found for ${uri}`);
+    throw new Error(`Resource content not found for ${uri}`)
   },
   resourceTemplates: async () => myResourceTemplates,
-};
+}
 
 const serverWithResources = new MCPServer({
-  id: "resourceful-server",
-  name: "Resourceful Server",
-  version: "1.0.0",
+  id: 'resourceful-server',
+  name: 'Resourceful Server',
+  version: '1.0.0',
   tools: {
     /* ... your tools ... */
   },
   resources: myResourceHandlers,
-});
+})
 ```
 
 ### Notifying Clients of Resource Changes
@@ -632,7 +631,7 @@ Example:
 
 ```typescript
 // After updating the content of 'file://data.txt'
-await serverWithResources.resources.notifyUpdated({ uri: "file://data.txt" });
+await serverWithResources.resources.notifyUpdated({ uri: 'file://data.txt' })
 ```
 
 #### `server.resources.notifyListChanged()`
@@ -647,7 +646,7 @@ Example:
 
 ```typescript
 // After adding a new resource to the list managed by 'myResourceHandlers.listResources'
-await serverWithResources.resources.notifyListChanged();
+await serverWithResources.resources.notifyListChanged()
 ```
 
 ## Prompt Handling
@@ -665,7 +664,7 @@ The `prompts` option takes an object of type `MCPServerPrompts`. This type defin
 ```typescript
 export type MCPServerPrompts = {
   // Callback to list available prompts
-  listPrompts: () => Promise<Prompt[]>;
+  listPrompts: () => Promise<Prompt[]>
 
   // Callback to get the messages/content for a specific prompt
   getPromptMessages?: ({
@@ -673,80 +672,78 @@ export type MCPServerPrompts = {
     version,
     args,
   }: {
-    name: string;
-    version?: string;
-    args?: any;
-  }) => Promise<{ prompt: Prompt; messages: PromptMessage[] }>;
-};
+    name: string
+    version?: string
+    args?: any
+  }) => Promise<{ prompt: Prompt; messages: PromptMessage[] }>
+}
 ```
 
 Example:
 
 ```typescript
-import { MCPServer } from "@mastra/mcp";
-import type { Prompt, PromptMessage, MCPServerPrompts } from "@mastra/mcp";
+import { MCPServer } from '@mastra/mcp'
+import type { Prompt, PromptMessage, MCPServerPrompts } from '@mastra/mcp'
 
 const prompts: Prompt[] = [
   {
-    name: "analyze-code",
-    description: "Analyze code for improvements",
-    version: "v1",
+    name: 'analyze-code',
+    description: 'Analyze code for improvements',
+    version: 'v1',
   },
   {
-    name: "analyze-code",
-    description: "Analyze code for improvements (new logic)",
-    version: "v2",
+    name: 'analyze-code',
+    description: 'Analyze code for improvements (new logic)',
+    version: 'v2',
   },
-];
+]
 
 const myPromptHandlers: MCPServerPrompts = {
   listPrompts: async () => prompts,
   getPromptMessages: async ({ name, version, args }) => {
-    if (name === "analyze-code") {
-      if (version === "v2") {
-        const prompt = prompts.find(
-          (p) => p.name === name && p.version === "v2",
-        );
-        if (!prompt) throw new Error("Prompt version not found");
+    if (name === 'analyze-code') {
+      if (version === 'v2') {
+        const prompt = prompts.find(p => p.name === name && p.version === 'v2')
+        if (!prompt) throw new Error('Prompt version not found')
         return {
           prompt,
           messages: [
             {
-              role: "user",
+              role: 'user',
               content: {
-                type: "text",
+                type: 'text',
                 text: `Analyze this code with the new logic: ${args.code}`,
               },
             },
           ],
-        };
+        }
       }
       // Default or v1
-      const prompt = prompts.find((p) => p.name === name && p.version === "v1");
-      if (!prompt) throw new Error("Prompt version not found");
+      const prompt = prompts.find(p => p.name === name && p.version === 'v1')
+      if (!prompt) throw new Error('Prompt version not found')
       return {
         prompt,
         messages: [
           {
-            role: "user",
-            content: { type: "text", text: `Analyze this code: ${args.code}` },
+            role: 'user',
+            content: { type: 'text', text: `Analyze this code: ${args.code}` },
           },
         ],
-      };
+      }
     }
-    throw new Error("Prompt not found");
+    throw new Error('Prompt not found')
   },
-};
+}
 
 const serverWithPrompts = new MCPServer({
-  id: "promptful-server",
-  name: "Promptful Server",
-  version: "1.0.0",
+  id: 'promptful-server',
+  name: 'Promptful Server',
+  version: '1.0.0',
   tools: {
     /* ... */
   },
   prompts: myPromptHandlers,
-});
+})
 ```
 
 ### Notifying Clients of Prompt Changes
@@ -758,7 +755,7 @@ If the available prompts change, your server can notify connected clients:
 Call this method when the overall list of available prompts has changed (e.g., a prompt was added or removed). This will send a `notifications/prompts/list_changed` message to clients, prompting them to re-fetch the list of prompts.
 
 ```typescript
-await serverWithPrompts.prompts.notifyListChanged();
+await serverWithPrompts.prompts.notifyListChanged()
 ```
 
 ### Best Practices for Prompt Handling
@@ -798,19 +795,19 @@ execute: async (inputData, context) => {
 
   // Access authentication information (when available)
   if (context.mcp?.extra?.authInfo) {
-    console.log("Authenticated request from:", context.mcp.extra.authInfo.clientId);
+    console.log('Authenticated request from:', context.mcp.extra.authInfo.clientId)
   }
 
   // Use elicitation capabilities
   const result = await context.mcp.elicitation.sendRequest({
-    message: "Please provide information",
+    message: 'Please provide information',
     requestedSchema: {
       /* schema */
     },
-  });
+  })
 
-  return result;
-};
+  return result
+}
 ```
 
 ### How Elicitation Works
@@ -829,75 +826,72 @@ A common use case is during tool execution. When a tool needs user input, it can
 Here's an example of a tool that uses elicitation to collect user contact information:
 
 ```typescript
-import { MCPServer } from "@mastra/mcp";
-import { createTool } from "@mastra/core/tools";
-import { z } from "zod";
+import { MCPServer } from '@mastra/mcp'
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
 
 const server = new MCPServer({
-  id: "interactive-server",
-  name: "Interactive Server",
-  version: "1.0.0",
+  id: 'interactive-server',
+  name: 'Interactive Server',
+  version: '1.0.0',
   tools: {
     collectContactInfo: createTool({
-      id: "collectContactInfo",
-      description: "Collects user contact information through elicitation",
+      id: 'collectContactInfo',
+      description: 'Collects user contact information through elicitation',
       inputSchema: z.object({
-        reason: z
-          .string()
-          .optional()
-          .describe("Reason for collecting contact info"),
+        reason: z.string().optional().describe('Reason for collecting contact info'),
       }),
       execute: async (inputData, context) => {
-        const { reason } = inputData;
+        const { reason } = inputData
 
         // Log session info if available
-        console.log("Request from session:", context.mcp?.extra?.sessionId);
+        console.log('Request from session:', context.mcp?.extra?.sessionId)
 
         try {
           // Request user input via elicitation
           const result = await context.mcp.elicitation.sendRequest({
             message: reason
               ? `Please provide your contact information. ${reason}`
-              : "Please provide your contact information",
+              : 'Please provide your contact information',
             requestedSchema: {
-              type: "object",
+              type: 'object',
               properties: {
                 name: {
-                  type: "string",
-                  title: "Full Name",
-                  description: "Your full name",
+                  type: 'string',
+                  title: 'Full Name',
+                  description: 'Your full name',
                 },
                 email: {
-                  type: "string",
-                  title: "Email Address",
-                  description: "Your email address",
-                  format: "email",
+                  type: 'string',
+                  title: 'Email Address',
+                  description: 'Your email address',
+                  format: 'email',
                 },
                 phone: {
-                  type: "string",
-                  title: "Phone Number",
-                  description: "Your phone number (optional)",
+                  type: 'string',
+                  title: 'Phone Number',
+                  description: 'Your phone number (optional)',
                 },
               },
-              required: ["name", "email"],
+              required: ['name', 'email'],
             },
-          });
+          })
 
           // Handle the user's response
-          if (result.action === "accept") {
-            return `Contact information collected: ${JSON.stringify(result.content, null, 2)}`;
-          } else if (result.action === "decline") {
-            return "Contact information collection was declined by the user.";
+          if (result.action === 'accept') {
+            return `Contact information collected: ${JSON.stringify(result.content, null, 2)}`
+          } else if (result.action === 'decline') {
+            return 'Contact information collection was declined by the user.'
           } else {
-            return "Contact information collection was cancelled by the user.";
+            return 'Contact information collection was cancelled by the user.'
           }
         } catch (error) {
-          return `Error collecting contact information: ${error}`;
+          return `Error collecting contact information: ${error}`
         }
       },
     }),
   },
-});
+})
 ```
 
 ### Elicitation Request Schema
@@ -983,9 +977,9 @@ The `ElicitResult` type:
 
 ```typescript
 type ElicitResult = {
-  action: "accept" | "decline" | "cancel";
-  content?: any; // Only present when action is 'accept'
-};
+  action: 'accept' | 'decline' | 'cancel'
+  content?: any // Only present when action is 'accept'
+}
 ```
 
 ## OAuth Protection
@@ -993,41 +987,43 @@ type ElicitResult = {
 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";
+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 */ },
-});
+  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"]),
+    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",
-});
+  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");
+  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.)
+  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 });
-});
+  await mcpServer.startHTTP({ url, httpPath: '/mcp', req, res })
+})
 
-httpServer.listen(3000);
+httpServer.listen(3000)
 ```
 
 The middleware automatically:
@@ -1041,38 +1037,38 @@ The middleware automatically:
 For production, use proper token validation:
 
 ```typescript
-import { createOAuthMiddleware, createIntrospectionValidator } from "@mastra/mcp";
+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" }
-    ),
+    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"],
+    resource: 'https://mcp.example.com/mcp',
+    authorizationServers: ['https://auth.example.com'],
     validateToken: async (token, resource) => {
-      const decoded = await verifyJWT(token);
+      const decoded = await verifyJWT(token)
       if (!decoded) {
-        return { valid: false, error: "invalid_token" };
+        return { valid: false, error: 'invalid_token' }
       }
       return {
         valid: true,
-        scopes: decoded.scope?.split(" ") || [],
+        scopes: decoded.scope?.split(' ') || [],
         subject: decoded.sub,
-      };
+      }
     },
   },
-});
+})
 ```
 
 ### OAuth Middleware Options
@@ -1106,14 +1102,14 @@ req.auth = { ... }  →  context?.mcp?.extra?.authInfo.extra = { ... }
 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";
+import express from 'express'
 
-const app = 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);
+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
@@ -1121,14 +1117,14 @@ app.use("/mcp", (req, res, next) => {
     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 });
-});
+  }
+  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
@@ -1138,23 +1134,23 @@ The `req.auth` object is available as `context.mcp.extra.authInfo` in your tool'
 ```typescript
 execute: async (inputData, context) => {
   // Access the auth data you set in middleware
-  const authInfo = context?.mcp?.extra?.authInfo;
+  const authInfo = context?.mcp?.extra?.authInfo
 
   if (!authInfo?.extra?.userId) {
-    return { error: "Authentication required" };
+    return { error: 'Authentication required' }
   }
 
   // Use the auth data
-  console.log("User ID:", authInfo.extra.userId);
-  console.log("Email:", authInfo.extra.email);
+  console.log('User ID:', authInfo.extra.userId)
+  console.log('Email:', authInfo.extra.email)
 
-  const response = await fetch("/api/data", {
+  const response = await fetch('/api/data', {
     headers: { Authorization: `Bearer ${authInfo.token}` },
     signal: context?.mcp?.extra?.signal,
-  });
+  })
 
-  return response.json();
-};
+  return response.json()
+}
 ```
 
 ### Passing `RequestContext` through to agent
@@ -1162,19 +1158,19 @@ execute: async (inputData, context) => {
 ```typescript
 execute: async (inputData, context) => {
   // Access the auth data you set in middleware
-  const authInfo = context?.mcp?.extra?.authInfo;
+  const authInfo = context?.mcp?.extra?.authInfo
 
   const requestContext = context.requestContext || new RequestContext().set('someKey', authInfo)
 
   if (!authInfo?.extra?.userId) {
-    return { error: "Authentication required" };
+    return { error: 'Authentication required' }
   }
 
   // Use the auth data
-  console.log("User ID:", authInfo.extra.userId);
-  console.log("Email:", authInfo.extra.email);
+  console.log('User ID:', authInfo.extra.userId)
+  console.log('Email:', authInfo.extra.email)
 
-  const agent = context?.mastra?.getAgentById('some-agent-id');
+  const agent = context?.mastra?.getAgentById('some-agent-id')
 
   if (!agent) {
     return { error: "Agent 'some-agent-id' not found" }
@@ -1183,7 +1179,7 @@ execute: async (inputData, context) => {
   const response = await agent.generate(prompt, { requestContext })
 
   return response.text
-};
+}
 ```
 
 ### The `extra` Object
@@ -1203,53 +1199,53 @@ The full `context.mcp.extra` object contains:
 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";
+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",
-  };
-};
+    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",
+  id: 'get-user-data',
+  description: 'Fetches data for the authenticated user',
   inputSchema: z.object({}),
   execute: async (inputData, context) => {
-    const authInfo = context?.mcp?.extra?.authInfo;
+    const authInfo = context?.mcp?.extra?.authInfo
 
     if (!authInfo?.extra?.userId) {
-      return { error: "Authentication required" };
+      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",
+  id: 'my-server',
+  name: 'My Server',
+  version: '1.0.0',
   tools: { getUserData },
-});
+})
 
 // 3. Set up Express with auth middleware
-const app = express();
+const app = express()
 
-app.use("/mcp", (req, res, next) => {
-  const token = req.headers.authorization?.replace("Bearer ", "");
-  const user = verifyToken(token);
+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
@@ -1257,16 +1253,16 @@ app.use("/mcp", (req, res, next) => {
     token,
     userId: user.userId,
     email: user.email,
-  };
-  next();
-});
+  }
+  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.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);
+app.listen(3000)
 ```
 
 ## Related Information