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 are never exposed 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: THE NEVER-EXPOSED LIST     not configurable
  Four capabilities that no tier unlocks, 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      descriptive changes that do not    rename a schedule,
  -only         alter what runs                    edit a description

2 reversible    actions with a defined undo        stop a resource,
                                                   pause an autoscaler
                                                   policy, set an
                                                   override

3 irreversible  destructive actions.               delete a budget,
                ADDITIONALLY requires a token      delete a schedule
                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 it is the only one that also changes the token requirement. A personal access token cannot reach tier 3 even in an org configured for it; the token has to be bound to the organisation.

Boundary 2: what no tier reaches

NEVER EXPOSED, AT ANY TIER:
  1. RBAC            roles, policies, assignments
  2. User management users, invitations, memberships
  3. Deletion of an organisation or a cloud account
  4. Credentials     no tool reads or writes one
  5. Bulk actions    no fan-out mutation tool exists

  Plus: get_service_config redacts every environment-variable
  value. No tool returns a configuration secret.

Each of the four has the same shape of reasoning, and it is worth being able to state it rather than just recite the list:

• RBAC and user management are the controls that bound every other capability. An agent that can widen its own caller’s permissions has no ceiling, so the ceiling itself is off the table. This is the same argument that keeps Editor out of role management in M3.1.
• Organisation and cloud-account deletion are the two operations whose blast radius is the entire tenant. There is no undo and no partial failure.
• Credentials never leave the vault for any surface, agent or not. Exposing one through a tool would put a long-lived secret into an LLM context window, which is a place secrets do not come back from.
• Bulk actions turn a single mis-parsed instruction into an estate-wide event. The absence of a fan-out tool is what keeps the worst case bounded to one resource.

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 (Decisions #75 and #78).

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 on the next call. Nothing is cached 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 cloud-account
  deletion is on the never-exposed list, 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?"
  No. RBAC is on the never-exposed list. There is no tool that
  writes a role, a policy, or an assignment, at any tier.

QUESTION 4: "Show us the evidence, not the claim."
  Settings → Audit Log, filtered to source = mcp. Every call
  is there, reads included: tool name, caller, timestamp,
  request body. 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 → Access → MCP

2. From memory, list the never-exposed capabilities:
   ___________  ___________  ___________  ___________

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

   a. Agent deletes 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, tier 2 would permit it for a caller whose role allows it. (b), (c) and (d) are all the never-exposed list, and no tier changes any of them.

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. Adding a user to the Admin role within the current organisation
D. Reading a stored AWS secret key straight back out of the vault

Q3

Why does no bulk-action tool exist at any tier?

A. Bulk actions are slow and would time out well before the MCP request boundary
B. Because a fan-out mutation turns one mis-parsed instruction into an estate-wide event
C. The API does not support them, so there is no tool to expose in the first place
D. They were removed in a later release after an incident and never reinstated

5. Apply

Confirm your org’s tier at Settings → Organization → Access → MCP, then write down the never-exposed list 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 · Never-exposed list · Org-bound token · Gateway enforcement