Group-Based Tool Access

As a platform operator, you can vary which tools a caller sees based on who they are. Group-based access is built into the Arcade Engine: you define rules that require membership in an identity provider group, and the Engine resolves membership and filters the tool list before the caller ever sees it. Like rate limits, this runs natively inside Arcade, so there is no server to build or host.

Use it when one shared MCP gateway serves more than one team or customer and they should not all see the same tools. Without it, the alternatives are a separate gateway per access boundary or a custom webhook extension.

How enforcement works

A group access configuration has two parts: an identity backend that holds your groups, and a set of rules. Each rule combines two things:

• A tool matcher that selects which tools the rule applies to
• One or more required groups the caller must belong to

Enforcement runs at the tool access hook point, so it applies to both discovery and execution:

• A caller who does not satisfy a matched rule has the tool removed from the response rather than being shown a tool that returns an error.
• Naming that tool directly is also refused, so hiding is not the only enforcement. A caller who guesses a tool name gains nothing.

Membership is resolved by querying your identity provider, then cached per user and per group for five minutes by default.

Tool matchers

When several rules match the same call, only the most specific rule applies: an exact match beats a toolkit match, and a toolkit match beats the global match. The caller is evaluated against that one rule only.

A tool no rule matches stays visible. This matters when you write a matcher by hand: a typo produces a rule that governs nothing, rather than a rule that hides everything. Use a global * rule when you want a default that covers tools you have not named.

Choosing an identity backend

One configuration uses one backend. All three are read-only integrations that never write to your directory.

With Okta, a rule’s required groups are group names. With Entra ID they are group names or group object IDs, which is a distinction worth reading below. With SailPoint, they are role names or access profile IDs, which is also covered below.

Naming an Entra group: name or object ID

Entra does not require group display names to be unique. Its object ID is the only unique key, and many tenants let ordinary members create groups. A rule that requires the display name finance-admins could therefore be satisfied by someone who creates their own group with that name and joins it, without ever belonging to the group you meant.

Two ways to name an Entra group in a rule:

Restricting a display-name match to ordinary security groups removes the surface most members can add to, but it is not a guarantee. For anything sensitive, put the group’s object ID in the rule. You can copy it from the group’s overview page in Entra.

Matching a caller to a directory user

The backend looks the caller up in your directory by the identity the request carries. In practice the Arcade user ID has to equal the directory login exactly.

This is the most common source of surprise in a real deployment. A caller whose Arcade identity is an internal ID, or an email that differs in case or domain from the directory login, matches nothing. Because the hook fails closed, that surfaces as tools quietly missing for everyone rather than as an error someone can act on. Confirm that the identity your gateway sends is the same string your directory knows the person by before you turn a rule on.

SailPoint Identity Security Cloud

SailPoint support has constraints the other two backends do not.

Identity Security Cloud only. IdentityIQ is a separate product with a different API surface and is not supported.

Rules match roles and access profiles, not groups. Raw entitlements and identity attributes do not count either. How you name each one differs:

An access profile has to be named by its ID. SailPoint’s access-items response documents displayName as the role display name on a role, but as the identity’s display name on an access profile, and it carries no access profile name at all, so a profile-name rule has nothing to match against. Copy the ID from the access profile’s page in Identity Security Cloud.

Resolving profile names to IDs for you would mean reading /v3/access-profiles, which needs idn:access-profiles:read. The section below deliberately excludes that right, so the rule carries the ID instead.

Only provisioned access counts. Access that has been requested or approved but not yet provisioned does not satisfy a rule. This is deliberate: a rule should reflect what someone actually has.

Required API client rights

Create a read-only API client in Identity Security Cloud using the OAuth 2.0 client credentials grant. No interactive user is needed. Grant it exactly:

• idn:identity-history:read
• idn:public-identities:read

Identity matching in SailPoint

SailPoint’s access read is keyed on an internal identity ID rather than a login, so an email caller is resolved to that ID first. Two cases are reported as errors rather than as a clean denial, so that a mapping mistake stays diagnosable instead of looking like a working deny:

• No identity matches the caller
• More than one identity matches the caller

Consider gating on the provisioned groups instead

Many organizations use SailPoint to provision access into Okta or Entra ID. If that describes you, pointing a rule at the resulting Okta or Entra group is simpler to operate and closer to real time, because you skip a layer of propagation. Reach for the SailPoint backend when the access you want to gate on lives only in SailPoint.

Configure in the Dashboard

Rules and credentials can both be edited after creation. Leave a credential field blank when editing to keep the stored value.

Configure via the API

Create a configuration with the plugins API. The example below hides every Slack tool from callers outside two Okta groups, restricts one specific tool to a narrower group, and leaves every other tool visible:

curl -s -X POST "https://api.arcade.dev/v1/orgs/{org_id}/projects/{project_id}/plugins" \
  -H "Authorization: Bearer $ARCADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plugin_type": "group_access",
    "name": "Team tool boundaries",
    "group_access_config": {
      "backend": "okta",
      "okta": {
        "org_url": "https://example.okta.com",
        "api_token": "'"$OKTA_API_TOKEN"'"
      },
      "rules": [
        { "match": "Slack.SendMessage", "required_groups": ["comms-team"] },
        { "match": "Slack.*", "required_groups": ["comms-team", "support-team"] }
      ]
    }
  }'

Swap the okta block for entra or sailpoint to use another backend:

{ "backend": "entra", "entra": { "tenant_id": "...", "client_id": "...", "client_secret": "..." } }

{ "backend": "sailpoint", "sailpoint": { "tenant_url": "https://acme.identitynow.com", "client_id": "...", "client_secret": "..." } }

To bind the configuration to the organization instead of a project, post to /v1/orgs/{org_id}/plugins. The API reference documents the full plugins API, including listing, updating, and deleting.

When you update a configuration, rules are replaced as a set rather than merged, because a rule has no identifier of its own. Send the complete list you want. Credentials behave the opposite way: omit one and the stored value is kept.

How quickly a change takes effect

Effective delay is the membership cache lifetime plus however long your identity provider takes to converge on the change. Both directions are worth understanding:

• Granting access fails safe. A caller stays without the tool until the change propagates.
• Revoking access is bounded, not immediate. A caller who is removed from a group can keep seeing a gated tool until the cached answer expires.

Identity providers are themselves eventually consistent, and in testing a group removal took roughly ten seconds to appear in one provider’s transitive membership data. If you need tighter propagation than the default five minutes, lower the cache lifetime on the hook.

When the platform cannot verify membership

If membership cannot be determined, because the provider is unreachable or does not recognize the caller, the tool is hidden. A degraded provider must not silently stop enforcing the boundaries you rely on.

For rules where availability matters more than the boundary, you can opt individual rules into the opposite behavior with allow_on_unavailable:

{ "match": "Slack.*", "required_groups": ["comms-team"], "allow_on_unavailable": true }

Next steps

• How hooks work - Where group access fits in the hook pipeline
• Rate limiting - Cap how often tools can be called
• Build your own - Enforce custom policies from your own webhook server
• API reference - Full plugins API documentation