@mastra/mcp-docs-server 1.0.0-beta.9 → 1.0.0

package/.docs/raw/reference/tools/mcp-server.mdx

@@ -1,6 +1,9 @@
 ---
 title: "Reference: MCPServer | Tools & MCP"
 description: API Reference for MCPServer - A class for exposing Mastra tools and capabilities as a Model Context Protocol server.
+packages:
+  - "@mastra/core"
+  - "@mastra/mcp"
 ---
 
 # MCPServer
@@ -41,6 +44,8 @@ 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.",
   tools: { weatherTool },
   agents: { myAgent }, // this agent will become tool "ask_myAgent"
   workflows: {
@@ -102,6 +107,13 @@ The constructor accepts an `MCPServerConfig` object with the following propertie
       isOptional: true,
       description: "Optional description of what the MCP server does.",
     },
+    {
+      name: "instructions",
+      type: "string",
+      isOptional: true,
+      description:
+        "Optional instructions describing how to use the server and its features.",
+    },
     {
       name: "repository",
       type: "Repository", // { url: string; source: string; id: string; }
@@ -1179,44 +1191,286 @@ 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
+
+<PropertiesTable
+  content={[
+    {
+      name: "oauth.resource",
+      type: "string",
+      description: "The canonical URL of your MCP server. This is returned in Protected Resource Metadata.",
+    },
+    {
+      name: "oauth.authorizationServers",
+      type: "string[]",
+      description: "URLs of authorization servers that can issue tokens for this resource.",
+    },
+    {
+      name: "oauth.scopesSupported",
+      type: "string[]",
+      isOptional: true,
+      defaultValue: "['mcp:read', 'mcp:write']",
+      description: "Scopes supported by this MCP server.",
+    },
+    {
+      name: "oauth.resourceName",
+      type: "string",
+      isOptional: true,
+      description: "Human-readable name for this resource server.",
+    },
+    {
+      name: "oauth.validateToken",
+      type: "(token: string, resource: string) => Promise<TokenValidationResult>",
+      isOptional: true,
+      description: "Function to validate access tokens. If not provided, tokens are accepted without validation (NOT recommended for production).",
+    },
+    {
+      name: "mcpPath",
+      type: "string",
+      isOptional: true,
+      defaultValue: "'/mcp'",
+      description: "Path where the MCP endpoint is served. Only requests to this path require authentication.",
+    },
+  ]}
+/>
+
 ## 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/.docs/raw/reference/tools/vector-query-tool.mdx

@@ -1,6 +1,10 @@
 ---
 title: "Reference: createVectorQueryTool() | Tools & MCP"
 description: Documentation for the Vector Query Tool in Mastra, which facilitates semantic search over vector stores with filtering and reranking capabilities.
+packages:
+  - "@mastra/core"
+  - "@mastra/pg"
+  - "@mastra/rag"
 ---
 
 import Tabs from "@theme/Tabs";
@@ -117,6 +121,13 @@ time.
         "Provider-specific options for the embedding model (e.g., outputDimensionality). **Important**: Only works with AI SDK EmbeddingModelV2 models. For V1 models, configure options when creating the model itself.",
       isOptional: true,
     },
+    {
+      name: "vectorStore",
+      type: "MastraVector | VectorStoreResolver",
+      description:
+        "Direct vector store instance or a resolver function for dynamic selection. Use a function for multi-tenant applications where the vector store is selected based on request context. When provided, `vectorStoreName` becomes optional.",
+      isOptional: true,
+    },
   ]}
 />
 
@@ -326,7 +337,7 @@ This agent-driven approach:
 
 For detailed filter syntax and store-specific capabilities, see the [Metadata Filters](../rag/metadata-filters) documentation.
 
-For an example of how agent-driven filtering works, see the [Agent-Driven Metadata Filtering](/examples/v1/rag/usage/filter-rag) example.
+For an example of how agent-driven filtering works, see the [Agent-Driven Metadata Filtering](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/filter-rag) example.
 
 ## Example with Reranking
 
