Skip to main content

Role-based access control

Control who can administer MintMCP and which tools each user can call. These are two separate, complementary layers:

LayerGovernsMechanism
Org-level rolesAdministrative capabilities: creating MCPs, issuing API keys, viewing org-wide logs, managing members, configuring enterprise settingsBuilt-in member and admin roles, plus custom roles assembled from a permission set
Virtual MCP accessWhich connectors and tools a user can see and callAccess policies on each Virtual MCP (VMCP), typically referencing directory groups

The two are independent. An org-level role decides what administrative actions you can take; a Virtual MCP's access policy decides which tools appear in your MCP store. A user holds an org-level role and access to zero or more Virtual MCPs. So "what roles does MintMCP support?" has two answers depending on whether you mean administrative roles or tool-access grouping.

If you're here for "grant the Sales team access to Salesforce and Slack, grant Engineering access to GitHub and Jira, and make sure Finance sees neither", that's Virtual MCP access, covered from The pattern onward.

Org-level roles​

Every user has one directly assigned org-level role that controls which administrative actions they can take across the organization, separate from which tools they can call. Roles mapped from SCIM directory groups add permissions on top of the assigned one.

Two roles are built in:

  • Member: the default. Uses the Virtual MCPs they're entitled to and sees only their own activity.
  • Admin: full org-wide control over rules, connectors, retention, exports, members, and every Virtual MCP. Org-wide admin bypasses all Virtual MCP access policies.

Custom roles​

Member and admin are not the only options. Admins can define custom roles (named, org-specific roles assembled from a supported permission set) on the Team management page. This is the lever for "more than a member, less than a full admin": Security can hold guardrails and org-wide logs while Platform engineering holds connector deployment, without either team getting the whole organization. Custom roles can also be assigned automatically through SCIM directory groups, so directory membership drives administrative rights the same way it drives tool access below.

Roles and permissions is the canonical reference for this layer: the full permission set, example roles that map to real teams, and assignment mechanics including directory-group mapping. Custom roles control administrative reach only; access policies on each Virtual MCP still independently control which connectors and tools the same user sees.

The pattern​

  1. Define your roles. Typically these map to teams, functions, or directory groups you already have: Sales, Engineering, Support, Finance, Legal. The right granularity is usually the level at which tool access actually differs.
  2. Create one Virtual MCP per role. Each Virtual MCP groups the connectors that role needs: Sales gets CRM + calendar + communications; Engineering gets source control + issue tracker + observability. Curate the tool set so members only see what's relevant. See Packaging a Virtual MCP and Administration for the mechanics.
  3. Set each Virtual MCP's access policy to the matching directory group. Under the Access policy tab, turn off the Entire Organization toggle and grant Can Use to the group (or explicit user list) that represents the role; the add dialog lists directory groups above individual users. When groups come from your IdP via SCIM, assignment happens automatically as people join and leave teams.
  4. Ship it. Users connect to the Virtual MCPs they're authorized for; everything else is invisible: not just blocked, but not even listed. Offboarding from a role removes the tools at the next SCIM sync.

Why Virtual MCPs, not individual tools​

Grant access at the Virtual MCP level rather than tool-by-tool:

  • A role has a toolset, not a tool. Most access decisions at review time are "should Alice see Salesforce?" not "should Alice see salesforce.get_contact but not salesforce.list_contacts?" Granting at the Virtual MCP level matches how humans reason about access.
  • One policy, one audit trail, one place to change things. Tool-level grants fragment governance across dozens of servers, so every rotation, audit, and exception has to visit each server.
  • Context-window efficiency. Agents only load the tools inside the Virtual MCPs they're assigned. A Sales agent won't burn tokens describing Kubernetes tools it can't call anyway.
  • Least privilege falls out of role design. If Finance doesn't have a Virtual MCP, Finance can't see source control. You're not maintaining a long deny list: the absence of an assignment is the denial.

