Access tiers

Whether a call succeeds is decided by four gates, in this order. They are independent: clearing one says nothing about the next.

The most common mistake is assuming a credential is enough. It clears gate 2. Gates 3 and 4 still apply, and on a blocklet that has declared no network rules they will still refuse a write from an owner-role caller.

Gates 1 and 2 are transport-level: they answer with an HTTP status and no JSON-RPC result. Gates 3 and 4 are inside a successful MCP call: the call itself worked, the operation did not. See Errors.

Why there are four

Because three different parties decide them, and none can answer for another.

This is why a credential is not enough, and why no better credential would help. A credential is an answer to the runtime, and the runtime does not own gates 3 and 4. No token can speak for the blocklet, and none can add an operation the provider never implemented.

It also explains the failure shapes. Gates 1 and 2 are decided before a tool is reached, so they can only answer in HTTP. Gates 3 and 4 are decided by code that already ran, so they answer inside a 200.

Gate 1: the method allowlist

Without a credential, only these are allowed:

The rule is fail-closed: anything not on the list is refused, and in a batch every message must be allowed or the whole batch is refused.

Gate 2: the credential

Three ways to clear it:

Roles

When a person approves a client, the consent screen asks for an access level. Four are offered:

The credential carries the role the person picked, scoped to that blocklet instance. It is not a global role: the same person can be owner on one blocklet and have no access on another.

The role is an upper bound, not a grant. It cannot open a path that gate 3 has closed.

Gate 3: the path policy

This is the gate most callers hit and the one no credential can bypass.

A blocklet decides, per path, what a network client may do. Paths that were not declared are closed to the network, including to an owner. The refusal is explicit about the fix:

{
  "result": {
    "content": [{
      "type": "text",
      "text": "AFS_FORBIDDEN: Forbidden at /instance/notes.txt: network clients cannot write base paths; use a resolver overlay or internal code"
    }],
    "isError": true
  },
  "jsonrpc": "2.0",
  "id": 3
}

Read and list produce the same shape with cannot read base paths / cannot list base paths and declare a networkRead rule or use an overlay.

What the declaration changes, compared across two blocklets:

The last row is the one to remember. Writing from the network is not something a credential turns on; it needs a resolver overlay or code running inside the blocklet. If you are building an agent that must write, that is a decision for whoever owns the blocklet. See Declare what agents see.

Gate 4: provider capabilities

Each path is served by a provider that implements only some operations. afs_stat reports both what the provider can do and what you are allowed to do:

{
  "capabilities": ["list", "read", "stat", "search", "write", "delete", "exec", "explain"],
  "accessMode": "readonly"
}

capabilities is the provider's implementation. accessMode is your effective access after gate 3. A path can list write in capabilities and still be readonly for you.

Check capabilities before making an operation part of an integration. See AFS for the contract these operations belong to.

What this means in practice