@@ -567,14 +578,14 @@ const response = await agent.generate(
 
 For more information on request context, please see:
 
-- [Agent Request Context](/docs/v1/server-db/request-context)
-- [Request Context](/docs/v1/server-db/request-context#accessing-values-with-tools)
+- [Agent Request Context](/docs/v1/server/request-context)
+- [Request Context](/docs/v1/server/request-context#accessing-values-with-tools)
 
 ## Usage Without a Mastra Server
 
 The tool can be used by itself to retrieve documents matching a query:
 
-```typescript copy showLineNumbers title="src/index.ts"
+```typescript title="src/index.ts"
 import { RequestContext } from "@mastra/core/request-context";
 import { createVectorQueryTool } from "@mastra/rag";
 import { PgVector } from "@mastra/pg";
@@ -600,6 +611,59 @@ const queryResult = await vectorQueryTool.execute(
 console.log(queryResult.sources);
 ```
 
+## Dynamic Vector Store for Multi-Tenant Applications
+
+For multi-tenant applications where each tenant has isolated data (e.g., separate PostgreSQL schemas), you can pass a resolver function instead of a static vector store instance. The function receives the request context and can return the appropriate vector store for the current tenant:
+
+```typescript title="src/index.ts"
+import { createVectorQueryTool, VectorStoreResolver } from "@mastra/rag";
+import { PgVector } from "@mastra/pg";
+
+// Cache for tenant-specific vector stores
+const vectorStoreCache = new Map<string, PgVector>();
+
+// Resolver function that returns the correct vector store based on tenant
+const vectorStoreResolver: VectorStoreResolver = async ({ requestContext }) => {
+  const tenantId = requestContext?.get("tenantId");
+  
+  if (!tenantId) {
+    throw new Error("tenantId is required in request context");
+  }
+
+  // Return cached instance or create new one
+  if (!vectorStoreCache.has(tenantId)) {
+    vectorStoreCache.set(tenantId, new PgVector({
+      id: `pg-vector-${tenantId}`,
+      connectionString: process.env.POSTGRES_CONNECTION_STRING!,
+      schemaName: `tenant_${tenantId}`, // Each tenant has their own schema
+    }));
+  }
+
+  return vectorStoreCache.get(tenantId)!;
+};
+
+const vectorQueryTool = createVectorQueryTool({
+  indexName: "embeddings",
+  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
+  vectorStore: vectorStoreResolver, // Dynamic resolution!
+});
+
+// Usage with tenant context
+const requestContext = new RequestContext();
+requestContext.set("tenantId", "acme-corp");
+
+const result = await vectorQueryTool.execute(
+  { queryText: "company policies", topK: 5 },
+  { requestContext }
+);
+```
+
+This pattern is similar to how `Agent.memory` supports dynamic configuration and enables:
+
+- **Schema isolation**: Each tenant's data in separate PostgreSQL schemas
+- **Database isolation**: Route to different database instances per tenant
+- **Dynamic configuration**: Adjust vector store settings based on request context
+
 ## Tool Details
 
 The tool is created with:

package/.docs/raw/reference/vectors/astra.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Astra Vector Store | Vectors"
 description: Documentation for the AstraVector class in Mastra, which provides vector search using DataStax Astra DB.
+packages:
+  - "@mastra/astra"
 ---
 
 # Astra Vector Store
@@ -142,7 +144,7 @@ Returns an array of index names as strings.
 
 Returns:
 
-```typescript copy
+```typescript
 interface IndexStats {
   dimension: number;
   count: number;
@@ -219,7 +221,7 @@ interface IndexStats {
 
 Query results are returned in this format:
 
-```typescript copy
+```typescript
 interface QueryResult {
   id: string;
   score: number;
@@ -232,7 +234,7 @@ interface QueryResult {
 
 The store throws typed errors that can be caught:
 
-```typescript copy
+```typescript
 try {
   await store.query({
     indexName: "index_name",

package/.docs/raw/reference/vectors/chroma.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Chroma Vector Store | Vectors"
 description: Documentation for the ChromaVector class in Mastra, which provides vector search using ChromaDB.
+packages:
+  - "@mastra/chroma"
 ---
 
 # Chroma Vector Store
@@ -313,7 +315,7 @@ Returns an array of index names as strings.
 
 Returns:
 
-```typescript copy
+```typescript
 interface IndexStats {
   dimension: number;
   count: number;
@@ -475,7 +477,7 @@ await vectorStore.deleteVectors({
 
 Query results are returned in this format:
 
-```typescript copy
+```typescript
 interface QueryResult {
   id: string;
   score: number;
@@ -489,7 +491,7 @@ interface QueryResult {
 
 The store throws typed errors that can be caught:
 
-```typescript copy
+```typescript
 try {
   await store.query({
     indexName: "index_name",

package/.docs/raw/reference/vectors/convex.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Convex Vector Store | Vectors"
 description: Documentation for the ConvexVector class in Mastra, which provides vector search using Convex.
+packages:
+  - "@mastra/convex"
 ---
 
 # Convex Vector Store
@@ -9,7 +11,7 @@ The ConvexVector class provides vector storage and similarity search using [Conv
 
 ## Installation
 
-```bash copy
+```bash
 npm install @mastra/convex@beta
 ```
 
@@ -94,7 +96,7 @@ const vectorStore = new ConvexVector({
   ]}
 />
 
-```typescript copy
+```typescript
 await vectorStore.createIndex({
   indexName: "my_vectors",
   dimension: 1536,
@@ -130,7 +132,7 @@ await vectorStore.createIndex({
   ]}
 />
 
-```typescript copy
+```typescript
 await vectorStore.upsert({
   indexName: "my_vectors",
   vectors: [[0.1, 0.2, 0.3, ...]],
@@ -176,7 +178,7 @@ await vectorStore.upsert({
   ]}
 />
 
-```typescript copy
+```typescript
 const results = await vectorStore.query({
   indexName: "my_vectors",
   queryVector: [0.1, 0.2, 0.3, ...],
@@ -189,7 +191,7 @@ const results = await vectorStore.query({
 
 Returns an array of index names as strings.
 
-```typescript copy
+```typescript
 const indexes = await vectorStore.listIndexes();
 // ["my_vectors", "embeddings", ...]
 ```
@@ -208,7 +210,7 @@ const indexes = await vectorStore.listIndexes();
 
 Returns:
 
-```typescript copy
+```typescript
 interface IndexStats {
   dimension: number;
   count: number;
@@ -230,7 +232,7 @@ interface IndexStats {
 
 Deletes the index and all its vectors.
 
-```typescript copy
+```typescript
 await vectorStore.deleteIndex({ indexName: "my_vectors" });
 ```
 
@@ -265,7 +267,7 @@ Update a single vector by ID or by metadata filter. Either `id` or `filter` must
   ]}
 />
 
-```typescript copy
+```typescript
 // Update by ID
 await vectorStore.updateVector({
   indexName: "my_vectors",
@@ -303,7 +305,7 @@ await vectorStore.updateVector({
   ]}
 />
 
-```typescript copy
+```typescript
 await vectorStore.deleteVector({ indexName: "my_vectors", id: "vector123" });
 ```
 
@@ -333,7 +335,7 @@ Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` m
   ]}
 />
 
-```typescript copy
+```typescript
 // Delete by IDs
 await vectorStore.deleteVectors({
   indexName: "my_vectors",
@@ -351,7 +353,7 @@ await vectorStore.deleteVectors({
 
 Query results are returned in this format:
 
-```typescript copy
+```typescript
 interface QueryResult {
   id: string;
   score: number;
@@ -364,7 +366,7 @@ interface QueryResult {
 
 ConvexVector supports metadata filtering with various operators:
 
-```typescript copy
+```typescript
 // Simple equality
 const results = await vectorStore.query({
   indexName: "my_vectors",

package/.docs/raw/reference/vectors/couchbase.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: Couchbase Vector Store | Vectors"
 description: Documentation for the CouchbaseVector class in Mastra, which provides vector search using Couchbase Vector Search.
+packages:
+  - "@mastra/couchbase"
 ---
 
 # Couchbase Vector Store
@@ -14,13 +16,13 @@ The `CouchbaseVector` class provides vector search using [Couchbase Vector Searc
 
 ## Installation
 
-```bash copy
+```bash
 npm install @mastra/couchbase@beta
 ```
 
 ## Usage Example
 
-```typescript copy
+```typescript
 import { CouchbaseVector } from "@mastra/couchbase";
 
 const store = new CouchbaseVector({
@@ -209,7 +211,7 @@ Returns information about the index.
 
 Returns:
 
-```typescript copy
+```typescript
 interface IndexStats {
   dimension: number;
   count: number;
@@ -307,7 +309,7 @@ Closes the Couchbase client connection. Should be called when done using the sto
 
 Query results are returned in this format:
 
-```typescript copy
+```typescript
 interface QueryResult {
   id: string;
   score: number;
@@ -320,7 +322,7 @@ interface QueryResult {
 
 The store throws typed errors that can be caught:
 
-```typescript copy
+```typescript
 try {
   await store.query({
     indexName: "my_index",