Designing scopes for an MCP agent: a practical playbook

Most teams give their first MCP agent too much access. They paste in *:write because the docs example used it once, and then they spend a week wondering why the agent rewrote a pricing page or marked half the lead pipeline as duplicates.

The fix isn't more prompting. It's understanding the four knobs that actually control an agent's blast radius in Slab5 — and the one reflex that ties them together.

The four knobs

The effective access of any MCP client (or OAuth subject grant) is the intersection of:

1. Coarse scopes on the credential. Per module, read or write. Today: crm:read, crm:write, support:read, support:write, tasks:read, tasks:write, activity:read, activity:write, cms:read, cms:write, assets:read, assets:write, integrations:read, integrations:write, analytics:read, analytics:write, bi:read, bi:write, audit:read, and settings:admin. No sub-scopes. 2. Workspace role. owner, admin, member, agent, readonly. The agent role is the right default for agent identities — it can do module reads and writes its scopes allow, but it cannot create or revoke credentials, change module access, rename the workspace, send invitations, or change MCP auth policy. 3. Module enablement. A support:write scope is useless if Support is not enabled in the workspace. Module enablement is a workspace-wide on/off switch you control independently of scopes. 4. OAuth subject grants. For organization MCP rollouts, a workspace admin can attach an explicit grant to a specific OAuth subject that *reduces* effective scope further. Grants can subset, never broaden. This is how you let one person's Claude integration touch CRM while another person's only sees Support.

And above all four: the workspace boundary. If an agent has no business reading client A's data, run it in client B's workspace, not with cleverer scopes in client A's.

A starter setup

For a brand-new triage or assistant agent:

• Create one MCP client in the target workspace. One credential per agent, never shared.
• Assign it the agent workspace role. This alone removes credential admin, settings admin, and destructive workspace actions — the agent cannot escalate its own access.
• Grant only the coarse module scopes you actually need. Typical starter: crm:read, support:read, tasks:read, tasks:write, activity:read, activity:write, cms:read.
• Add a write scope per module only when you have a concrete workflow that needs it. support:write for triage that updates priority and queue. cms:write for drafting revisions. crm:write only after you've watched the agent for a couple of weeks.
• Leave settings:admin, integrations:write, analytics:write, and bi:write off unless the agent is specifically an admin or webhook-managing agent.
• For organization OAuth-connected agents, layer an explicit subject grant on top that subsets further. A user with broad workspace access can still hand their Claude or ChatGPT integration just crm:read, crm:write, and tasks:write.

What about "don't let it convert leads"?

Slab5 today does not have a crm:write:convert scope distinct from crm:write. So how do you prevent an agent from converting twenty leads into duplicate contacts?

Three practical patterns:

1. Don't give the agent `crm:write` at all. A triage agent with crm:read plus activity:write can propose conversions as Activity Log entries without performing them. Useful, zero-risk. 2. Grant `crm:write`, but trust the audit log + your revocation reflex. Every conversion is recorded against the agent identity. If you see one you didn't expect, revoke the credential. The blast radius is whatever the audit log shows. 3. Run the agent in a separate workspace with mirrored read access. It can analyze, summarize, and propose; it can't reach the real CRM at all.

Finer-grained scopes (a crm:write:convert distinct from crm:write) are on the roadmap. Until they ship, the workspace role, the audit log, and a fast revocation are what enforce the line.

Audit log + revocation = the feedback loop

For the first month, open the audit log filtered by the agent's identity and skim every write. You'll find at least one scope you can drop (the agent never used assets:write) and at least one decision you want to reconsider (the agent updated a deal stage in a way you didn't expect). Adjust scopes and redeploy.

The one-click kill switch on the credential is what makes this safe. The audit log is what makes it adjustable.

Common mistakes

• Granting *:write everywhere on day one. The agent rarely needs it; even when it does, you want to discover that by watching the audit log fill up, not by debugging after a bad write.
• Assigning member or admin as the workspace role for an agent identity. Use agent — it exists precisely so agent credentials cannot administer the workspace.
• Sharing one MCP client across multiple agents. Use one credential per agent so the audit log attributes each action to a single actor.
• Treating a prompt as access control. A prompt that says "do not delete records" is a wish. A credential that lacks the relevant *:write scope is a guarantee.
• Skipping module enablement. If you don't need BI in this workspace, leave it disabled. The agent then cannot even attempt BI calls regardless of what scopes are on its credential.

Create one MCP client per agent. Assign the agent workspace role. Grant only the coarse module scopes the agent actually needs. For org rollouts, attach an OAuth subject grant that subsets further. Review the audit log filtered to the agent's identity weekly; narrow scopes or revoke the credential when behavior surprises you.

API keys follow the same coarse-scope model. Keep human-facing app keys and agent keys separate so audit attribution stays clean. The workspace boundary is the strongest scope you have — use it.