The tiered write surface

Outcome

By the end of this lesson, you will be able to describe what each of the four write tiers unlocks, name the capabilities that have no tool at any tier, and explain where the decision is enforced and why it lives there.

1. Concept

There are two separate boundaries here, and conflating them is the most common mistake people make when describing this surface.

BOUNDARY 1: THE TIER          configurable, per organisation
  Governs whether mutating tools are reachable at all,
  and which class of them. Default: none.

BOUNDARY 2: NO TOOL EXISTS     not configurable
  Two capabilities have no tool at all, so no tier
  unlocks them, for anyone, ever. Raising the tier to 3
  does not reach them.

Boundary 1 is a decision your org owns. Boundary 2 is a product decision you cannot opt into.

Boundary 1: the four tiers

TIER            WHAT IT UNLOCKS                    TYPICAL EXAMPLE
────────────────────────────────────────────────────────────────────
none            nothing. Reads only.               (the default)

1 metadata      ZopNight's own records. No cloud   create or delete a
  -only         state, no cost.                    budget, update a
                                                   rec's status, manage
                                                   roles and members

2 reversible    bounded blast radius, and it may   edit or delete a
                affect cost.                       schedule, set an
                                                   override, ship a
                                                   deploy

3 irreversible  no undo, or it incurs cost.        start or stop a
                                                   resource (singly or
                                                   in bulk), delete a
                                                   service
────────────────────────────────────────────────────────────────────
EVERY WRITE TIER requires a token bound to the organisation.
ABOVE ALL FOUR: MCP_WRITE_ENABLED, a global kill switch,
default off. With it off the whole write surface is inert
regardless of any org's tier.

The tiers are cumulative: tier 2 includes tier 1. The jump that deserves the most scrutiny is 2 to 3, because tier 3 is where actions stop being undoable, bulk start/stop included. Tier 1 deserves more care than its name suggests: “ZopNight’s own records” include roles and memberships. At every tier the token must be bound to the organisation: a PAT reaches only the orgs selected when it was created, and an unbound token is refused every write.

Boundary 2: what no tier reaches

NO TOOL AT ANY TIER:
  1. Deleting the organisation
  2. Deleting a cloud account

  Also: no tool returns a secret value. get_service_config
  redacts every environment-variable value.

The reasoning is worth being able to state rather than just recite:

• Organisation and cloud-account deletion are the two operations whose blast radius is the entire tenant. There is no undo and no partial failure.
• Secret values never come back through a tool. Returning one would put a long-lived secret into an LLM context window, which is a place secrets do not come back from.

Just as important is what is not on this list, because older material claimed it was:

• Roles and members have tools at tier 1 (create_role, update_role, delete_role, add_org_member, update_org_member, remove_org_member). An agent can only do what its caller’s role already allows, so an Editor’s agent cannot manage roles any more than the Editor can in the UI (M4.1), but an Admin’s agent can, once the org is at tier 1 or above.
• Bulk start/stop has tools at tier 3 (bulk_start_resources, bulk_stop_resources). One mis-parsed instruction can become an estate-wide event, which is why it sits at the top tier.

Where it is enforced

THE GATEWAY RESOLVES, PER CALL:
    the org's mcp_write_tier
  ∩ the caller's LIVE RBAC role
  ∩ the token's own scope

The MCP server owns no authorisation logic. It is a stateless
executor.

Three properties fall out of that, and they are what make the surface defensible:

1. One implementation. There is no second copy of the rules in the MCP server to drift out of sync with the gateway’s.
2. tools/list is filtered. A tool is advertised if and only if the gate would allow the call. An agent is never told about a capability it cannot use, so it cannot be socially engineered into trying.
3. RBAC is live. Narrow a role and the surface narrows within about 30 seconds (the gateway caches permission answers briefly). Nothing is snapshotted at grant time.

The gate is deliberately not a per-service environment variable. That pattern scatters the access decision across every service, each of which must re-derive caller identity, and a service that forgets to check fails open. The single legitimate environment variable is the global kill switch, which makes an unfinished surface inert at merge and is not a per-request access decision.

Intersection, not union

The most common misreading of the model: people assume raising the org tier grants the capability. It does not. It permits the capability, which the caller’s role must then also grant.

ORG AT TIER 2, CALLER IS A VIEWER
  -> reads only. The tier permitted reversible writes;
     the Viewer role grants none, and the intersection is empty.

