# Roles, Restrictions and ACLs in MCP: Three Layers

> Roles restrictions and ACLs in MCP are three layers: a role says what a member may do, a restriction which tools they reach, an ACL who may use one connection.

**TL;DR** Elaichi separates access into three layers: a role (one per member, 58 permissions to draw from), restrictions (allow and block rules on a role or one member), and resource ACLs (view, use or edit on one connection, toolbox, template or connector). Collapsing them into a single permissions model is the usual cause of a rollout that either blocks too much or shares too much. Role, team and restriction changes take effect within about two minutes; revoking a share takes effect on the next call.

## The rollout that blocks the wrong thing

A finance lead asks why Claude cannot read the Xero connection her team shares. An admin opens Elaichi, sees she holds the Member role with `tool:execute`, and concludes the permission is fine. It is. The block is somewhere else: either a restriction rule on her role, or the simple fact that nobody granted her use on that connection.

This is the standard failure. One question ("can she do this?") has three different answers in three different places. Roles restrictions and ACLs in MCP are three layers, and an admin who knows only one of them debugs the wrong one. MCP (the Model Context Protocol, the standard an AI client speaks to reach tools) does not define any of this. Each control plane decides for itself. Elaichi splits it into three.

The AI client adds a prompt of its own on top, and that prompt is not one of the three. Anthropic documents connector tool permissions of Always allow, Needs approval or Blocked, applied to a whole connector, a category of its tools or a single tool ([support.claude.com](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities), checked October 2026). Cursor asks for approval before using MCP tools by default ([cursor.com](https://cursor.com/docs/mcp), checked October 2026). OpenAI says ChatGPT may ask for confirmation before a write action, depending on app permissions and the action's context ([help.openai.com](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt), checked October 2026). None of those decides who may reach an account. That is the third layer below.

## What are roles, restrictions and ACLs in MCP?

In Elaichi, roles restrictions and ACLs in MCP are three separate layers, each answering a different question about a single tool call.

- **Role.** What actions this member may perform in the organization. A role is a bundle drawn from Elaichi's catalog of 58 permissions, each an action string such as `tool:execute`, `connector:create` or `audit:view`.
- **Restriction.** Which connectors and which individual tools this member may reach. A restriction rule has a mode (allow or block), a target, a list of whole connectors and a list of single tools.
- **Resource ACL.** Who may use one specific connection, toolbox, template or connector. A grant is one of three levels: view, use or edit.

A call must clear all three. The role must carry `tool:execute`. No restriction may block the tool. And the caller must reach the connection behind it, either because they own it or because a grant says so.

Write these as three questions, in this order, and most access debugging gets short: does their role allow the action, does a rule block the tool, and can they reach the account?

## Why does each member hold exactly one role?

A member holds exactly one role in an organization, and the database enforces it. Role writes refuse zero roles or more than one with a 400 `role_cardinality` error, and the member role table carries a unique index on the user id.

That is a design choice, not a limitation to work around. Each role is meant to be a complete persona. A member's permissions are their role's permissions, with nothing to union. When an admin asks for two roles at once, the refusal says so plainly: "A member can hold only one role in an organization. Assign a single role, or create a custom role that combines the permissions you need."

Elaichi ships eight system roles. Six form a strict subset chain: Guest, Member, Team Admin, People Admin, Org Admin, Org Owner. Each tier holds everything below it plus at least one more permission. Billing Admin and Auditor sit off the chain as standalone personas. Guest, Billing Admin and Auditor are free seats; a custom role is always billable, even one holding only view permissions.

For the permission side of role design, including which role to start a rollout on, see the longer treatment in [designing roles for AI agents](/blog/designing-roles-for-ai-agents/).

## What can a restriction target, and what can it not?

A restriction targets either a role, applying to every member who holds it, or one member. In Elaichi, restriction targets are role or user only; the organization default is the absence of a rule, which means allow everything. To keep a team off a tool, write the rule on the role its members hold, or on each member.

Two layers apply at once: the rules on the member's role, and the rules aimed at them personally. A connector or tool passes only when both layers admit it. A personal rule can only narrow what the role allows. It never replaces or loosens a role rule. The one way to lift a role-level block for one person is an access request an admin approves, which records an access grant for that requester and writes no restriction rule.

Within each layer, allow rules merge into one allowlist, block rules merge into one blocklist, and a block always beats an allow. An allow rule turns on the allowlist for its layer just by existing. An allow rule that names nothing therefore blocks every connector and tool for its target, and its own summary says so.

Allow rules and block rules also match differently. A block matches by tool name or by the operation the tool performs. An allow matches only by the operation Elaichi pinned when the rule was saved. [Why blocks match tool names but allows don't](/blog/block-matches-name-allow-matches-operation/) works through the consequence.

## How does sharing differ from permissions?

Sharing is the third layer, and it answers a question neither of the others touch: who may use this one thing. Connections, toolboxes, templates and connectors all share one mechanism, a [resource ACL grant at view, use or edit level](/blog/resource-acl-primitive-view-use-edit/), whose grantee is a user, a team, or the whole organization.

Here is the part that catches admins. A member sees only what they own or what has been explicitly shared with them. No organization permission widens a listing. An Org Owner cannot list another member's toolboxes, and `connection:view` and `template:view` are marked "Reserved (no effect)" in the permission catalog precisely because access resolves from ownership or an explicit share.

So an Auditor, the free read-only role, holds 12 view permissions and still sees no other member's connections, templates or toolboxes. What it opens is billing, the connector catalog, restrictions, API token metadata, SSO and SCIM settings, logging and notification destinations, and the audit log.

The practical rule: permissions govern actions, sharing governs objects. A role never hands out a connection, and a share never hands out a permission.

## What goes wrong when the three layers are collapsed?

Treating all three as one permissions model produces four recurring mistakes.

**Writing a rule for a team.** Restrictions have no team target. An admin who assumes otherwise either finds no place to write the rule, or writes it somewhere it does not apply.

**Expecting a personal exception to loosen a role.** A rule aimed at one member can only narrow them. The way to lift a role-level block for one person is an access request, which an admin approves in the console; approval records an access grant for that one requester and writes no restriction rule. Every other role rule keeps applying, including ones added later.

**Assuming an admin can audit every toolbox.** Templates and toolboxes have no organization-wide oversight view. A toolbox an admin cannot see answers 404, not 403, and no permission changes that.

**Confusing a share with an identity.** Every call through a connection uses that one connection's credential, whoever is calling. A shared connection runs on its owner's sign-in to the third-party app. To give each person their own identity in the app, each person connects their own account. [AI agents with employee permissions](/blog/ai-agents-employee-permissions/) covers the per-person pattern in full.

## When does a change in each layer take effect?

The three layers do not change at the same speed, and the difference matters when an admin is watching a chat window for a fix to land.

**Roles, teams, restrictions and access grants: within about two minutes.** A member's roles, teams, permissions and resolved restrictions are cached, and every relevant write bumps a per-organization epoch. Elaichi's own design doc treats that figure as the worst case at a remote point of presence, not a typical delay. It is still the number to quote to an impatient admin.

**Shares and connections: on the next call.** For tool calls, Elaichi reads toolboxes, shares and connections fresh on every request, so revoking a share or disconnecting an account takes effect on the caller's next call.

**Grants and membership: on the next call.** Every MCP request re-reads the client's OAuth grant (the authorization a person approved for one AI client), so revoking a grant fails that client's very next request with a 401. Removing or suspending a member revokes their grants in the same step, so their clients stop on the next call too.

If an admin removes someone's role and their AI client keeps working for ninety seconds, that is the cache, not a bug. If they need it stopped now, revoking the grant or removing the member is the lever that acts on the next call. The places each check runs are set out in [where MCP restriction enforcement points actually sit](/blog/restriction-resolver-four-enforcement-points/).

## When you do not need all three

A company with five people and three connected apps does not need restrictions. Everyone holds Member, everyone connects their own accounts, and sharing stays between the people who built the toolboxes. The role layer alone does the work, and writing restriction rules at that size adds a thing to maintain and nothing to show for it.

The third layer earns its keep when one account has to be reachable by people who should not hold that account themselves: a shared billing login, a service account in a ticketing system, a connection pinned into a toolbox with locked arguments. The restriction layer earns its keep when a role must reach some of an app and not the rest.

If neither of those describes the situation yet, see [when you don't need an MCP gateway](/blog/when-you-dont-need-an-mcp-gateway/) before building a model nobody will maintain. When they do describe it, the ordering above is the one that keeps the three layers from being argued about as if they were one.

For the wider picture of who may do what in which app, read [MCP governance](/blog/mcp-governance/). For a single refusal traced from the client's call to the audit row, read [how an MCP tool restriction is enforced, end to end](/blog/what-a-tool-restriction-looks-like-on-the-wire/). For what each layer leaves in the record afterwards, read [what an AI agent audit log must capture](/blog/what-an-ai-audit-log-must-capture/). The connectors each layer applies to are listed in the [connector catalog](/connectors/).

## FAQ

### Can a member in Elaichi hold two roles at once?

No. A member holds exactly one role in an Elaichi organization, and the database enforces it with a unique index on the user id; a write naming zero roles or more than one is refused with a 400 role_cardinality error. To combine two roles' permissions, an admin authors a custom role that holds both sets. Custom roles need the role:manage permission and the custom roles plan feature, which Gold and Black both include.

### Can an Elaichi restriction be applied to a whole team?

No. An Elaichi restriction targets either a role, applying to every member who holds it, or one individual member. In Elaichi, restriction targets are role or user only; the organization default is the absence of a rule, which means allow everything. To keep a team's members off a connector or tool, write the rule on the role those members hold, or write one rule per member.

### Does an Org Admin in Elaichi see every member's connections and toolboxes?

No. In Elaichi, a member sees only what they own or what has been explicitly shared with them, and that holds for Org Owners and Org Admins too. No organization permission widens a listing: connection:view and template:view are marked reserved and grant no visibility, and a toolbox an admin cannot see answers 404 rather than 403. Access to a connection, toolbox, template or connector comes from ownership or an explicit grant at view, use or edit level.

### How long does a role or restriction change take to apply in Elaichi?

Within about two minutes. A member's roles, teams, permissions and resolved restrictions are cached, and every role, membership, team, restriction and grant change bumps a per-organization epoch that each location has to pick up. Elaichi's design doc treats that figure as the worst case at a remote point of presence, not a typical delay. Revoking a share, disconnecting an account, revoking an OAuth grant or removing a member all take effect on the next call instead.

### If I share a connection in Elaichi, whose account does the AI act as?

The connection owner's. Every call through a connection fetches credentials from that one connection's bound account, whoever is calling, so a shared connection runs on its owner's sign-in to the third-party app. To have each person act as themselves in the connected app, each person connects their own account, either in their own toolbox or by stamping a template and picking their own connection for each connector.

## Read next

- [Resource ACL view use edit: how Elaichi shares access](/blog/resource-acl-primitive-view-use-edit/) — How the resource ACL view use edit grant works in Elaichi, and why no org-level permission widens what a member can list.
- [Where MCP restriction enforcement points actually sit](/blog/restriction-resolver-four-enforcement-points/) — The mcp restriction enforcement points in Elaichi run at eight places, not four, and a ninth check inside the AI client would prove nothing.
- [How MCP tool restriction enforcement works, end to end](/blog/what-a-tool-restriction-looks-like-on-the-wire/) — Follow one rule through MCP tool restriction enforcement in Elaichi, from the admin who writes it to the final check on the resolved outbound URL.