@mastra/mcp 1.9.0-alpha.0 → 1.9.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @mastra/mcp
 
+## 1.9.0-alpha.1
+
+### Patch Changes
+
+- Fixed FGA-enabled MCP servers so OAuth authInfo can be mapped to a Mastra user before tools/list and tools/call authorization. ([#17475](https://github.com/mastra-ai/mastra/pull/17475))
+
+- Updated dependencies [[`0c1ed1d`](https://github.com/mastra-ai/mastra/commit/0c1ed1d00c7d87b5ac99ca95896211a2fa9189fa), [`849efb9`](https://github.com/mastra-ai/mastra/commit/849efb9fca6dc976589c1f90a303fea618769109)]:
+  - @mastra/core@1.38.0-alpha.8
+
 ## 1.9.0-alpha.0
 
 ### Minor Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-mcp
 description: Documentation for @mastra/mcp. Use when working with @mastra/mcp APIs, configuration, or implementation.
 metadata:
   package: "@mastra/mcp"
-  version: "1.9.0-alpha.0"
+  version: "1.9.0-alpha.1"
 ---
 
 ## When to use
@@ -18,6 +18,7 @@ Read the individual reference documents for detailed explanations and code examp
 
 - [MCP Apps](references/docs-mcp-mcp-apps.md) - Serve interactive HTML UIs from MCP tools using the MCP Apps extension.
 - [MCP overview](references/docs-mcp-overview.md) - Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient, connect to registries, and share your own tools using MCPServer.
+- [Fine-Grained Authorization (FGA)](references/docs-server-auth-fga.md) - Add resource-level authorization to your Mastra application with FGA providers.
 
 ### Reference
 

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.9.0-alpha.0",
+  "version": "1.9.0-alpha.1",
   "package": "@mastra/mcp",
   "exports": {
     "UnauthorizedError": {

package/dist/docs/references/docs-mcp-mcp-apps.md

@@ -93,7 +93,7 @@ export const myAgent = new Agent({
   id: 'my-agent',
   name: 'My Agent',
   instructions: 'You have access to interactive UI tools.',
-  model: '__OPENAI_MODEL_MINI__',
+  model: 'openai/gpt-5-mini',
   tools: { calculatorTool },
 })
 ```
@@ -125,7 +125,7 @@ const mcpClient = new MCPClient({
 const myAgent = new Agent({
   id: 'my-agent',
   name: 'My Agent',
-  model: '__OPENAI_MODEL_MINI__',
+  model: 'openai/gpt-5-mini',
   tools: await mcpClient.listTools(),
 })
 
@@ -270,7 +270,7 @@ const mcpClient = new MCPClient({
 const myAgent = new Agent({
   id: 'my-agent',
   name: 'My Agent',
-  model: '__OPENAI_MODEL_MINI__',
+  model: 'openai/gpt-5-mini',
   tools: await mcpClient.listTools(),
 })
 

package/dist/docs/references/docs-mcp-overview.md

@@ -82,7 +82,7 @@ export const testAgent = new Agent({
       - US National Weather Service
 
       Answer questions using the information you find using the MCP Servers.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: await testMcpClient.listTools(),
 })
 ```

package/dist/docs/references/docs-server-auth-fga.md

@@ -0,0 +1,258 @@
+# Fine-Grained Authorization (FGA)
+
+> **Note:** Fine-Grained Authorization is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
+
+Fine-Grained Authorization (FGA) adds resource-level permission checks to your Mastra application. While RBAC answers "can this role do this action?", FGA answers **"can this user do this action on this specific resource?"**
+
+## When to use FGA
+
+FGA is designed for multi-tenant B2B products where permissions are contextual:
+
+- A user might be an **admin** of Team A but only a **member** of Team B
+- Thread access should be limited to the user's own organization
+- Workflow execution should be scoped to a specific team or project
+- Tool access depends on the user's relationship to a resource
+
+## Configuration
+
+Configure FGA in your Mastra server config alongside authentication and RBAC:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra';
+import { MastraFGAPermissions } from '@mastra/core/auth/ee';
+import { MastraAuthWorkos, MastraFGAWorkos } from '@mastra/auth-workos';
+
+const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthWorkos({
+      /* ... */
+      fetchMemberships: true,
+      mapUserToResourceId: user => user.teamId,
+    }),
+    fga: new MastraFGAWorkos({
+      resourceMapping: {
+        agent: { fgaResourceType: 'team', deriveId: (ctx) => ctx.user.teamId },
+        workflow: { fgaResourceType: 'team', deriveId: (ctx) => ctx.user.teamId },
+        thread: { fgaResourceType: 'workspace-thread', deriveId: ({ resourceId }) => resourceId },
+      },
+      permissionMapping: {
+        [MastraFGAPermissions.AGENTS_EXECUTE]: 'manage-workflows',
+        [MastraFGAPermissions.WORKFLOWS_EXECUTE]: 'manage-workflows',
+        [MastraFGAPermissions.MEMORY_READ]: 'read',
+        [MastraFGAPermissions.MEMORY_WRITE]: 'update',
+      },
+    }),
+    storedResources: {
+      scope: true,
+    },
+  },
+});
+```
+
+When using `MastraFGAWorkos`, set `fetchMemberships: true` on `MastraAuthWorkos`. WorkOS FGA checks need the user's organization memberships to resolve the correct membership ID for authorization.
+
+Use `thread` as the resource-mapping key for memory authorization. `MastraFGAWorkos` still accepts the legacy alias `memory`, but new configs should prefer `thread`.
+
+When `server.fga` is configured, Mastra enforces FGA on protected actions. If a protected action has no authenticated user, Mastra denies it. If `server.fga` is not configured, these FGA checks are skipped and Mastra keeps the previous behavior.
+
+### Resource mapping
+
+The `resourceMapping` tells Mastra how to resolve FGA resource types and IDs from request context. Keys are Mastra resource types, values define the FGA resource type and how to derive the ID:
+
+```typescript
+resourceMapping: {
+  // When checking "can user execute agent X?", resolve the FGA resource
+  // as the user's team (type: 'team', id: user.teamId)
+  agent: {
+    fgaResourceType: 'team',
+    deriveId: (ctx) => ctx.user.teamId,
+  },
+}
+```
+
+`deriveId()` receives:
+
+- `user` — the authenticated user
+- `resourceId` — the owning Mastra resource ID when available (for example, a thread's `resourceId`)
+- `requestContext` — the current request context for advanced tenant resolution
+- `metadata` — provider-specific metadata for the attempted action
+
+Return `undefined` from `deriveId()` to fall back to the original Mastra resource ID.
+
+For thread and memory checks, Mastra still passes the raw `threadId` as the resource being checked, but it also forwards the thread's owning `resourceId` into `deriveId()`. This lets you map thread permissions to composite tenant IDs such as `userId-teamId-orgId`.
+
+### Permission mapping
+
+The `permissionMapping` translates Mastra's internal permission strings to your FGA provider's permission slugs:
+
+```typescript
+import { MastraFGAPermissions } from '@mastra/core/auth/ee';
+
+permissionMapping: {
+  [MastraFGAPermissions.AGENTS_EXECUTE]: 'manage-workflows', // Mastra permission -> WorkOS permission slug
+  [MastraFGAPermissions.MEMORY_READ]: 'read',
+}
+```
+
+If no mapping exists for a permission, the original string is passed through.
+
+Use `validatePermissions()` to validate the full set of permissions Mastra may emit at startup. Use this when a provider requires every Mastra permission to have an explicit provider permission slug.
+
+### Stored resource scoping
+
+FGA authorizes access to a resource. It does not automatically filter stored records that live in shared storage. Enable stored resource scoping when the built-in stored resource APIs are used in a multi-tenant app.
+
+```typescript
+const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthWorkos({
+      /* ... */
+      mapUserToResourceId: user => user.teamId,
+    }),
+    storedResources: {
+      scope: true,
+    },
+  },
+});
+```
+
+With `scope: true`, Mastra reads `MASTRA_RESOURCE_ID_KEY` from the request context. `mapUserToResourceId()` sets this value after authentication. Stored resource handlers persist the scope in record metadata and filter list, read, update, publish, and delete operations by that scope.
+
+Use an object when the scope needs custom request logic:
+
+```typescript
+storedResources: {
+  scope: {
+    metadataKey: 'teamId',
+    resolve: ({ user }) => user.teamId,
+    requireScope: true,
+  },
+},
+```
+
+If `requireScope` is `true` or omitted, scoped stored resource routes fail when no scope can be resolved.
+
+### Route policy coverage
+
+Mastra includes route-level FGA metadata for built-in resource routes, including agents, workflows, tools, MCP tools, memory threads, responses, conversations, and stored resources. Stored resource route coverage includes `/stored/agents`, `/stored/mcp-clients`, `/stored/prompt-blocks`, `/stored/scorers`, `/stored/skills`, and `/stored/workspaces`. A route is checked when it has route-level `fga` metadata, when Mastra can derive built-in metadata for that route, or when the provider supplies metadata with `resolveRouteFGA()`.
+
+To deny protected routes that do not resolve FGA metadata, configure route policy coverage on the FGA provider:
+
+```typescript
+const fga = new MastraFGAWorkos({
+  resourceMapping: {
+    project: { fgaResourceType: 'project' },
+  },
+  permissionMapping: {
+    'projects:read': 'read',
+  },
+  requireForProtectedRoutes: true,
+  auditProtectedRoutes: 'warn',
+  validatePermissions: async permissions => {
+    // Throw if a Mastra permission is missing from permissionMapping.
+  },
+});
+```
+
+Set `auditProtectedRoutes: 'error'` to fail startup when protected routes are missing built-in FGA metadata. If `requireForProtectedRoutes` is enabled, Mastra logs this audit as a warning by default.
+
+For custom routes, prefer route-level `fga` metadata. This keeps authorization policy next to the route:
+
+```typescript
+import { createRoute } from '@mastra/server/server-adapter';
+
+export const getProjectRoute = createRoute({
+  method: 'GET',
+  path: '/projects/:projectId',
+  responseType: 'json',
+  requiresAuth: true,
+  fga: {
+    resourceType: 'project',
+    resourceIdParam: 'projectId',
+    permission: 'projects:read',
+  },
+  handler: async () => {
+    return { project: null };
+  },
+});
+```
+
+Use `resolveRouteFGA()` only when route metadata must be derived centrally from route, params, or request context. A route map scales better than string-prefix checks:
+
+```typescript
+import type { FGARouteConfig, FGARouteResolver } from '@mastra/core/auth/ee';
+
+const routeFGA = {
+  'GET /billing/:accountId': {
+    resourceType: 'account',
+    resourceIdParam: 'accountId',
+    permission: 'billing:read',
+  },
+} satisfies Record<string, FGARouteConfig>;
+
+const resolveRouteFGA: FGARouteResolver = ({ route }) => routeFGA[`${route.method} ${route.path}`];
+
+const fga = new MastraFGAWorkos({
+  /* ... */
+  resolveRouteFGA,
+});
+```
+
+## Enforcement points
+
+When an FGA provider is configured, Mastra automatically checks authorization at these lifecycle points:
+
+| Lifecycle point                                                  | Permission checked                              | Resource type        | Resource ID                                                         |
+| ---------------------------------------------------------------- | ----------------------------------------------- | -------------------- | ------------------------------------------------------------------- |
+| Agent execution (`generate`, `stream`)                           | `agents:execute`                                | `agent`              | `agentId`                                                           |
+| Built-in workflow HTTP execution routes and `Workflow.execute()` | `workflows:execute`                             | `workflow`           | `workflowId`                                                        |
+| Standalone tool execution                                        | `tools:execute`                                 | `tool`               | `toolName`                                                          |
+| Agent tool execution                                             | `tools:execute`                                 | `tool`               | `${agentId}:${toolName}`                                            |
+| MCP tool execution                                               | `tools:execute`                                 | `tool`               | `JSON.stringify([serverName, toolName])`                            |
+| Thread and memory access                                         | `memory:read`, `memory:write`, `memory:delete`  | `thread`             | `threadId`                                                          |
+| Stored resource routes                                           | Stored resource permission for the route action | Stored resource type | Route record ID, or the stored-resource scope for collection routes |
+| HTTP resource routes                                             | Configured per route                            | Configured per route | Configured per route                                                |
+
+For OAuth-protected MCP servers, HTTP MCP transports pass authenticated data as `extra.authInfo`. If an `MCPServer` is registered on an FGA-enabled Mastra instance, configure `mapAuthInfoToUser` so Mastra can set `requestContext.get('user')` before checking `tools/list` and `tools/call`. See [MCPServer authentication context](https://mastra.ai/reference/tools/mcp-server).
+
+Direct SDK calls to `createRun().start()`, `resume()`, or `restart()` are not independently checked by core FGA in this release. Make those calls from a protected route or guard them in application code. Pass a `requestContext` with an authenticated user when invoking protected entry points directly.
+
+Core agent, internal workflow, tool, and memory checks also pass `requestContext` and action metadata to the FGA provider. Route checks pass `requestContext`. Thread checks pass the owning `resourceId` when available.
+
+## Custom FGA provider
+
+Implement `IFGAProvider` to use any FGA backend:
+
+```typescript
+import { FGADeniedError } from '@mastra/core/auth/ee'
+import type { FGACheckParams, IFGAProvider, MastraFGAPermissionInput } from '@mastra/core/auth/ee'
+
+class MyFGAProvider implements IFGAProvider {
+  async check(user: any, params: FGACheckParams): Promise<boolean> {
+    // Your authorization logic
+    return true
+  }
+
+  async require(user: any, params: FGACheckParams): Promise<void> {
+    const allowed = await this.check(user, params)
+    if (!allowed) {
+      throw new FGADeniedError(user, params.resource, params.permission)
+    }
+  }
+
+  async filterAccessible<T extends { id: string }>(
+    user: any,
+    resources: T[],
+    resourceType: string,
+    permission: MastraFGAPermissionInput,
+  ): Promise<T[]> {
+    // Filter resources the user can access
+    return resources
+  }
+}
+```
+
+## Related
+
+- [Authentication overview](https://mastra.ai/docs/server/auth)
+- [WorkOS authentication](https://mastra.ai/docs/server/auth/workos)

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

@@ -890,7 +890,7 @@ const agent = new Agent({
   id: 'multi-tool-agent',
   name: 'Multi-tool Agent',
   instructions: 'You have access to multiple tool servers.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: await mcp.listTools(),
 })
 
@@ -941,7 +941,7 @@ const agent = new Agent({
   id: 'multi-tool-agent',
   name: 'Multi-tool Agent',
   instructions: 'You help users check stocks and weather.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 
 // Later, configure MCP with user-specific settings

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

@@ -2783,6 +2783,7 @@ var MCPServer = class extends mcp.MCPServerBase {
   definedPrompts;
   promptOptions;
   jsonSchemaValidator;
+  mapAuthInfoToUser;
   subscriptions = /* @__PURE__ */ new Set();
   currentLoggingLevel;
   /**
@@ -2884,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
@@ -2920,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 }
@@ -3156,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]) => {
@@ -3236,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: "",
@@ -4520,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 [];
     }
@@ -4559,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
+      }
     });
   }
   /**