feat(mcp): add server FGA authorization overrides#17529
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (6)
✅ Files skipped from review due to trivial changes (2)
🚧 Files skipped from review as they are similar to previous changes (3)
WalkthroughThis PR extends ChangesMCP Server FGA Mapping Overrides
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
ESLint install failed. For unrecoverable errors, disable the tool in CodeRabbit configuration. Comment |
🦋 Changeset detectedLatest commit: a82ad9c The changes in this PR will be included in the next version bump. This PR includes changesets to release 24 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
github-actions
Bot
added
the
Documentation
Contributor
PR triageLinked issue check skipped for core contributor @graysonhicks. PR complexity score
Applied label: Changed test gateChanged tests failed against the base branch as expected. Label: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
.changeset/lazy-hornets-hide.md (1)
10-27: ⚡ Quick winAlign permissionMapping example with reference docs pattern.
The code example uses string literal
'tools:execute'directly, but the reference docs example (lines 1377, 1409 in mcp-server.mdx) imports and uses theMastraFGAPermissions.TOOLS_EXECUTEconstant with bracket notation. For consistency and to demonstrate the type-safe pattern, update the changeset example to match the reference docs.Suggested alignment
+import { MastraFGAPermissions } from '`@mastra/core/auth/ee`' + const server = new MCPServer({ name: 'My Server', version: '1.0.0', tools: { getData }, fga: { resourceMapping: { tool: { fgaResourceType: 'user', deriveId: ({ user }) => user.id, }, }, permissionMapping: { - 'tools:execute': 'read', + [MastraFGAPermissions.TOOLS_EXECUTE]: 'read', }, }, });🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.changeset/lazy-hornets-hide.md around lines 10 - 27, Update the changeset example to use the type-safe constant and bracket notation from the docs: replace the literal 'tools:execute' in the permissionMapping with the MastraFGAPermissions.TOOLS_EXECUTE constant and use computed property syntax (e.g. [MastraFGAPermissions.TOOLS_EXECUTE]: 'read'); ensure the example includes or assumes the MastraFGAPermissions import and that the mapping remains under the MCPServer fga.permissionMapping field so it matches the pattern used in the mcp-server.mdx reference.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/core/src/mcp/types.ts`:
- Around line 230-240: The resourceMapping field on MCPServerFGAConfig is too
permissive (Record<string,...>) allowing typos to slip through; change its type
to a keyed type that only allows the supported aliases ('tool' and 'tools') so
misconfigurations fail at compile time — update
MCPServerFGAConfig.resourceMapping to be something like Partial<Record<'tool' |
'tools', MCPServerFGAResourceMappingEntry>> (keeping
MCPServerFGAPermissionMapping unchanged) so server.ts code that reads
resourceMapping.tool and resourceMapping.tools is type-safe.
---
Nitpick comments:
In @.changeset/lazy-hornets-hide.md:
- Around line 10-27: Update the changeset example to use the type-safe constant
and bracket notation from the docs: replace the literal 'tools:execute' in the
permissionMapping with the MastraFGAPermissions.TOOLS_EXECUTE constant and use
computed property syntax (e.g. [MastraFGAPermissions.TOOLS_EXECUTE]: 'read');
ensure the example includes or assumes the MastraFGAPermissions import and that
the mapping remains under the MCPServer fga.permissionMapping field so it
matches the pattern used in the mcp-server.mdx reference.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: c89481d6-5ceb-4ec0-9246-f3016996034d
📒 Files selected for processing (6)
.changeset/lazy-hornets-hide.mddocs/src/content/en/docs/server/auth/fga.mdxdocs/src/content/en/reference/tools/mcp-server.mdxpackages/core/src/mcp/types.tspackages/mcp/src/server/__tests__/server-fga.test.tspackages/mcp/src/server/server.ts
Add MCPServer-level FGA resource and permission mapping overrides for tools/list and tools/call checks. This lets MCP tool authorization use a different scope from the instance-level tool mapping used by internal agent and workflow tool execution.
graysonhicks
force-pushed
the
graysonhicks/17508-mcp-fga-tool-authorization
branch
from
e127ef8 to
3cd29ef
Compare
dane-ai-mastra
Bot
added
tests: green ✅
abhiaiyer91
approved these changes
Jun 9, 2026
This was referenced Jun 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds
MCPServerFine-Grained Authorization mapping overrides so MCPtools/listandtools/callchecks can use server-specific resource and permission mappings without changing the instance-leveltoolmapping used by internal agent and workflow tool execution.Related Issue(s)
Fixes #17508
Type of Change
Checklist
ELI5
This PR lets each MCP server set its own access rules for listing and calling tools, so server requests are authorized using server-specific mappings instead of the global tool mapping used by internal agents and workflows.
Overview
Adds an optional
fgaconfig toMCPServerthat provides per-server Fine-Grained Authorization (FGA) overrides for resource and permission mapping used bytools/listandtools/call, decoupling MCP server authorization from the instance-leveltoolmapping used for internal agent/workflow tool execution.Problem Statement
Both MCP tool checks and internal agent/workflow tool execution previously used the shared instance-level
resourceMapping.tool, causing scoping conflicts:tool→team, deriveId uses teamId).Sharing the mapping forced trade-offs (weakened agent gates or synthetic context), making correct scoping difficult.
Solution
Implements per-server FGA mapping overrides on
MCPServer(solution#1from the linked issue) via an optionalfgaproperty:fga.resourceMapping(with optionalderiveId) andfga.permissionMapping. MCPtools/listandtools/callauthorization resolve their resource type/ID and permission using these server-level overrides without changing the instance-leveltoolmapping.Changes
packages/core/src/mcp/types.ts
MCPServerFGAResourceMappingEntry(optionalderiveId),MCPServerFGAPermissionMapping,MCPServerFGAConfig.MCPServerConfigwith optionalfga?: MCPServerFGAConfig.packages/mcp/src/server/server.ts
fgaprivate field wired from constructor options.{ type: 'tool', id: resourceId }/ rawMastraFGAPermissions.TOOLS_EXECUTEwith a newresolveToolFGAParamshelper that appliesfga.resourceMappingandfga.permissionMapping(including derived IDs) and callsrequireFGAwith the resolved resource and permission.packages/mcp/src/server/tests/server-fga.test.ts
tools/listandtools/callverifying:deriveIdis invoked with{ user, resourceId, requestContext }.docs
JSON.stringify([serverName, toolName])unless overridden viafga.resourceMapping.fgaconstructor docs and a "Scope MCP tool FGA separately" section with a TypeScript example demonstratingderiveIdand permission mapping usage..changeset/lazy-hornets-hide.md
fgaoption for@mastra/mcpand@mastra/core(minor release).Tests & Docs
Impact
fgais optional; absence retains prior behavior.#17508.