@mastra/mcp-docs-server 1.2.8-alpha.0 → 1.2.8-alpha.19

package/.docs/reference/tools/create-tool.md

@@ -10,25 +10,29 @@ The `createTool()` function is used to define custom tools that your Mastra agen
 import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
-export const tool = createTool({
-  id: 'test-tool',
-  description: 'Reverse the input string',
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Get the current weather for a location',
   inputSchema: z.object({
-    input: z.string(),
+    location: z.string(),
   }),
   outputSchema: z.object({
-    output: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async inputData => {
-    const reversed = inputData.input.split('').reverse().join('')
-
+  execute: async ({ location }) => {
     return {
-      output: reversed,
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
 })
 ```
 
+The first `execute` parameter is the validated value from `inputSchema`. Destructure schema fields directly in the function signature, as shown with `{ location }`. The optional second parameter contains the execution context.
+
 ## Parameters
 
 **id** (`string`): A unique identifier for the tool.
@@ -112,10 +116,12 @@ export const weatherTool = createTool({
     location: z.string(),
   }),
   outputSchema: z.object({
-    weather: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async inputData => {
-    // Fetch weather data
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```
@@ -137,11 +143,13 @@ export const weatherTool = createTool({
   ),
   outputSchema: toStandardJsonSchema(
     v.object({
-      weather: v.string(),
+      location: v.string(),
+      temperatureCelsius: v.number(),
+      conditions: v.string(),
     }),
   ),
-  execute: async inputData => {
-    // Fetch weather data
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```
@@ -159,10 +167,12 @@ export const weatherTool = createTool({
     location: 'string',
   }),
   outputSchema: type({
-    weather: 'string',
+    location: 'string',
+    temperatureCelsius: 'number',
+    conditions: 'string',
   }),
-  execute: async inputData => {
-    // Fetch weather data
+  execute: async ({ location }) => {
+    return { location, temperatureCelsius: 21, conditions: 'sunny' }
   },
 })
 ```
@@ -176,18 +186,22 @@ import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
 export const weatherTool = createTool({
-  id: 'get-weather',
-  description: 'Get weather for a city',
+  id: 'weather-tool',
+  description: 'Get the current weather for a location',
   strict: true,
   inputSchema: z.object({
-    city: z.string(),
-    units: z.enum(['metric', 'imperial']),
+    location: z.string(),
+  }),
+  outputSchema: z.object({
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async ({ city, units }) => {
+  execute: async ({ location }) => {
     return {
-      city,
-      units,
-      forecast: 'sunny',
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
 })
@@ -204,28 +218,31 @@ import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
 export const weatherTool = createTool({
-  id: 'get-weather',
-  description: 'Get weather for a city',
+  id: 'weather-tool',
+  description: 'Get the current weather for a location',
   inputSchema: z.object({
-    city: z.string(),
+    location: z.string(),
   }),
   outputSchema: z.object({
-    city: z.string(),
-    temperature: z.number(),
-    condition: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
     radarImageUrl: z.string().url(),
   }),
-  execute: async ({ city }) => ({
-    city,
-    temperature: 72,
-    condition: 'sunny',
+  execute: async ({ location }) => ({
+    location,
+    temperatureCelsius: 21,
+    conditions: 'sunny',
     radarImageUrl: 'https://example.com/radar/seattle.png',
   }),
   toModelOutput: output => {
     return {
       type: 'content',
       value: [
-        { type: 'text', text: `${output.city}: ${output.temperature}F and ${output.condition}` },
+        {
+          type: 'text',
+          text: `${output.location}: ${output.temperatureCelsius}°C and ${output.conditions}`,
+        },
         { type: 'image-url', url: output.radarImageUrl },
       ],
     }
@@ -294,11 +311,16 @@ import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
 export const weatherTool = createTool({
-  id: 'get-weather',
-  description: 'Get current weather for a location',
+  id: 'weather-tool',
+  description: 'Get the current weather for a location',
   inputSchema: z.object({
     location: z.string().describe('City name or coordinates'),
   }),
+  outputSchema: z.object({
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
+  }),
   // MCP-specific properties
   mcp: {
     // Annotations for client behavior hints
@@ -315,9 +337,11 @@ export const weatherTool = createTool({
       category: 'weather',
     },
   },
-  execute: async inputData => {
+  execute: async ({ location }) => {
     return {
-      weather: `Current weather for ${inputData.location}: sunny`,
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
 })
@@ -334,19 +358,21 @@ import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
 export const weatherTool = createTool({
-  id: 'get-weather',
-  description: 'Get weather for a city',
+  id: 'weather-tool',
+  description: 'Get the current weather for a location',
   inputSchema: z.object({
-    city: z.string(),
+    location: z.string(),
   }),
   outputSchema: z.object({
-    city: z.string(),
-    forecast: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
-  execute: async ({ city }) => {
+  execute: async ({ location }) => {
     return {
-      city,
-      forecast: 'sunny',
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
   onInputStart: ({ toolCallId }) => {
@@ -356,10 +382,10 @@ export const weatherTool = createTool({
     console.log(`Tool call ${toolCallId} received input chunk: ${inputTextDelta}`)
   },
   onInputAvailable: ({ input, toolCallId }) => {
-    console.log(`Tool call ${toolCallId} received city: ${input.city}`)
+    console.log(`Tool call ${toolCallId} received location: ${input.location}`)
   },
   onOutput: ({ output, toolCallId, toolName }) => {
-    console.log(`Tool ${toolName} call ${toolCallId} returned forecast: ${output.forecast}`)
+    console.log(`Tool ${toolName} call ${toolCallId} returned conditions: ${output.conditions}`)
   },
 })
 ```
@@ -403,7 +429,7 @@ export const tool = createTool({
   id: 'example-tool',
   description: 'Example tool with hooks',
   inputSchema: z.object({
-    city: z.string(),
+    location: z.string(),
   }),
   onInputAvailable: ({ input, toolCallId, messages, abortSignal }) => {
     console.log(`Tool received complete input:`, input)

package/.docs/reference/tools/mcp-client.md

@@ -207,6 +207,34 @@ const instructionsByServer = mcp.getServerInstructions()
 console.log(instructionsByServer.db)
 ```
 
+### `authenticate()`
+
+Runs the interactive OAuth authorization-code flow for a server configured with an `MCPOAuthClientProvider` whose redirect URL points at a loopback address. Starts a local callback server, delivers the authorization URL through the provider's `onRedirectToAuthorization` callback, waits for the browser to return the authorization code, exchanges it for tokens, and reconnects. See [Interactive browser authentication](#interactive-browser-authentication).
+
+The optional `timeoutMs` bounds how long the flow waits for the browser to return the authorization code before rejecting, and defaults to 5 minutes.
+
+```typescript
+async authenticate(serverName: string, options?: { timeoutMs?: number }): Promise<void>
+```
+
+### `getServerAuthState()`
+
+Returns the OAuth authorization state of a configured server: `'needs-auth'` after a connection attempt was rejected with an authorization error, `'authorized'` once the server accepted the provider's credentials, or `undefined` for servers without an `authProvider` or that haven't attempted a connection yet.
+
+```typescript
+getServerAuthState(serverName: string): 'needs-auth' | 'authorized' | undefined
+```
+
+### `cancelAuthentication()`
+
+Cancels an in-progress `authenticate()` flow for a server, so an abandoned browser authorization does not leave the client waiting indefinitely. It aborts the flow (including its setup phase, before the callback server binds), closes the local callback server if one is listening, and the pending `authenticate()` call rejects. Returns `true` if a flow was cancelled, or `false` when no flow was in progress.
+
+The resulting `getServerAuthState()` depends on how far the flow had progressed: a flow cancelled after the server rejected the connection with `401` stays at `'needs-auth'` and can be retried immediately, while a flow cancelled during the setup phase — before any connection was attempted — leaves the state unchanged (typically `undefined`).
+
+```typescript
+async cancelAuthentication(serverName: string): Promise<boolean>
+```
+
 ### `disconnect()`
 
 Disconnects from all MCP servers and cleans up resources.
@@ -252,9 +280,7 @@ This is useful for connecting external MCP servers that implement the MCP Apps e
 The `MCPClient` instance has a `resources` property that provides access to resource-related operations.
 
 ```typescript
-const mcpClient = new MCPClient({
-  /* ...servers configuration... */
-})
+const mcpClient = new MCPClient({/* ...servers configuration... */})
 
 // Access resource methods via mcpClient.resources
 const allResourcesByServer = await mcpClient.resources.list()
@@ -383,9 +409,7 @@ mcpClient.resources.onListChanged('myWeatherServer', () => {
 The `MCPClient` instance has an `elicitation` property that provides access to elicitation-related operations. Elicitation allows MCP servers to request structured information from users.
 
 ```typescript
-const mcpClient = new MCPClient({
-  /* ...servers configuration... */
-})
+const mcpClient = new MCPClient({/* ...servers configuration... */})
 
 // Set up elicitation handler
 mcpClient.elicitation.onRequest('serverName', async request => {
@@ -524,9 +548,7 @@ await mcpClient.elicitation.onRequest('interactiveServer', async request => {
 The `MCPClient` instance has a `prompts` property that provides access to prompt-related operations.
 
 ```typescript
-const mcpClient = new MCPClient({
-  /* ...servers configuration... */
-})
+const mcpClient = new MCPClient({/* ...servers configuration... */})
 
 // Access prompt methods via mcpClient.prompts
 const allPromptsByServer = await mcpClient.prompts.list()
@@ -821,6 +843,74 @@ const client = new MCPClient({
 })
 ```
 
+Give each server its own `MCPOAuthClientProvider` instance. A provider holds per-server session and credential state during authorization, so sharing one instance across multiple servers lets their flows overwrite each other. When configuring several protected servers, construct a separate provider for each.
+
+### Interactive browser authentication
+
+When a server rejects a connection because authorization is required, the client records a `'needs-auth'` state instead of failing outright. Calling `authenticate()` then completes the flow end to end: it starts a one-shot callback server on the provider's loopback redirect URL (falling back to the next sequential ports when it is in use), lets the SDK run discovery and dynamic client registration, delivers the authorization URL through `onRedirectToAuthorization` — open it in the user's browser — and finishes the token exchange once the browser returns the authorization code:
+
+```typescript
+import { MCPClient, MCPOAuthClientProvider } from '@mastra/mcp'
+
+const oauthProvider = new MCPOAuthClientProvider({
+  redirectUrl: 'http://127.0.0.1:5533/oauth/callback',
+  clientMetadata: {
+    redirect_uris: ['http://127.0.0.1:5533/oauth/callback'],
+    client_name: 'My MCP Client',
+    grant_types: ['authorization_code', 'refresh_token'],
+    response_types: ['code'],
+  },
+  onRedirectToAuthorization: url => {
+    // Open the user's browser at the consent page
+    console.log(`Please visit: ${url}`)
+  },
+})
+
+const mcp = new MCPClient({
+  servers: {
+    protectedServer: {
+      url: new URL('https://mcp.example.com/mcp'),
+      authProvider: oauthProvider,
+    },
+  },
+})
+
+try {
+  await mcp.listTools()
+} catch {
+  if (mcp.getServerAuthState('protectedServer') === 'needs-auth') {
+    await mcp.authenticate('protectedServer')
+  }
+}
+```
+
+Concurrent `authenticate()` calls for the same server join the pending flow; different servers authenticate independently. With valid stored tokens the call simply reconnects without opening a browser.
+
+Hosts that drive the flow themselves can capture the authorization code with the exported `createOAuthCallbackServer` helper, which binds a one-shot loopback server, validates the OAuth `state` parameter, and resolves with the code. It creates a plain HTTP server, so it is only for local loopback redirects. Web applications that use an HTTPS redirect URL must host their own callback endpoint and drive the provider directly rather than using this helper:
+
+```typescript
+import { createOAuthCallbackServer, getCallbackUrlCandidates } from '@mastra/mcp'
+
+// getCallbackUrlCandidates() lists every URL the helper may bind, so register
+// all of them as redirect_uris during client registration to cover port fallback.
+const redirectUris = getCallbackUrlCandidates('http://127.0.0.1:5533/oauth/callback').map(url =>
+  url.toString(),
+)
+
+const server = await createOAuthCallbackServer({
+  redirectUrl: 'http://127.0.0.1:5533/oauth/callback',
+  state: expectedState,
+})
+
+// server.url reflects the port actually bound — use it as the redirect_uri.
+try {
+  const { code } = await server.waitForCode()
+  // Exchange the code here.
+} finally {
+  await server.close()
+}
+```
+
 ### Quick Token Provider
 
 For testing or when you already have a valid access token:
@@ -884,9 +974,7 @@ class DatabaseOAuthStorage implements OAuthStorage {
 
 const provider = new MCPOAuthClientProvider({
   redirectUrl: 'http://localhost:3000/callback',
-  clientMetadata: {
-    /* ... */
-  },
+  clientMetadata: {/* ... */},
   storage: new DatabaseOAuthStorage(db, 'user-123'),
 })
 ```
@@ -1021,33 +1109,25 @@ For example, if you try to create multiple instances with the same configuration
 ```typescript
 // First instance - OK
 const mcp1 = new MCPClient({
-  servers: {
-    /* ... */
-  },
+  servers: {/* ... */},
 })
 
 // Second instance with same config - Will throw an error
 const mcp2 = new MCPClient({
-  servers: {
-    /* ... */
-  },
+  servers: {/* ... */},
 })
 
 // To fix, either:
 // 1. Add unique IDs
 const mcp3 = new MCPClient({
   id: 'instance-1',
-  servers: {
-    /* ... */
-  },
+  servers: {/* ... */},
 })
 
 // 2. Or disconnect before recreating
 await mcp1.disconnect()
 const mcp4 = new MCPClient({
-  servers: {
-    /* ... */
-  },
+  servers: {/* ... */},
 })
 ```
 

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

@@ -187,9 +187,7 @@ const server = new MCPServer({
   id: 'my-server',
   name: 'My Server',
   version: '1.0.0',
-  tools: {
-    /* ... */
-  },
+  tools: {/* ... */},
 })
 await server.startStdio()
 ```
@@ -353,9 +351,7 @@ const server = new MCPServer({
   id: 'my-serverless-mcp',
   name: 'My Serverless MCP',
   version: '1.0.0',
-  tools: {
-    /* your tools */
-  },
+  tools: {/* your tools */},
 })
 
 serve(async req => {
@@ -637,9 +633,7 @@ const serverWithResources = new MCPServer({
   id: 'resourceful-server',
   name: 'Resourceful Server',
   version: '1.0.0',
-  tools: {
-    /* ... your tools ... */
-  },
+  tools: {/* ... your tools ... */},
   resources: myResourceHandlers,
 })
 ```
@@ -768,9 +762,7 @@ const serverWithPrompts = new MCPServer({
   id: 'promptful-server',
   name: 'Promptful Server',
   version: '1.0.0',
-  tools: {
-    /* ... */
-  },
+  tools: {/* ... */},
   prompts: myPromptHandlers,
 })
 ```
@@ -966,9 +958,7 @@ execute: async (inputData, context) => {
   // Use elicitation capabilities
   const result = await context.mcp.elicitation.sendRequest({
     message: 'Please provide information',
-    requestedSchema: {
-      /* schema */
-    },
+    requestedSchema: {/* schema */},
   })
 
   return result
@@ -1159,9 +1149,7 @@ const mcpServer = new MCPServer({
   id: 'protected-server',
   name: 'Protected MCP Server',
   version: '1.0.0',
-  tools: {
-    /* your tools */
-  },
+  tools: {/* your tools */},
 })
 
 // Create OAuth middleware
@@ -1342,21 +1330,48 @@ To pass data to your tools, populate `req.auth` on the Node.js request object in
 ```typescript
 import express from 'express'
 
+type MCPAuthenticatedRequest = express.Request & {
+  auth?: {
+    token: string
+    clientId: string
+    scopes: string[]
+    expiresAt?: number
+    extra?: Record<string, unknown>
+  }
+}
+
 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,
+app.use('/mcp', async (req, res, next) => {
+  const authorization = req.headers.authorization
+
+  if (!authorization?.startsWith('Bearer ')) {
+    res.status(401).json({ error: 'Missing bearer token' })
+    return
+  }
+
+  const token = authorization.slice('Bearer '.length)
+
+  try {
+    const user = await verifyToken(token)
+
+    // This entire object becomes context.mcp.extra.authInfo
+    const authenticatedRequest = req as MCPAuthenticatedRequest
+    authenticatedRequest.auth = {
+      token,
+      clientId: user.clientId,
+      scopes: user.scopes,
+      expiresAt: user.expiresAt,
+      extra: {
+        userId: user.userId,
+        email: user.email,
+      },
+    }
+    next()
+  } catch {
+    res.status(401).json({ error: 'Invalid or expired token' })
   }
-  next()
 })
 
 app.all('/mcp', async (req, res) => {
@@ -1434,19 +1449,86 @@ The full `context.mcp.extra` object contains:
 
 ### Complete Example
 
-Here's a complete example showing the data flow from middleware to tool:
+Install [`jose`](https://github.com/panva/jose) to verify JSON Web Tokens (JWTs) against your identity provider's JSON Web Key Set (JWKS):
+
+**npm**:
+
+```shell
+npm install jose
+```
+
+**pnpm**:
+
+```shell
+pnpm add jose
+```
+
+**Yarn**:
+
+```shell
+yarn add jose
+```
+
+**Bun**:
+
+```shell
+bun add jose
+```
+
+The following example validates the token's signature, issuer, audience, algorithm, expiration, and required claims before passing its user data to the tool:
 
 ```typescript
 import express from 'express'
+import { createRemoteJWKSet, jwtVerify } from 'jose'
 import { MCPServer } from '@mastra/mcp'
 import { createTool } from '@mastra/core/tools'
 import { z } from 'zod'
 
-const verifyToken = (token: string) => {
-  // TODO: Implement token verification
+type MCPAuthenticatedRequest = express.Request & {
+  auth?: {
+    token: string
+    clientId: string
+    scopes: string[]
+    expiresAt?: number
+    extra?: Record<string, unknown>
+  }
+}
+
+const issuer = process.env.JWT_ISSUER
+const audience = process.env.JWT_AUDIENCE
+const jwksUri = process.env.JWT_JWKS_URI
+
+if (!issuer || !audience || !jwksUri) {
+  throw new Error('JWT_ISSUER, JWT_AUDIENCE, and JWT_JWKS_URI are required')
+}
+
+const jwks = createRemoteJWKSet(new URL(jwksUri))
+
+const verifyToken = async (token: string) => {
+  const { payload } = await jwtVerify(token, jwks, {
+    issuer,
+    audience,
+    algorithms: ['RS256'],
+    requiredClaims: ['exp'],
+  })
+
+  const clientId =
+    typeof payload.client_id === 'string'
+      ? payload.client_id
+      : typeof payload.azp === 'string'
+        ? payload.azp
+        : undefined
+
+  if (!payload.sub || typeof payload.email !== 'string' || !clientId || !payload.exp) {
+    throw new Error('Token must contain sub, email, exp, and client_id or azp claims')
+  }
+
   return {
-    userId: '123',
-    email: 'test@test.com',
+    userId: payload.sub,
+    clientId,
+    email: payload.email,
+    expiresAt: payload.exp,
+    scopes: typeof payload.scope === 'string' ? payload.scope.split(' ') : [],
   }
 }
 
@@ -1481,18 +1563,35 @@ const server = new MCPServer({
 // 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)
+app.use('/mcp', async (req, res, next) => {
+  const authorization = req.headers.authorization
+
+  if (!authorization?.startsWith('Bearer ')) {
+    res.status(401).json({ error: 'Missing bearer token' })
+    return
+  }
 
-  // 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,
+  const token = authorization.slice('Bearer '.length)
+
+  try {
+    const user = await verifyToken(token)
+
+    // This entire object becomes context.mcp.extra.authInfo
+    const authenticatedRequest = req as MCPAuthenticatedRequest
+    authenticatedRequest.auth = {
+      token,
+      clientId: user.clientId,
+      scopes: user.scopes,
+      expiresAt: user.expiresAt,
+      extra: {
+        userId: user.userId,
+        email: user.email,
+      },
+    }
+    next()
+  } catch {
+    res.status(401).json({ error: 'Invalid or expired token' })
   }
-  next()
 })
 
 app.all('/mcp', async (req, res) => {