Developers

Capability scopes and MCP connections

From the api repo’s docs/agent-scopes.md at 509805b

What an MCP client may do once a person connects it: each scope, what it allows, and how to disconnect. The tools that need each scope are in the tool inventory; every route’s scope is in the OpenAPI spec.

Where this page cites “the README” it means the api repo’s README, which is not published; the routes it describes are all in the OpenAPI spec.

An agent or integration working with Shelf normally acts as the person who connected it, with everything that person may do. An MCP connection lets that person hand over less: when an MCP client (claude.ai, ChatGPT, Claude Code, Cursor, ...) connects through the hosted MCP's OAuth sign-in, Shelf's consent step asks the person to name the connection and pick its capability scopes. The client's tokens then act as them, but only within those scopes, until the person disconnects it.

Effective access is always the intersection of the person's own access and the connection's scopes. The api still scopes every query to the person's account, plan and feature flags; a scope only takes routes away. No scope can reach another person's documents, and no connection can do anything its owner could not.

Agent keys are retired. Shelf used to hand out its own bearer keys (shelf_ak_…) for this. They can no longer be made or used: the code refuses every key, live or not, and a shelf_ak_ bearer answers 401 with a message saying to connect with OAuth sign-in instead (the hosted MCP adds the resource_metadata challenge, so an MCP client starts that sign-in). Their records and what they did stay in the activity log (see History).

Scopes

ScopeAllows
shelves:readList shelves and their folders.
shelves:writeCreate and rename shelves; create, rename and move folders.
shelves:deleteDelete shelves and folders (and everything in them) to the trash, and restore them from it.
documents:readList, search and read documents, their text and their sites; gather evidence across them (/evidence); make bulk download links; see which Google Drive files were imported before.
documents:uploadUpload new documents, and import them from Google Drive.
documents:writeRename and move documents, read them again, review them, and build their sites.
documents:deleteDelete documents to the trash, and restore them from it.
shares:readSee a document's share links and the links shared with you.
shares:writeCreate and revoke public share links; remember or forget links shared with you.
parsers:readList, read and download parsers and their revisions; read the parser format, check a spec, read candidates.
parsers:writeImport, draft, edit and delete parsers; submit, test and activate candidates.
parsers:executeRe-read documents with a parser, or apply it to chosen documents.
webhooks:readList webhooks and their deliveries.
webhooks:writeCreate, change, test, redeliver and delete webhooks, and rotate their secrets.
audit:readRead the activity log: what was changed, when, and by which credential (including other MCP connections).

GET /api/v1/scopes lists them. Each route's scope is in internal/httpx/scopes.go; a test fails if a route is added without one.

Destructive and exposing capabilities are separate scopes, so they are never granted by accident:

  • deleting shelves, folders and documents needs shelves:delete or documents:delete, not :write;
  • a changeset (/api/v1/changesets, README "Previewing changes") needs the scope of the change it makes, to preview, read or apply it: documents:write to rename and move, documents:delete or shelves:delete to delete; a filing plan (/api/v1/filing/plan, README "Filing documents") makes a file.update changeset, so it needs documents:write;
  • creating a public share link needs shares:write;
  • sending documents to another system needs webhooks:write.

A delete moves things to the trash for 30 days, where restoring takes the same :delete scope; listing the trash takes shelves:read or documents:read (README "Deleting and restoring").