ORG AT TIER none, CALLER IS AN ADMIN
  -> reads only. The role grants everything; the tier
     permits nothing.

ORG AT TIER 2, CALLER IS AN EDITOR
  -> the reversible subset of what an Editor may do.

Raising the tier never gives anyone a capability they did not already have in the UI. It decides whether their existing capabilities are reachable from an agent.

2. Demo

An org walking the boundary during a security review:

CURRENT STATE
  mcp_write_tier:        none
  MCP_WRITE_ENABLED:     off (fleet-wide)
  Connected users:       14 (9 Editor, 4 Viewer, 1 Admin)
  Advertised tools:      reads only, all 14 callers

QUESTION 1: "Our Admin has a PAT. Could they delete a cloud
             account through Claude?"
  No, twice over. The org is at tier none, and no tool deletes
  a cloud account, so tier 3 would not reach it either.

QUESTION 2: "If we moved to tier 2, what changes for the
             4 Viewers?"
  Nothing. Viewer grants no mutations, so the intersection
  stays empty. Only the 9 Editors and the 1 Admin would gain
  the reversible subset of what they can already do in the UI.

QUESTION 3: "Could an agent grant itself more access?"
  Not at tier none. Role and member tools exist at tier 1, so
  from tier 1 up the Admin's agent could change roles, exactly
  as the Admin can in the UI. No agent ever exceeds its
  caller's own role.

QUESTION 4: "Show us the evidence, not the claim."
  Activity → Audit Logs. Every MCP call is there, reads
  included: tool name, caller, timestamp, request body. Read
  response payloads are dropped by design.

DECISION: stay at tier none for now; revisit after the
          incident-response drafting workflow has run for a
          quarter and we can name a write we actually want.

The last line is the point. “We could not name a write we actually wanted” is the correct reason to stay at the default, and it is a stronger position in a review than an architectural claim you would have to walk back later.

3. Hands-on (6 min)

1. Your org's current tier:                        _________
   Settings → Organization, MCP Server section

2. From memory, list the capabilities with no tool at any tier:
   ___________  ___________

3. For each of these, say which boundary blocks it and
   whether raising the tier would change the answer:

   a. Agent stops an idle EC2 instance
      Blocked by: ____________  Tier would change it? Y / N
   b. Agent adds a teammate to the Admin role
      Blocked by: ____________  Tier would change it? Y / N
   c. Agent reads an AWS secret key
      Blocked by: ____________  Tier would change it? Y / N
   d. Agent stops 200 resources in one call
      Blocked by: ____________  Tier would change it? Y / N

4. If your org is above tier none, name the person who
   owns that decision:  ______________________________

Answers to 3: (a) the tier, and yes: stop_resource is tier 3. (b) the tier, and yes: update_org_member is tier 1, for a caller whose role allows managing members. (c) no tool returns a secret value, and no tier changes that. (d) the tier, and yes: bulk_stop_resources is tier 3.

4. Knowledge check

Q1

An organisation raises mcp_write_tier from none to 2 (reversible). A user with the Viewer role connects an agent. What can that agent now mutate?

A. Everything reversible, because the org permitted it
B. Nothing
C. Only metadata
D. It depends on the PAT’s age

Q2

Which of these would become reachable if an org moved all the way to tier 3 (irreversible) with an org-bound token?

A. Deleting a whole cloud account together with its stored credential
B. Deleting a budget or a schedule, for a caller whose role permits it
C. Deleting the whole organisation, for a caller who is its Admin
D. Reading a stored AWS secret key straight back out of the vault

Q3

At which write tier can an agent bulk start or stop resources?

A. Tier 1 (metadata-only)
B. Tier 2 (reversible)
C. Tier 3 (irreversible)
D. At no tier

5. Apply

Confirm your org’s tier at Settings → Organization (MCP Server section), then write down the two deletions that have no tool somewhere your security team can find it. It is the half of the answer that does not change when your configuration does.

If a write workflow keeps coming up in conversation, do not reach for the tier first. L2 covers which surface should own it, and MCP is frequently the wrong answer even when it is technically available.

Related lessons

• M6.1.L2: Read by default: the write-tier contract
• L2: Choosing the right write surface (next)
• L3: Raising the tier: the decision
• M6.3.L2: The org-level MCP toggle

Glossary terms touched

Write tier · Org-bound token · Gateway enforcement