Group-Based Tool Access

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

Use it when one MCP gateway serves more than one team or customer and they should not all see the same tools, instead of running a separate gateway for each.

How enforcement works

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

• A tool matcher that selects which tools the rule applies to
• One or more required groups. A caller in any one of them satisfies the rule.

Enforcement runs at the tool access hook point, so it covers both discovery and execution. A caller who does not satisfy a rule does not see the tool in their tool list, and a call to it by name is refused.

The Engine checks membership with your identity provider and caches the answer per user and per group for five minutes.

Tool matchers

When more than one rule matches a tool, only the most specific rule applies: an exact match beats a toolkit match, and a toolkit match beats the global match. The caller is checked against that one rule only.

A tool that no rule matches stays visible to everyone. Add a global * rule to set a default for tools you have not named.

Tool matchers are not case-sensitive. Group names are: a rule requiring Finance-Admins is not satisfied by membership in finance-admins. Group IDs are not case-sensitive.

Choose an identity backend

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

A required group can be a name or an ID in every backend: an Okta group name or ID, an Entra ID group name or object ID, or a SailPoint role or access profile name or ID. An ID is exact and survives a rename, so use IDs for sensitive rules.

Okta API token

An Okta API token has the same permissions as the administrator who creates it. Create the token from an account whose administrator role can read users and groups, such as a service account with the Read-Only Administrator role. If that account’s role changes, the token’s permissions change with it.

Entra ID app permissions

Register an app in Entra ID and give it the GroupMember.Read.All application permission (not delegated), then grant administrator consent. Until consent is granted, the app can still sign in but every membership lookup fails.

Entra ID group names

Entra ID does not require group display names to be unique, and many tenants let members create their own groups. A rule that names finance-admins could be satisfied by someone who creates a group with that name and joins it.

For sensitive rules, use the object ID. You can copy it from the group’s overview page in Entra ID. This does not apply to Okta or SailPoint, where only administrators can create groups, roles, and access profiles.

Match callers to directory users

The backend looks up the caller in your directory using the user ID the request carries. Arcade passes that value to your directory unchanged and does not assume it is an email address.

A caller whose user ID your directory does not recognize matches no groups, so every gated tool is hidden from them. Before you turn on a rule, confirm that the user IDs your gateway sends are ones your directory knows.

SailPoint Identity Security Cloud

SailPoint support covers Identity Security Cloud only. IdentityIQ is not supported.

Rules match roles and access profiles. Entitlements and identity attributes do not count toward a rule. Name a role or access profile by its name, or by its ID from the item’s page in Identity Security Cloud.

Only provisioned access counts. Access that has been requested or approved but not yet provisioned does not satisfy a rule.

A caller is matched to an identity by email or alias. If no identity matches, or more than one does, membership cannot be verified and the caller’s gated tools are hidden.

Required API client rights

Create a read-only API client in Identity Security Cloud using the OAuth 2.0 client credentials grant. It needs exactly two rights:

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

Configure in the Dashboard

You can edit rules and credentials after you create the extension. When you edit, leave a secret blank to keep the stored one. If you change the backend, org URL, tenant URL, tenant ID, or client ID, you must enter the secret again.

Configure via the API

Create a configuration with the plugins API. The example below hides every Slack tool from callers outside two Okta groups, limits Slack.SendMessage to one 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"] }
      ]
    }
  }'

To use another backend, replace the okta block with an entra or sailpoint block:

{ "backend": "entra", "entra": { "tenant_id": "11111111-2222-3333-4444-555555555555", "client_id": "66666666-7777-8888-9999-000000000000", "client_secret": "..." } }

{ "backend": "sailpoint", "sailpoint": { "tenant_url": "https://acme.identitynow.com", "client_id": "2c9180835d2e5168015d32f890ca1581", "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, the rules you send replace the existing rules, so send the complete list. A credential you leave out keeps its stored value, unless the update changes the backend, a URL, the tenant ID, or the client ID, in which case the credential is required.

How quickly changes take effect

A membership change reaches Arcade after your identity provider applies it and the cached answer expires, which takes up to five minutes:

• Granting access: the caller does not see the tool until the change reaches Arcade.
• Revoking access: the caller can keep seeing the tool until the cached answer expires.

When membership cannot be verified

If the Engine cannot determine membership, because the identity provider is unreachable or does not recognize the caller, the tool is hidden. This keeps an outage from silently removing the boundaries you set.

To show the tool instead when membership cannot be verified, turn on Show the tool when membership cannot be verified for the rule in the Dashboard, or set allow_on_unavailable on the rule in the API:

{ "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