Some things no connection can do, whatever its scopes. Only the person, signed in themselves, can list or disconnect MCP connections (and only the consent step, with the person's own sign-in, can make one, so a connection can never mint a wider one), manage billing, and purge from the trash for good.

The consent step's presets:

PresetScopes
Read only (find and read documents)shelves:read documents:read
Organiser (read, rename and move; no deleting, no sharing)shelves:read shelves:write documents:read documents:write
Uploader (add new documents, nothing else)shelves:read documents:upload
All permissions (everything you can give)every scope the person may give, last; not shown when it would only repeat a preset above

Each preset offers only the scopes the person may give (a preset left with none is not shown).

Connecting, and disconnecting

The person adds Shelf's MCP server (https://shelf.tri2b.cloud/mcp) to their client. The client discovers the sign-in from the server's WWW-Authenticate resource_metadata challenge, the person signs in to Shelf, and Shelf's consent step shows:

  • the connection's name, prefilled with the client's own;
  • its permissions: a preset (Read only, Organiser, Uploader, All permissions) or a checkbox per scope;
  • Allow or Cancel (the client gets access_denied).

Allow records the connection (POST /api/v1/mcp-connections, activity connection.create), and the client gets short-lived access tokens for it. Connecting again makes a new connection. In the web app, Settings → MCP connections lists them, with Disconnect (DELETE /api/v1/mcp-connections/{id}, activity connection.revoke): the connection's tokens stop working at once, and its client must connect again. The api is documented in docs/openapi.yaml (tag Credentials).

What a connection may do

GET /api/v1/credential says what the caller's credential may do:

{"subject":"…","full_access":false,"scopes":["documents:read","shelves:read"],
 "credential":{"kind":"mcp_connection","id":"…","name":"Research assistant","client_id":"…"}}

A route the connection's scopes do not cover answers 403 with RFC 6750's challenge and a message an agent can show:

WWW-Authenticate: Bearer error="insufficient_scope", scope="documents:delete"

{"error":"This credential lacks the documents:delete scope, which this needs. Ask the user to connect again and allow it.",
 "code":"insufficient_scope",
 "message":"This credential lacks the documents:delete scope, which this needs. Ask the user to connect again and allow it.",
 "retryable":false,"required_scope":"documents:delete"}

A disconnected connection's token answers 401 MCP connection token is invalid, expired or revoked: connect again.

The MCP server reads the same GET /api/v1/credential, so tools/list shows a limited connection only the tools its scopes allow, and each tool's description names the scope it needs. A call to a tool outside them fails with the api's insufficient_scope message, naming the scope.

Compatibility: who has full access

These credentials keep full access:

  • the web app's session cookie;
  • Zitadel access tokens: the mobile app's and shelf-mcp login's.

A bearer whose scope claim names any capability scope is narrowed to those scopes. Zitadel does not issue such tokens today (see below), so in practice an agent gets narrower access only through an MCP connection.

Why Shelf's own connections, not Zitadel scopes

Zitadel v4.19.3 (auth.tri2b.cloud) cannot carry a grant's scopes to the api. Checked on 2026-10-05 with a client-credentials token for a throwaway machine user (accessTokenType JWT) in the Shelf organization, asking for openid urn:zitadel:iam:org:project:id:<Shelf project>:aud shelf:documents:read documents:read: the JWT access token had only iss sub aud exp iat nbf client_id jti, no scope claim, and the token response had no scope either. Zitadel accepts scopes it does not reserve and drops them.

The other Zitadel mechanisms do not fit either:

  • Project roles requested with urn:zitadel:iam:org:project:role:<key> narrow the roles claim only to roles the user was *granted*. Every Shelf user would need a grant of every capability role, and a user without a grant would get a token with no roles, indistinguishable from a request that asked for none: a narrowing could silently become full access.
  • Actions can add claims, but not from the scopes a grant asked for, and changing them is instance-wide configuration outside this repo.
  • Introspection would put Zitadel in the path of every request.

So Shelf keeps the scopes itself. Shelf first did that with agent keys, pasted into clients as bearers; now the hosted MCP's OAuth proxy records an MCP connection (mcp_connections, migration 045) at its consent step and issues tokens bound to it, which the api verifies and narrows itself. They need none of the above, are disconnected at once, and record which client acted. The decision is in CONTEXT.md.

History

Agent keys' records (table agent_keys, migration 032) are kept for history; none can be used, whatever their state (the code refuses every shelf_ak_ bearer, and no migration revokes them). The activity log keeps what they did: events whose actor.kind is agent_key (with the key's id and name), and the keys' own agent_key.create, agent_key.revoke and agent_key.extend events. GET /api/v1/audit and the MCP's get_activity still filter and show them (actor_kind=agent_key, actor_id=<key id>), and GET /api/v1/agent-keys lists the old keys' records, read only, to name them.

For the api

  • auth.PrincipalFrom(ctx) is the caller: Subject, Scopes (nil for full access) and Credential (kind session, bearer or mcp_connection, with the connection's id and name or the bearer's client_id). The activity log (internal/audit, README "Activity log") attributes every change with it.
  • Table mcp_connections (migration 045), internal/mcpconn.
  • auth.Middleware refuses a shelf_ak_ bearer before any verifier (auth.AgentKeyRetiredMessage).