@mastra/mcp 1.8.1 → 1.9.0-alpha.1

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

@@ -22,7 +22,7 @@ const myAgent = new Agent({
   name: 'MyExampleAgent',
   description: 'A generalist to help with basic questions.',
   instructions: 'You are a helpful assistant.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 
 const weatherTool = createTool({
@@ -67,6 +67,8 @@ The constructor accepts an `MCPServerConfig` object with the following propertie
 
 **instructions** (`string`): Optional instructions describing how to use the server and its features.
 
+**mapAuthInfoToUser** (`({ authInfo, extra, requestContext }) => unknown | null | undefined | Promise<unknown | null | undefined>`): Maps MCP transport auth data from \`extra.authInfo\` into the \`user\` value used by Mastra FGA checks. Use this when an OAuth-protected MCP server is registered on a Mastra instance with an FGA provider.
+
 **repository** (`Repository`): Optional repository information for the server's source code.
 
 **releaseDate** (`string`): Optional release date of this server version (ISO 8601 string). Defaults to the time of instantiation if not provided.
@@ -1097,6 +1099,36 @@ Whatever you set on `req.auth` in your HTTP middleware becomes available as `con
 req.auth = { ... }  →  context?.mcp?.extra?.authInfo.extra = { ... }
 ```
 
+### Map auth data for FGA
+
+When an `MCPServer` is registered on a Mastra instance with a fine-grained authorization (FGA) provider, Mastra checks `requestContext.get('user')` before listing or calling tools. HTTP MCP transports pass authenticated data as `extra.authInfo`, so use `mapAuthInfoToUser` to set the user shape expected by your FGA provider.
+
+```typescript
+const server = new MCPServer({
+  id: 'my-server',
+  name: 'My Server',
+  version: '1.0.0',
+  tools: { getUserData },
+  mapAuthInfoToUser: ({ authInfo }) => {
+    const user = authInfo as {
+      extra?: {
+        userId?: string
+        organizationMembershipId?: string
+      }
+    }
+
+    if (!user.extra?.userId) {
+      return null
+    }
+
+    return {
+      id: user.extra.userId,
+      organizationMembershipId: user.extra.organizationMembershipId,
+    }
+  },
+})
+```
+
 ### 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()`.

package/dist/index.cjs

@@ -425,6 +425,7 @@ function isReconnectableMCPError(error) {
 
 // src/client/client.ts
 var DEFAULT_SERVER_CONNECT_TIMEOUT_MSEC = 3e3;
+var DEFAULT_INSTRUCTIONS_MAX_LENGTH = 512;
 var require2 = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
 var SSE_FALLBACK_STATUS_CODES = [400, 404, 405];
 var DATADOG_TRACER_TEST_SYMBOL = /* @__PURE__ */ Symbol.for("mastra.mcp.dd-trace-test-tracer");
@@ -507,6 +508,7 @@ var InternalMastraMCPClient = class extends base.MastraBase {
   exitHookUnsubscribe;
   sigTermHandler;
   sigHupHandler;
+  serverInstructions;
   _roots;
   requireToolApproval;
   /** Provides access to resource operations (list, read, subscribe, etc.) */
@@ -753,11 +755,19 @@ var InternalMastraMCPClient = class extends base.MastraBase {
         } else {
           throw new Error("Server configuration must include either a command or a url.");
         }
+        this.refreshServerInstructions();
         resolve(true);
         const originalOnClose = this.client.onclose;
         this.client.onclose = () => {
           this.log("debug", `MCP server connection closed`);
+          const staleTransport = this.transport;
+          this.transport = void 0;
           this.isConnected = null;
+          this.serverInstructions = void 0;
+          if (staleTransport) {
+            void staleTransport.close().catch(() => {
+            });
+          }
           if (typeof originalOnClose === "function") {
             originalOnClose();
           }
@@ -815,6 +825,18 @@ var InternalMastraMCPClient = class extends base.MastraBase {
     }
     return null;
   }
+  get instructions() {
+    return this.serverInstructions;
+  }
+  get forwardInstructions() {
+    return this.serverConfig.forwardInstructions ?? false;
+  }
+  get instructionsMaxLength() {
+    return this.serverConfig.instructionsMaxLength ?? DEFAULT_INSTRUCTIONS_MAX_LENGTH;
+  }
+  refreshServerInstructions() {
+    this.serverInstructions = this.client.getInstructions();
+  }
   async disconnect() {
     if (!this.transport) {
       this.log("debug", "Disconnect called but no transport was connected.");
@@ -832,6 +854,7 @@ var InternalMastraMCPClient = class extends base.MastraBase {
     } finally {
       this.transport = void 0;
       this.isConnected = null;
+      this.serverInstructions = void 0;
       if (this.exitHookUnsubscribe) {
         this.exitHookUnsubscribe();
         this.exitHookUnsubscribe = void 0;
@@ -870,6 +893,7 @@ var InternalMastraMCPClient = class extends base.MastraBase {
     }
     this.transport = void 0;
     this.isConnected = null;
+    this.serverInstructions = void 0;
     await this.connect();
     this.log("debug", "Successfully reconnected to MCP server");
   }
@@ -1008,7 +1032,10 @@ var InternalMastraMCPClient = class extends base.MastraBase {
           requireApproval,
           mcpMetadata: {
             serverName: this.name,
-            serverVersion: this.client.getServerVersion()?.version
+            serverVersion: this.client.getServerVersion()?.version,
+            serverInstructions: this.serverInstructions,
+            forwardInstructions: this.forwardInstructions,
+            instructionsMaxLength: this.instructionsMaxLength
           },
           execute: async (input, context) => {
             const operationContext = context?.requestContext ?? null;
@@ -1872,6 +1899,19 @@ To fix this you have three different options:
       await this.getConnectedClientForServer(serverName);
     }
   }
+  /**
+   * Returns instructions advertised by connected MCP servers during initialize.
+   *
+   * Servers that have not connected yet, or did not advertise instructions,
+   * return `undefined`.
+   */
+  getServerInstructions() {
+    const instructions = {};
+    for (const serverName of Object.keys(this.serverConfigs)) {
+      instructions[serverName] = this.mcpClientsById.get(serverName)?.instructions;
+    }
+    return instructions;
+  }
   /**
    * Retrieves all tools from all configured servers with namespaced names.
    *
@@ -2317,7 +2357,7 @@ function createSimpleTokenProvider(accessToken, options) {
   });
 }
 
-// ../../node_modules/.pnpm/hono@4.12.18/node_modules/hono/dist/utils/stream.js
+// ../../../../../setup-pnpm/node_modules/.bin/store/v11/links/@/hono/4.12.18/a4592d669eb2c33e4f24995614864047f2c1a155accc9d64dd2de0f4e8d608a9/node_modules/hono/dist/utils/stream.js
 var StreamingApi = class {
   writer;
   encoder;
@@ -2394,7 +2434,7 @@ var StreamingApi = class {
   }
 };
 
-// ../../node_modules/.pnpm/hono@4.12.18/node_modules/hono/dist/helper/streaming/utils.js
+// ../../../../../setup-pnpm/node_modules/.bin/store/v11/links/@/hono/4.12.18/a4592d669eb2c33e4f24995614864047f2c1a155accc9d64dd2de0f4e8d608a9/node_modules/hono/dist/helper/streaming/utils.js
 var isOldBunVersion = () => {
   const version = typeof Bun !== "undefined" ? Bun.version : void 0;
   if (version === void 0) {
@@ -2405,7 +2445,7 @@ var isOldBunVersion = () => {
   return result;
 };
 
-// ../../node_modules/.pnpm/hono@4.12.18/node_modules/hono/dist/utils/html.js
+// ../../../../../setup-pnpm/node_modules/.bin/store/v11/links/@/hono/4.12.18/a4592d669eb2c33e4f24995614864047f2c1a155accc9d64dd2de0f4e8d608a9/node_modules/hono/dist/utils/html.js
 var HtmlEscapedCallbackPhase = {
   Stringify: 1};
 var resolveCallback = async (str, phase, preserveCallbacks, context, buffer) => {
@@ -2436,7 +2476,7 @@ var resolveCallback = async (str, phase, preserveCallbacks, context, buffer) =>
   }
 };
 
-// ../../node_modules/.pnpm/hono@4.12.18/node_modules/hono/dist/helper/streaming/sse.js
+// ../../../../../setup-pnpm/node_modules/.bin/store/v11/links/@/hono/4.12.18/a4592d669eb2c33e4f24995614864047f2c1a155accc9d64dd2de0f4e8d608a9/node_modules/hono/dist/helper/streaming/sse.js
 var SSEStreamingApi = class extends StreamingApi {
   constructor(writable, readable) {
     super(writable, readable);
@@ -2743,6 +2783,7 @@ var MCPServer = class extends mcp.MCPServerBase {
   definedPrompts;
   promptOptions;
   jsonSchemaValidator;
+  mapAuthInfoToUser;
   subscriptions = /* @__PURE__ */ new Set();
   currentLoggingLevel;
   /**
@@ -2844,6 +2885,7 @@ var MCPServer = class extends mcp.MCPServerBase {
    * @param opts.prompts - Optional prompt configuration for exposing reusable templates
    * @param opts.id - Optional unique identifier (generated if not provided)
    * @param opts.description - Optional description of what the server does
+   * @param opts.mapAuthInfoToUser - Optional mapper from MCP `extra.authInfo` to the FGA user context
    *
    * @example
    * ```typescript
@@ -2880,6 +2922,7 @@ var MCPServer = class extends mcp.MCPServerBase {
     this.resourceOptions = this.mergeAppResources(opts.resources, opts.appResources);
     this.promptOptions = opts.prompts;
     this.jsonSchemaValidator = opts.jsonSchemaValidator;
+    this.mapAuthInfoToUser = opts.mapAuthInfoToUser;
     const capabilities = {
       tools: {},
       logging: { enabled: true }
@@ -3116,7 +3159,7 @@ var MCPServer = class extends mcp.MCPServerBase {
    */
   registerHandlersOnServer(serverInstance) {
     serverInstance.setRequestHandler(types_js.ListToolsRequestSchema, async (_request, extra) => {
-      const proxiedContext = this.createProxiedRequestContext(extra);
+      const proxiedContext = await this.createProxiedRequestContext(extra);
       const tools = await this.getAuthorizedConvertedToolEntries(proxiedContext);
       return {
         tools: tools.map(([, tool]) => {
@@ -3196,12 +3239,7 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
             return this.handleElicitationRequest(request2, serverInstance, options);
           }
         };
-        const proxiedContext = new requestContext.RequestContext();
-        if (extra) {
-          Object.entries(extra).forEach(([key, value]) => {
-            proxiedContext.set(key, value);
-          });
-        }
+        const proxiedContext = await this.createProxiedRequestContext(extra);
         const mcpOptions = {
           messages: [],
           toolCallId: "",
@@ -4480,22 +4518,50 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
       _meta: withMastraToolStrictMeta(tool.mcp?._meta, tool.strict)
     };
   }
-  createProxiedRequestContext(extra) {
+  async createProxiedRequestContext(extra) {
     const proxiedContext = new requestContext.RequestContext();
+    let extraRecord;
     if (extra && typeof extra === "object") {
-      Object.entries(extra).forEach(([key, value]) => {
+      extraRecord = extra;
+      Object.entries(extraRecord).forEach(([key, value]) => {
         proxiedContext.set(key, value);
       });
     }
+    await this.resolveMappedFGAUser(proxiedContext, extraRecord);
     return proxiedContext;
   }
+  async resolveMappedFGAUser(requestContext, extra) {
+    if (!requestContext) {
+      return void 0;
+    }
+    const existingUser = requestContext.get("user");
+    if (existingUser) {
+      return existingUser;
+    }
+    if (!this.mapAuthInfoToUser) {
+      return void 0;
+    }
+    const authInfo = extra && "authInfo" in extra ? extra.authInfo : requestContext.get("authInfo");
+    if (!authInfo) {
+      return void 0;
+    }
+    const user = await this.mapAuthInfoToUser({
+      authInfo,
+      extra: extra ?? { authInfo },
+      requestContext
+    });
+    if (user) {
+      requestContext.set("user", user);
+    }
+    return user;
+  }
   async getAuthorizedConvertedToolEntries(requestContext) {
     const entries = Object.entries(this.convertedTools);
     const fgaProvider = this.mastra?.getServer?.()?.fga;
     if (!fgaProvider) {
       return entries;
     }
-    const user = requestContext.get("user");
+    const user = await this.resolveMappedFGAUser(requestContext);
     if (!user) {
       return [];
     }
@@ -4519,17 +4585,26 @@ Provided arguments: ${JSON.stringify(request.params.arguments, null, 2)}`
     if (!fgaProvider) {
       return;
     }
-    const { checkFGA, FGADeniedError, MastraFGAPermissions } = await import('@mastra/core/auth/ee');
-    const resourceId = JSON.stringify([this.id, toolId]);
-    const user = requestContext?.get("user");
+    const { getMCPToolFGAResourceId, requireFGA, FGADeniedError, MastraFGAPermissions } = await import('@mastra/core/auth/ee');
+    const resourceId = getMCPToolFGAResourceId(this.id, toolId);
+    const user = await this.resolveMappedFGAUser(requestContext);
     if (!user) {
       throw new FGADeniedError({ id: "unknown" }, { type: "tool", id: resourceId }, MastraFGAPermissions.TOOLS_EXECUTE);
     }
-    await checkFGA({
+    await requireFGA({
       fgaProvider,
       user,
       resource: { type: "tool", id: resourceId },
-      permission: MastraFGAPermissions.TOOLS_EXECUTE
+      permission: MastraFGAPermissions.TOOLS_EXECUTE,
+      requestContext,
+      context: {
+        resourceId
+      },
+      metadata: {
+        mcpServerId: this.id,
+        mcpServerName: this.name,
+        toolId
+      }
     });
   }
   /**