Individual tool controls (enable/disable, redescribe) still exist inside a Virtual MCP; they're how you refine what a role sees, not how you hand out roles. See Tool customization.

How directory groups plug in​

SCIM provisioning is what makes this operational at scale:

  • Users. Assigning a user to the MintMCP application in your IdP creates them in MintMCP. Deactivating them there deactivates them here.
  • Groups. When group sync is enabled, your IdP's groups appear as MintMCP subjects that you use directly in access policies.
  • Transitive. Add someone to the sales-team group in your IdP, and at the next sync they inherit every Virtual MCP whose access policy references that group. No MintMCP-side admin action required.

The source of truth for role membership is your directory, not a list inside MintMCP.

For setup see Configure SSO and SCIM; the setup wizard includes provider-specific guidance for group sync, and enterprise@mintmcp.com can help with your IdP's provisioning setup.

An example​

A company rolls out MintMCP to Sales, Engineering, and Support with three Virtual MCPs:

Virtual MCPConnectorsAccess policyCredentials
SalesCRM, communications, calendarGroup: sales-teamPer-user OAuth to each downstream
EngineeringSource control, issue tracker, observabilityGroup: engineeringPer-user OAuth, plus shared read-only creds for a knowledge base
SupportCRM (read-only), ticketing, knowledge baseGroup: support-teamShared service accounts, with user identity forwarded downstream

SCIM syncs those three groups from the IdP. A new hire in the Sales directory group shows up in MintMCP, the Sales Virtual MCP appears in their MCP store, and they connect their AI client with the right (and only the right) tools. When they transfer to Engineering, IdP group membership changes, SCIM propagates, and the Virtual MCP they see changes too. No per-person admin action on the MintMCP side during onboarding, role changes, or offboarding.

Downstream credentials are still separate​

Giving a user access to a Virtual MCP does not automatically authorize them to the downstream systems the connectors call. That split matters.

  • Per-user credential connectors. The user still authenticates once to each downstream service (OAuth to the CRM, OAuth to the source host). MintMCP remembers their token per service; Virtual MCP access just entitles them to start that flow.
  • Shared credential connectors. Virtual MCP access is what authorizes the user to issue tool calls using the shared credential, so rules and tool curation are the controls preventing over-privilege.

See Authentication models for the tradeoffs and User identity forwarding for how downstream systems can still enforce per-user controls even with a shared credential.

Access policy options​

The Access policy tab is a grant editor: an Entire Organization toggle plus per-user and per-group grants at one of two levels. Can Use lets the subject connect to and call the Virtual MCP; Can Edit includes Can Use and adds the ability to edit all of its settings. Three common configurations, in order of typical use:

  1. Everyone. Turn on the Entire Organization toggle so all members can use the Virtual MCP. Reasonable for servers that are truly universal (a general-purpose docs server), but rare in RBAC setups.
  2. Selected groups and users. The default RBAC mode. Leave the toggle off and grant Can Use to the directory groups that represent the role, plus any individual exceptions. Auditable, and it survives re-orgs as long as the groups do.
  3. No caller grants. With the toggle off and no Can Use grants, only the server's editors and org-wide admins can connect. Use this for Virtual MCPs that administer MintMCP itself (see Admin MCP) or for staging servers you're testing.

Individual users can be granted access on top of a group-based policy to handle exceptions (a cross-functional hire, a pilot participant) without creating a new group.

Read-only vs read-write: same connector, different Virtual MCPs​

A common RBAC goal: everyone in the company can query CRM records, but only Sales Ops can write. You don't need two connectors: you need two Virtual MCPs that each include the same connector with a different tool set curated.

  1. Register the connector once (e.g., Salesforce) in the MCP store.
  2. Create a Virtual MCP named plainly for reading ("Salesforce read-only") and include the connector.
  3. Under tool customization, disable every mutating tool, leaving only get_*, list_*, search_*, and similar read tools enabled.
  4. Set its access policy to a broad group (e.g., all-employees).
  5. Create a second Virtual MCP ("Salesforce full access") with the same connector, leaving the write tools (create_*, update_*, delete_*) enabled.
  6. Set its access policy to the smaller privileged group (e.g., sales-ops).

