Access

Backed by: the control plane’s connection listing, and the audit trail’s usage read. Scopes: connections:read · audit:events:read.

What it answers

Every connection on your Worker, agents included: what it was granted, what it was not, what each of its credentials last did, and which granted scopes it has not used.

Scopes is what a grant is, which scopes a connection used is the read behind the finding, and roles and permissions is who answers for an agent.

The pane sits in the rail’s Compliance group. It reads the Worker’s own GET /control-plane/connections for the index. The finding asks the audit trail’s GET /audit/control-plane/usage once, with no connection named, so it counts every connection’s calls in one statement: two signed reads, however many connections the Worker lists. A connection’s record asks the same read for that one connection, for its last use and what it was refused. Every answer is dropped with the screen, like every other pane.

Two filters narrow the index, over the connections read. Acting through it keeps an agent’s, a script’s, a dashboard’s, or those that recorded none, on every plan. Credential use, last 90 days keeps the connections with an allowed call in that window, or those with none, answered from the same usage read the finding makes. It is on Team: below it the filter is drawn locked, naming the plan, and on an audit trail with no calls it is locked and says nothing here can say what went unused. The overview is how the filter panel works.

The facts, on every plan

A connection’s record opens on its grant:

  • Granted and Withheld: the scopes it holds, and the declared scopes it does not. For the connection this dashboard reads through, the grant is the one the manifest reports, which is the one your Worker enforces on that very read.
  • Last observed and last action, per credential: the latest allowed call each key made, with the scope it ran under and its method and path. The scope sits beside the time because an idle credential whose last act was a deletion reads very differently from one whose last act was a read.

These render on every plan. Hiding a security-relevant fact behind a paywall is the one thing the dashboard does not do.

Granted, not used, on Team

The finding is the over-grant question: one row per credential holding scopes it did not use in the range as recorded, ranked by how many it holds unused, most first. With no connection selected, the record draws the whole ranked answer. A connection’s own record draws its row. A row names the credential, the scopes, and the keys its calls named: Support bot holds scopes it did not use in the range as recorded: entitlements:write, users:write. Keys seen: key-1. Narrow it to what it used. A connection with no call in the range holds every granted scope unused. The question has a row in reports, so the same answer can go in a document.

The range is the filter strip’s, and opens on the last 90 days, so a monthly or quarterly job’s scopes are not flagged. The strip narrows it to the last day, 7 or 30 days, and offers no Everything kept here.

  • “As recorded”, never “never used”. Retention prunes the trail by time, so when the trail starts after the range does, every row says a use before it is not seen.
  • A dropped audit write is not proof of no call. The pane says the finding is only as complete as the trail.
  • A grant that was fully used reads as clean, plainly: Nothing to fix.
  • The dashboard’s own calls count as use. A scope this dashboard reads with was used, and the pane does not subtract it.
  • manifest:read and keys:rotate are never a finding. Without them a management client discovers nothing and cannot replace its key, so every narrowing keeps them.

Beside it, Refused, not granted lists the scopes the connection asked for and was never given, with how many refusals. That is an under-grant, not one it wastes, so it is never folded into the finding.

For the connection this dashboard reads through, the record on Team also lists Nothing here spends: the granted scopes that no pane, read or act in this product would call on your Worker. It needs no audit trail, so it holds before the first call, and it is over-grant all the same: a write scope listed there is held against your production system for nothing. When every scope the grant holds has a control here, it says so: None. Every scope it holds has a control here. On Free and Solo that line is not drawn.

On Free and Solo, the finding, the under-grant and the command are locked, nothing is read for them, and the pane says what Team adds.

The command that narrows it

The dashboard changes no grant. It writes the command, and you run it. --scope on an update replaces the grant, so every command carries the whole set the connection should keep, never only what it drops: the scopes it used in the range, and manifest:read and keys:rotate where it holds them.

ConnectionThe command
This dashboard’s ownpithy dashboard connect --update, the scope panel’s command, carrying the scopes it keeps
An agentpithy mcp connect --update, run by the agent’s principal, signed in as themselves. Its record also opens the member who answers for it, where it can be revoked
Any other keypithy dashboard connect --update --public-key --issuer, with the key file the connection already holds and the issuer it presents
No key at allNone. There is no key file to narrow it with, so the row says to change its trust where it was made

A narrowing that would keep nothing gets no command. Narrowing to nothing is revoking, and the row says so instead of writing one. A row with no command, for that reason, for a connection with no key, or for one keeping a scope that cannot be written as one shell word, links to the connection’s record instead.

When it cannot answer

It says why, rather than reporting zero use:

  • A Worker that composes no audit trail has nothing to say what a connection used.
  • A dashboard connection that withholds audit:events:read cannot make the usage read, and the pane names the scope. Scopes is how to add it.
  • An audit trail with no events cannot say what went unused.
  • A Worker whose usage read needs connectionId on every call answers one connection at a time, and the finding reads them all in one call. It says so, names the route, and sends nothing. Upgrading audit on the Worker is the fix.

The usage read is an aggregate: counts, two instants, and the method and path of the last allowed call. Nothing here asks the per-event detail read, which would also disclose the client IP and user agent.

ESC