Outcome
By the end of this lesson, you will be able to classify an action into its write tier, explain the three checks every write passes, and diagnose a refusal from its message rather than by guessing.
| Tier | Engineer |
| JTBD | ”Know what will be refused before I ask for it.” |
| Personas | Platform Engineer · SRE · Developer |
| Prerequisites | M6.5, M6.6.L2 |
| Time | 9 minutes |
| Bloom verb | Classify (Analyze), Explain (Understand), Diagnose (Analyze) |
1. Concept
Reads are available at every level. Writes are governed by three independent things, and all three must hold:
1. THE ORGANISATION'S WRITE ACCESS SETTING set by an admin, and it names which tiers are admitted at all
2. YOUR LIVE ROLE checked per request, against your role right now, not at login
3. YOUR TOKEN'S CAPABILITY OAuth scopes, or the capabilities ticked when a PAT was mintedA token can carry less than you do. That is the point of a read-only PAT in CI: your identity could change production, the token cannot.
The tiers, stated plainly
TIER 1 METADATA ONLY renames, and budgets. ZopNight's own records only. No cloud state, no cost: a budget is a number you are watching against, not a change to anything.
TIER 2 REVERSIBLE deploys, rollbacks, schedules, overrides, tags. Bounded blast radius, may affect cost.
TIER 3 IRREVERSIBLE registering or deregistering infrastructure, database migrations, provisioned resource changes. No undo, or it spends money.Your tool list is your answer
The catalogue lists everything the server can expose. What your assistant actually sees is narrower, and it is filtered to what your token, role and organisation allow. Nothing advertised to you will fail on permissions, and nothing is hidden that you could have called. Asking your assistant what it can do is therefore a real answer, not a guess.
2. Demo
ADMIN, WRITE ACCESS TIER 2, FULL SCOPES "rename this environment" allowed tier 1 "deploy this service" allowed tier 2 "deregister that cluster" refused tier 3 not admitted
SAME PERSON, READ-ONLY PAT "deploy this service" refused token lacks capability
VIEWER ROLE, WRITE ACCESS TIER 3, FULL SCOPES "deploy this service" refused role does not permit itThree refusals, three different causes, one symptom.
3. Hands-on (6 min)
1. Ask your assistant what it is allowed to do in this organisation.2. Ask for a tier 1 action, a rename, and watch it succeed.3. Ask for a tier 3 action and read the refusal word for word.4. If you can, mint a read-only token, reconnect, and ask for the same tier 2 deploy that worked a minute ago.5. Compare the two refusals. They are not the same sentence.Do it through MCP. The same task you just did in the console, asked in one sentence.
BEFORE An account on any of the three products, and whatever role you already hold.ASK "What am I allowed to do in this organisation, and which write tiers are enabled?"CHECK the answer against what you expected. Most surprises here are a token carrying less than the person, which is by design.Tools behind it: get_my_permissions (read, Introspect), get_organisation (read, Introspect), list_organisations (read, Introspect). The full catalogue is at zop.dev/learn/mcp-tools.
4. Knowledge check
Q1
Your role is Admin, the org admits tier 2, and your deploy is refused. The remaining cause:
A. Your token does not carry the write capability
B. The image is unavailable
C. Deploys are tier 3
D. The service is locked
Show answer
Correct: A. Two of the three checks passed, so the third is the one left. A read-only token held by an admin is a deliberate arrangement, not a mistake, and it is why the check exists separately from the role.
Q2
Why is a refusal permanent rather than something to retry?
A. Rate limiting
B. Because the assistant caches it
C. Because the token is burned
D. Because none of the three checks change by asking again
Show answer
Correct: D. A refusal is a statement about configuration: the setting, the role, or the capability. Retrying is only useful for transient failures, and permission is not one.
Q3
Your assistant lists fewer tools than the public catalogue. This means:
A. Your list is filtered to what your token, role and organisation allow
B. The catalogue is out of date
C. Some tools are deprecated
D. Your client is old
Show answer
Correct: A. The narrower list is the useful one: nothing in it will fail on permissions, and nothing you could call is missing from it. Treat it as the authoritative answer for you rather than a subset of the truth.
5. Apply
When you set up MCP for a team, decide the token shape before the role. Most teams want humans on OAuth with their live role, and automation on a read-only PAT, so the dangerous half of the surface simply is not reachable from CI.
KEEP the three refusal messages, and which check produced each