A user in the privileged group sees both; a user in only the broad group sees just the read-only server. The downstream credentials and upstream server are the same: the difference is entirely in which tools MintMCP exposes.

The pattern generalizes beyond read/write:

  • Tiers of access. Basic / Advanced / Admin Virtual MCPs for the same connector, each with progressively more tools enabled.
  • Scope filters on shared credentials. Pair a shared-credential connector with identity forwarding, and different Virtual MCPs can route the same connector to the same backend with different tool subsets.
  • Risk-based separation. One server for everyday analysts with read + low-risk writes; another for incident responders with destructive or override tools.
  • Sandbox vs production. Two Virtual MCPs backed by two different remote connector URLs (one pointed at a sandbox tenant, one at production) with different access policies.

Why this works cleanly:

  • No duplication of credentials. The connector is registered once; the Virtual MCPs compose it with different tool curation.
  • No duplication of rules or monitoring. Rules still fire on the underlying tool calls regardless of which Virtual MCP wrapped them, and the audit log captures which one was used.
  • Reversible. Tightening (moving a tool from read-write to read-only status) is an edit of tool customization, not a migration.
  • Least privilege enforced by absence. A user in the read-only group can't call write tools because those tools aren't present in their server's tool set, not blocked by a rule that could later be bypassed.

For the curation mechanics, see Tool customization.

Common edge cases​

A user needs two roles. Assign them to both directory groups. They'll see both Virtual MCPs in the MCP store and can connect to either, since there's no mutual exclusivity.

An exception for one person. Add them to the access policy as an individual user without changing the group. Document the exception; the audit log captures the admin change.

A short-term project team. Create a project-specific Virtual MCP and a project-specific group in your IdP, and archive both when the project ends. Don't repurpose long-lived Virtual MCPs for temporary work, or the audit trail gets noisy.

Per-VMCP admin delegation. Grant a user or group Can Edit on the Virtual MCP when a team lead should own their own server without org-wide admin. Org-wide admin bypasses all access policies. For delegation that isn't about a single Virtual MCP (letting someone manage members or create connectors without full admin), use an org-level custom role instead.

No IdP / no SCIM. The pattern still works with manually managed access, but keeping it current becomes your responsibility. Assigning individual users to each access policy is possible but brittle at scale.

Non-interactive callers. Access policies govern human members. CI jobs and agent runtimes authenticate with bearer keys minted against a Virtual MCP, usually owned by an agent identity rather than an employee.

Limited rollouts and testing​

Access policies make it straightforward to stage a new Virtual MCP for a small audience before opening it to the whole organization:

  1. Create the Virtual MCP with its connectors and tool curation as normal.
  2. Keep access narrow. Leave the Entire Organization toggle off and grant Can Use to a short list of individual users, or grant no one so only the server's editors and admins can connect.
  3. Test. The restricted group connects, exercises the tools, and confirms the connector setup, tool curation, and rules behave as expected.
  4. Widen access. Once validated, update the access policy to the target directory group or all members.

Group-based restriction requires SSO. Group membership comes from your SSO provider (see Configure SSO and SCIM) rather than ad-hoc groups defined inside MintMCP. If SSO-based groups aren't configured yet, restrict per-user (grant Can Use to specific users) or leave no caller grants. Either works for short-term testing; move to group-based policies once directory integration is in place.

Checklist​

Before shipping an RBAC setup:

  • Every role has a Virtual MCP; every Virtual MCP has a role.
  • Every access policy references a directory group, not a long list of individual users.
  • SCIM is enabled and the relevant groups are syncing.
  • Tool curation inside each Virtual MCP matches what the role actually needs, not the connector's default tool set.
  • Per-user vs shared credentials is right for each connector.
  • A test user in each group sees only the Virtual MCPs they should.