@mastra/mcp-docs-server 1.2.8-alpha.2 → 1.2.8-alpha.23

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) => {

package/.docs/reference/tools/tavily.md

@@ -59,7 +59,7 @@ All factory functions accept `TavilyClientOptions` from `@tavily/core`:
 
 **apiKey** (`string`): Tavily API key. Falls back to the TAVILY\_API\_KEY environment variable.
 
-**clientSource** (`string`): Attribution string sent with each request. (Default: `'mastra'`)
+**clientName** (`string`): Attribution string sent with each request in the X-Client-Name header. (Default: `'mastra'`)
 
 **apiBaseURL** (`string`): Base URL for the Tavily API.
 

package/.docs/reference/tools/vector-query-tool.md

@@ -269,6 +269,28 @@ const chromaQueryTool = createVectorQueryTool({
 - **whereDocument**: Filter by document content
 - **Use Cases**: Advanced filtering, content-based search
 
+**Turbopuffer**:
+
+### Turbopuffer Configuration
+
+```typescript
+const turbopufferQueryTool = createVectorQueryTool({
+  vectorStoreName: 'turbopuffer',
+  indexName: 'docs',
+  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+  databaseConfig: {
+    turbopuffer: {
+      consistency: 'eventual', // Lower latency, recently written data may not be visible yet
+    },
+  },
+})
+```
+
+**Turbopuffer Features:**
+
+- **consistency**: Choose between `strong` (default, read-your-writes) and `eventual` (lower latency)
+- **Use Cases**: Latency-sensitive queries where slightly stale data is acceptable
+
 **Multiple Configs**:
 
 ### Multiple Database Configurations

package/.docs/reference/vectors/mongodb.md

@@ -89,6 +89,8 @@ Creates a new vector index (collection) in MongoDB.
 
 **metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
 
+**filterFields** (`string[]`): Metadata field names to declare as filter fields in the Atlas vectorSearch index (registered as metadata.\<field>). Queries that filter only on declared fields are pushed directly into $vectorSearch instead of pre-filtering candidate \_ids, avoiding the 16 MB BSON limit on large result sets. Filters that reference an undeclared field, or use an operator $vectorSearch does not support, fall back to the pre-filter automatically.
+
 ### `waitForIndexReady()`
 
 Waits for an index to become ready after creation. Useful when you need to ensure an index is ready before performing operations.

package/.docs/reference/vectors/turbopuffer.md

@@ -18,6 +18,8 @@ The TurbopufferVector class provides vector search using [Turbopuffer](https://t
 
 **compression** (`boolean`): Whether to compress requests and accept compressed responses. (Default: `true`)
 
+**consistency** (`'strong' | 'eventual'`): The default consistency level for queries. Can be overridden per query. "strong" guarantees queries see all data written before the query started, at the cost of higher latency. "eventual" offers lower latency, but recently written data may not be visible yet. (Default: `strong`)
+
 **schemaConfigForIndex** (`function`): A callback function that takes an index name and returns a config object for that index. This allows you to define explicit schemas per index.
 
 ## Methods
@@ -50,6 +52,8 @@ The TurbopufferVector class provides vector search using [Turbopuffer](https://t
 
 **includeVector** (`boolean`): Whether to include vectors in the results (Default: `false`)
 
+**consistency** (`'strong' | 'eventual'`): The consistency level for this query. Overrides the consistency level set in the constructor. Defaults to "strong".
+
 ### `listIndexes()`
 
 Returns an array of index names as strings.

package/.docs/reference/voice/mistral.md

@@ -0,0 +1,127 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Mistral
+
+The MistralVoice class provides text-to-speech and speech-to-text capabilities using Mistral's Voxtral audio models. It supports buffered and streaming TTS, batch transcription with diarization, and voice cloning via reference audio.
+
+## Usage example
+
+```typescript
+import { MistralVoice } from '@mastra/voice-mistral'
+
+const voice = new MistralVoice()
+
+// Text-to-speech
+const audioStream = await voice.speak('Hello, how can I help you?', {
+  responseFormat: 'mp3',
+})
+
+// Speech-to-text
+const text = await voice.listen(audioStream, {
+  language: 'en',
+})
+
+// List available voices
+const speakers = await voice.getSpeakers()
+```
+
+```typescript
+import { MistralVoice } from '@mastra/voice-mistral'
+
+// Initialize with specific configuration
+const voice = new MistralVoice({
+  speechModel: {
+    name: 'voxtral-mini-tts-2603',
+    apiKey: 'your-mistral-api-key',
+  },
+  listeningModel: {
+    name: 'voxtral-mini-latest',
+    apiKey: 'your-mistral-api-key',
+  },
+  speaker: 'en_paul_neutral',
+})
+```
+
+## Constructor parameters
+
+**speechModel** (`MistralModelConfig`): Configuration for text-to-speech synthesis. (Default: `{ name: 'voxtral-mini-tts-2603' }`)
+
+**speechModel.name** (`string`): Model ID for speech synthesis.
+
+**speechModel.apiKey** (`string`): Mistral API key. Falls back to MISTRAL\_API\_KEY environment variable.
+
+**listeningModel** (`MistralModelConfig`): Configuration for speech-to-text recognition. (Default: `{ name: 'voxtral-mini-latest' }`)
+
+**listeningModel.name** (`string`): Model ID for transcription. Use 'voxtral-mini-2507' for a pinned version.
+
+**listeningModel.apiKey** (`string`): Mistral API key. Falls back to MISTRAL\_API\_KEY environment variable.
+
+**speaker** (`string`): Default voice ID for speech synthesis. Retrieve available IDs from getSpeakers(). (Default: `'en_paul_neutral'`)
+
+## Methods
+
+### `speak(input, options?)`
+
+Converts text to speech using Mistral's Voxtral TTS model. Supports both buffered and streaming output.
+
+**input** (`string | NodeJS.ReadableStream`): Text or text stream to convert to speech.
+
+**options** (`MistralSpeakOptions`): Configuration options.
+
+**options.speaker** (`string`): Voice ID to use. Overrides the constructor default.
+
+**options.responseFormat** (`'pcm' | 'wav' | 'mp3' | 'flac' | 'opus'`): Audio output format. Use 'pcm' for lowest latency streaming.
+
+**options.refAudio** (`string`): Base64-encoded reference audio for one-off voice cloning (minimum 2-3 seconds).
+
+**options.model** (`string`): Override the speech model for this call.
+
+**options.stream** (`boolean`): Enable streaming TTS. Audio chunks are written to the stream as they arrive.
+
+Returns: `Promise<NodeJS.ReadableStream>`
+
+### `listen(audioStream, options?)`
+
+Transcribes audio using Mistral's Voxtral transcription model. Supports diarization, context biasing, and timestamp granularity.
+
+**audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe.
+
+**options** (`MistralListenOptions`): Configuration options.
+
+**options.language** (`string`): Language code (e.g., 'en'). Improves accuracy when specified.
+
+**options.diarize** (`boolean`): Enable speaker diarization.
+
+**options.contextBias** (`string[]`): Words or phrases for vocabulary guidance.
+
+**options.timestampGranularities** (`('segment' | 'word')[]`): Timestamp detail level for transcription segments.
+
+**options.filetype** (`string`): Audio file extension hint for the input stream.
+
+Returns: `Promise<string>`
+
+### `getSpeakers()`
+
+Fetches available preset voices from the Mistral Voices API. Each entry contains:
+
+**voiceId** (`string`): Unique identifier for the voice.
+
+**name** (`string`): Display name of the voice.
+
+**languages** (`string[]`): Languages supported by the voice.
+
+**gender** (`string | null`): Gender of the voice.
+
+### `getListener()`
+
+Returns `{ enabled: true }`.
+
+## Notes
+
+- API keys can be provided via constructor options or the `MISTRAL_API_KEY` environment variable
+- TTS supports 9 languages: English, French, Spanish, Portuguese, Italian, Dutch, German, Hindi, Arabic
+- STT supports 13 languages: English, Chinese, Hindi, Spanish, Arabic, French, Portuguese, Russian, German, Japanese, Korean, Italian, Dutch
+- TTS input text should be kept under 300 words per request for best results
+- STT supports up to 3 hours of audio per request
+- Voice cloning via `refAudio` requires a minimum of 2-3 seconds of reference audio
+- `getSpeakers()` returns preset voices with UUID identifiers. The default `en_paul_neutral` is a named alias accepted by the TTS endpoint but not included in the list

package/.docs/reference/workspace/daytona-sandbox.md

@@ -440,12 +440,8 @@ Then use the snapshot name in your sandbox config:
 ```typescript
 const workspace = new Workspace({
   mounts: {
-    '/s3-data': new S3Filesystem({
-      /* ... */
-    }),
-    '/gcs-data': new GCSFilesystem({
-      /* ... */
-    }),
+    '/s3-data': new S3Filesystem({/* ... */}),
+    '/gcs-data': new GCSFilesystem({/* ... */}),
   },
   sandbox: new DaytonaSandbox({ snapshot: 'cloud-fs-mounting' }),
 })