Developers
Capability scopes and MCP connections
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
| Scope | Allows |
|---|---|
shelves:read | List shelves and their folders. |
shelves:write | Create and rename shelves; create, rename and move folders. |
shelves:delete | Delete shelves and folders (and everything in them) to the trash, and restore them from it. |
documents:read | List, 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:upload | Upload new documents, and import them from Google Drive. |
documents:write | Rename and move documents, read them again, review them, and build their sites. |
documents:delete | Delete documents to the trash, and restore them from it. |
shares:read | See a document's share links and the links shared with you. |
shares:write | Create and revoke public share links; remember or forget links shared with you. |
parsers:read | List, read and download parsers and their revisions; read the parser format, check a spec, read candidates. |
parsers:write | Import, draft, edit and delete parsers; submit, test and activate candidates. |
parsers:execute | Re-read documents with a parser, or apply it to chosen documents. |
webhooks:read | List webhooks and their deliveries. |
webhooks:write | Create, change, test, redeliver and delete webhooks, and rotate their secrets. |
audit:read | Read 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:deleteordocuments: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:writeto rename and move,documents:deleteorshelves:deleteto delete; a filing plan (/api/v1/filing/plan, README "Filing documents") makes afile.updatechangeset, so it needsdocuments: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:
| Preset | Scopes |
|---|---|
| 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) andCredential(kindsession,bearerormcp_connection, with the connection'sidandnameor the bearer'sclient_id). The activity log (internal/audit, README "Activity log") attributes every change with it.- Table
mcp_connections(migration 045),internal/mcpconn. auth.Middlewarerefuses ashelf_ak_bearer before any verifier (auth.AgentKeyRetiredMessage).