Developers
MCP server (shelf-mcp)
Coming soon: MCP access will be a paid plugin, and paid plans and plugins are not on sale yet. See the pricing page.
MCP clients connect to https://shelf.tri2b.cloud/mcp. Setup first, then every tool; the tool inventory lists each tool’s scope, side effects and how to undo it. New to it? The setup guides and agent workflows connect a client and walk through each workflow end to end. The HTTP API the tools call is described at /docs/api.
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.
shelf-mcp (cmd/mcp) lets Claude Code and other MCP clients work with
Shelf: browse shelves and folders, read documents and their text, search,
watch processing, upload, rename, move, re-read, share, delete and restore from the trash. It is modelled on nebula/projects'
projects-mcp, uses the same SDK (mark3labs/mcp-go) and follows the same
conventions: an embedded guide tool that works without a credential, a
whoami tool, compact JSON results, and a CLI that takes flags only.
It is an HTTP client of Shelf's own REST api. Every tool calls the same
/api/v1 routes the web and mobile apps use, with the signed-in person's
Zitadel (https://auth.tri2b.cloud) access token as Authorization: Bearer and never a session cookie. Every
call is therefore scoped to that person's owner_sub, exactly as in the
apps, and the MCP layer adds no privileges of its own. See
ADR 0009
in the docs repo for why it is built this way.
mcp-guides.md is the place to start: connecting
claude.ai, Claude Desktop, Claude Code or any remote MCP client to
https://shelf.tri2b.cloud/mcp, handling the credential, and five
end-to-end workflows with copyable prompts and the exact tool calls.
Connect to the hosted server
The hosted server is https://shelf.tri2b.cloud/mcp, and every client
connects to it with OAuth sign-in; there is no key to make or paste.
- claude.ai and Claude Desktop: Settings → Connectors → Add custom
connector, URL
https://shelf.tri2b.cloud/mcp, then Connect. A connector added in claude.ai shows in Claude Desktop under the same account. - Claude Code:
claude mcp add --transport http shelf https://shelf.tri2b.cloud/mcp, then/mcpin Claude Code, pickshelfand Authenticate.
The client opens Shelf's sign-in, then Shelf's consent screen: the connection's name (prefilled with the client's name), its permissions (the presets Read only, Organiser, Uploader and All permissions, or a checkbox per scope), and Allow / Cancel. The client then acts as you with only those permissions. Settings → MCP connections in the web app (<https://app.shelf.tri2b.cloud/settings/mcp-connections>) shows how many connections are active and lists them in a table, with Disconnect on each. mcp-guides.md has the steps for each client.
Status. The hosted server runs as the Fly app
tri2b-shelf-mcp, public athttps://shelf.tri2b.cloud/mcpthrough the landing proxy.shelf-mcp loginand the OAuth proxy sign in through the Zitadel app shelf-mcp; a login stored before Shelf moved its sign-in to Zitadel (2026-10-02) is refused with "runshelf-mcp loginagain".
Two ways to run it
shelf-mcp is one binary with two transports:
| Transport | How it's reached | Used by |
|---|---|---|
| stdio (default) | A local shelf-mcp process that the MCP client launches and speaks JSON-RPC to over stdin/stdout. | Claude Code on your workstation, for local development. |
HTTP (--http :8080) | The hosted, bearer-gated endpoint, https://shelf.tri2b.cloud/mcp. | claude.ai and ChatGPT connectors, and any remote MCP client. |
Either way, the caller's own Zitadel access token is what reaches the api. The HTTP transport never falls back to a token of its own.
Install (Claude Code, stdio)
Download the binary from the api repo's
GitHub Releases and register
it. Every v#.#.# release carries shelf-mcp_<version>_<os>_<arch>.tar.gz
for darwin and linux on arm64 and amd64, plus
shelf-mcp_<version>_checksums.txt. The release binaries have the Zitadel
ids shelf-mcp login signs in with (the shelf-mcp client, the Shelf project
and the Shelf organization) stamped in by .goreleaser.yaml, so login needs
no flags or env:
# latest release; pick darwin_arm64, darwin_amd64, linux_arm64 or linux_amd64
gh release download --repo PJ-SLF-998231/api --pattern 'shelf-mcp_*_darwin_arm64.tar.gz' --output - \
| tar -xz -C ~/.local/bin shelf-mcp
shelf-mcp --version
claude mcp add shelf -- ~/.local/bin/shelf-mcp
claude mcp list # shelf should show Connected
To build it yourself instead, stamp the ids (they are ids, not secrets;
Infisical shelf prod /zitadel mcp-client-id and project-id, or
fly.mcp.toml MCP_OIDC_CLIENT_ID, OIDC_PROJECT_ID and
MCP_OIDC_ORG_ID), or set SHELF_OIDC_CLIENT_ID, SHELF_OIDC_PROJECT_ID
and SHELF_OIDC_ORG_ID when you run login:
go build -o ~/.local/bin/shelf-mcp \
-ldflags "-X main.defaultOIDCClientID=<shelf-mcp client id> -X main.defaultOIDCProjectID=<Shelf project id> -X main.defaultOIDCOrgID=<Shelf org id>" \
./cmd/mcp
By default the server talks to the local docker compose stack at
http://localhost:18080. To use another api, pass its base URL (without
/api/v1) when registering:
claude mcp add shelf -e SHELF_API_URL=https://api.example.com -- ~/.local/bin/shelf-mcp
Keep tokens out of the MCP config. Use shelf-mcp login, or a token file.
Log in (stdio)
shelf-mcp login # browser sign-in at auth.tri2b.cloud
shelf-mcp login --device # no browser on this machine
shelf-mcp logout # revoke at Zitadel and forget the login
Without stamped ids (see Install), pass
--client-id and --project-id or set SHELF_OIDC_CLIENT_ID and
SHELF_OIDC_PROJECT_ID; otherwise login stops with "no client id".
Login reads the issuer's discovery document and signs you in to Zitadel as
the public native app shelf-mcp (no client secret) with scopes
openid profile email offline_access urn:zitadel:iam:org:project:id:<project id>:aud:
offline_access gets a refresh token, the last scope puts the Shelf project
into the access token's aud, which is what the api checks. With an org id
(--org-id, SHELF_OIDC_ORG_ID or -X main.defaultOIDCOrgID) it also asks
for urn:zitadel:iam:org:id:<org id>, so Zitadel shows the Shelf
organization's login. It supports two flows:
- Authorization code + PKCE (S256), the default. It opens the Shelf
sign-in page in a browser, which redirects back to
http://127.0.0.1:8765/callback. Use--portto change the port, and--no-browserto print the URL instead of opening it. - Device authorization (
--device), for a machine without a browser. You confirm a short code on any other device.
What login receives is written to ~/.config/shelf-mcp/credentials.json
($XDG_CONFIG_HOME/shelf-mcp/credentials.json when that is set): a 0600 file
in a 0700 directory, replaced atomically. The file records the issuer,
client, project and token endpoint the token was issued for, so the server
needs no OIDC settings of its own. The server hands out the stored access token while it
has more than two minutes left. After that it redeems the refresh token and
saves the rotated one. A lock file makes sure two Claude Code sessions never
redeem the same refresh token. Nothing needs restarting. If whoami
reports that the refresh failed, run shelf-mcp login again.
logout revokes the refresh token at the issuer's revocation_endpoint
(best effort, so it also works offline) and deletes the file.
| Flag | Env | Default |
|---|---|---|
--issuer | SHELF_OIDC_ISSUER | https://auth.tri2b.cloud |
--client-id | SHELF_OIDC_CLIENT_ID | the build's -X main.defaultOIDCClientID; none in an unstamped build |
--project-id | SHELF_OIDC_PROJECT_ID | the build's -X main.defaultOIDCProjectID; none in an unstamped build |
--org-id | SHELF_OIDC_ORG_ID | the build's -X main.defaultOIDCOrgID; optional, none sends no org scope |
--device | off (PKCE loopback) | |
--port | 8765 | |
--no-browser | off |
Other token sources
The stdio server looks for a token in this order and uses the first one it finds:
- the
SHELF_TOKENenvironment variable; - the file named by
--token-fileorSHELF_TOKEN_FILE; - the stored
shelf-mcp login; ~/.config/shelf/token($XDG_CONFIG_HOME/shelf/tokenwhen that is set).
whoami reports the source in use as token_source.
A token file must hold a Zitadel access token (JWT) whose aud holds the
Shelf project id; an ID token does not work. The file is re-read on every call, so replacing
it takes effect without a restart, but nothing refreshes it for you:
mkdir -p ~/.config/shelf && chmod 700 ~/.config/shelf
printf '%s' "$ACCESS_TOKEN" > ~/.config/shelf/token && chmod 600 ~/.config/shelf/token
A token is a credential. Never paste one into a chat, a document, a commit or a tool argument.
To give an agent less than full access, use the hosted endpoint: its OAuth sign-in has a consent step where the person picks the connection's permissions, and the tools are then limited to those scopes (see Scopes and agent-scopes.md).
Server flags (stdio)
| Flag | Env | Default | Meaning |
|---|---|---|---|
--api-url | SHELF_API_URL | http://localhost:18080 | The api's base URL, without /api/v1 |
--token-file | SHELF_TOKEN_FILE | ~/.config/shelf/token | A file holding an access token |
SHELF_TOKEN | An access token; used before the file |
Tools
Fifty-five tools on the hosted server (fifty-four over stdio, which has no create_upload_url): guide, whoami, fifteen read tools, the three
evidence tools, eighteen write tools (plus create_upload_url, hosted only), the two
read-only changeset tools
(preview_changes, get_changeset; apply_changes is a write), the
three filing tools and the eleven
parser candidate tools.
This is the exact set that tools/list returns to a full-access caller
with every flag on and the tests pin (wantTools in cmd/mcp/main_test.go,
wantWriteTools in cmd/mcp/write_tools_test.go, wantParserWriteTools
in cmd/mcp/parser_tools_test.go). Which human workflows they cover, and which
stay with the person, is in the inventory.
mcp-tools.md is the contract view: every tool's scope, side
effects and reversibility, and what the 2026-10-05 contract audit changed.
The surface is a contract. cmd/mcp/testdata/tool_surface.golden.json
pins every tool exactly as tools/list publishes it, and
TestToolSurfaceSnapshot fails on any change to a name, description or
schema until the golden file is regenerated (go test ./cmd/mcp -run
TestToolSurfaceSnapshot -update) and the diff reviewed. A renamed tool keeps
its old name as a deprecated alias for one release (deprecatedAliases:
callable, not listed). TestToolSelectionByDescription checks that the
descriptions alone pick the right tool for search, move, upload, reparse,
share, filing (classify and file documents), gathering evidence, totalling a
field, finding exceptions, and writing, testing and rolling out a parser.
Arguments are checked against the schema first. Every input schema is
strict (additionalProperties: false; ids carry a UUID pattern, or
UUID-or-"root"; counts are integers; enums, bounds and lengths are in the
schema), and every call is validated against it (cmd/mcp/schema.go)
before the plan check and before any request to the api. A refused call
sends nothing and is an invalid_input error starting invalid arguments,
nothing was sent:, with field naming the first argument at fault.
Guide and identity
| Tool | Route | Notes |
|---|---|---|
guide | none | Embedded playbooks (cmd/mcp/guides/*.md): topics onboarding (the default) and documents; pass "topics" to list them. Needs no credential and makes no api call. |
whoami | GET /auth/me, GET /api/v1/credential | Who the tools act as (sub), the api URL, where the token came from and when it expires, and full_access or the connection's scopes. If /auth/me is unavailable (503 when cookie sign-in is off), it probes GET /api/v1/shelves and reads sub/exp from the token. An MCP connection access token (the OAuth proxy's) skips /auth/me, which knows only the person's own sign-in, and is checked by GET /api/v1/credential alone. |
Read (readOnlyHint: true)
| Tool | Route | Notes |
|---|---|---|
list_shelves | GET /api/v1/shelves | With document and folder counts. |
get_shelf | GET /api/v1/shelves/{id} | |
list_folders | GET /api/v1/shelves/{id}/folders | Flat list with parent_id and a computed path ("Receipts / 2026": names joined by " / ", the same separator as list_filing_destinations; for reading, pass folder_id back), and the api's item_count (documents directly in the folder) and total_item_count (in it and every folder below it; trashed documents don't count). |
list_documents | GET /api/v1/files or GET /api/v1/shelves/{id}/files | folder_id (a UUID, or "root" for documents in no folder) is filtered client-side. excerpt adds the first ~600 characters of text. Each row has content_sha256 and a processing summary (status, result, next_action, error_code). |
get_document | GET /api/v1/files/{id} | Metadata, parse result, labels, content_sha256, the full processing state (api#148) and text_chars, but never the text. include_download_url adds a signed download URL, which is a credential. |
get_document_text | GET /api/v1/files/{id} | The text, sliced by offset/limit in characters; returns total_chars and next_offset. |
get_document_site | GET /api/v1/files/{id}/site | The document's site as the api has it (status, stale, error_code, spec: blocks with per-fact source page/line), plus a hint when it isn't ready and current. Read only: it never builds a site (README "Document sites"). |
search | GET /api/v1/search | q, mode (fuzzy/exact), category, label, parser, page, per_page. If the server has no search index (503), it says so plainly and suggests browsing instead. |
list_share_links | GET /api/v1/files/{id}/shares | Status and dates, opens and downloads counts, plus token_hint only. Share tokens are credentials and are never returned, even if the api sends one. |
list_parsers | GET /api/v1/parsers | |
get_parser | GET /api/v1/parsers/{id} | Including its YAML spec. |
get_processing_status | GET /api/v1/files/{id}/processing | One document's processing state as the api has it: status, result, next_action, error (stable code, retryable), each stage, and the history of its readings. What to poll after an upload or a reparse. |
get_processing_statuses | GET /api/v1/files/processing | Many at once: document_ids (up to 200, in order; unknown ids in missing) or the newest (limit, up to 500; truncated), narrowed by status (queued, running, succeeded, failed). |
list_deleted | GET /api/v1/files/deleted, GET /api/v1/folders/deleted, GET /api/v1/shelves/deleted (api#152) | The trash, most recently deleted first: documents, folders and shelves, each paged with offset/limit and each item with deleted_at, purge_at, deletion_id, deleted_with (the folder or shelf whose delete took it) and restore (the tool that brings it back). kind narrows to one; for documents the folder and shelf lists are still read, best effort, to fill deleted_with. Never a download URL. |
get_activity | GET /api/v1/audit (api#155) | The person's activity log, newest first: every change made through the api, each with action (file.update, shelf.delete, …), outcome (success, denied, failed, replayed, pending), resource_type/resource_id, changes (each edited field's from and to) and actor (the credential: session, bearer with its client_id, mcp_connection with its id, name and scopes, or, on older events, a retired agent_key the same way). The api's filters pass through as arguments: action, outcome, resource_type, resource_id, actor_kind, actor_id, client_id, request_id, since and until (RFC 3339). The api pages the log itself, so the tool takes limit (1-200, default 50) and cursor and answers next_cursor, not offset/next_offset. A bad outcome, actor_kind, time or limit is refused as invalid_input before anything is sent; a cursor the api didn't give comes back as the api's invalid_input with field: cursor. |
list_parsers, get_parser and the parser candidate tools
(Writing parsers) are behind the parsers PostHog feature
flag, evaluated for the caller's sub and failing closed (no
POSTHOG_KEY, an anonymous caller or PostHog unreachable means off). With
it off they are left out of tools/list, a call to them answers as an
unknown tool, search has no parser parameter, and no tool description
or guide mentions parsers; webhook mentions in the guides likewise need the
webhooks flag. Flagged guide text sits between <!-- if <flag> --> and
<!-- end <flag> --> lines (cmd/mcp/guides.go).
With the flag on, parsers are visible, as they are in the web app: the
document tools report the parser that read a document, and the
documents guide explains them, and how to write one with the candidate
tools below. Importing a parser file, the studio's drafts, re-reading
every document a parser reads, deleting a parser and reviewing a document
stay in the web app (see Not tools).
The guide tells an agent what to say about a document that needs review:
the person reviews it on the document's page, which names and links the
parser that read it (/parsers#parser-<id>). Accepting saves the parser's
next revision, or a new parser when the result fails the checks of a
parser that has already read documents (the api's saved_as_new,
api#122). Reviewing is on every plan; only an AI rewrite costs credits
(10). The guide also says how a parser claims a document since api#121:
two of its identifying words, not counting generic words or the person's
common ones, and one of its labelled fields when it has any.
list_shelves, list_folders, list_documents and list_parsers page
client-side with offset/limit and return total and next_offset,
because those routes return whole lists.
Plan
MCP access will be a Premium plugin (coming soon; today it is gated by the plan's mcp feature), whatever the caller's billing flag says: before a
tool call (every tool but guide), the server reads the caller's
GET /api/v1/plan (api#124) with their own bearer and refuses the call with a
plan_limit error and the upgrade URL when features lacks "mcp". So an account
without mcp is refused and one with it is allowed, including a complimentary
plan (a plan grant, "complimentary": true), with the billing flag on
or off. The answer is kept for a minute per token. /plan answers 404 only
from an api run without billing, which has no plan limits, and MCP is then
allowed. tools/list, initialize and server/discover are never gated (cmd/mcp/flags.go,
planGate).
Write (readOnlyHint: false)
| Tool | Route | Notes |
|---|---|---|
create_shelf | POST /api/v1/shelves | Names are unique per person. On a 409 the error names the existing shelf's id, so retrying is safe. Keyed (see Retries). |
rename_shelf | PATCH /api/v1/shelves/{id} | |
delete_shelf | DELETE /api/v1/shelves/{id}; dry run POST /api/v1/changesets | Destructive; needs confirm: true. Moves the shelf, its folders and documents to the trash (Trash). |
create_folder | POST /api/v1/shelves/{id}/folders | Optional parent_id. On a 409 the error names the existing folder's id. Keyed. |
rename_folder | PATCH /api/v1/folders/{id} | |
move_folder | PATCH /api/v1/folders/{id} | parent_id is a folder on the same shelf, or "root". Folders cannot move between shelves. |
delete_folder | GET /api/v1/shelves/{id}/folders, DELETE /api/v1/folders/{id}; dry run POST /api/v1/changesets | Destructive; needs confirm: true. The folder must be on the given shelf_id. Moves it, its subfolders and their documents to the trash. |
rename_document | PATCH /api/v1/files/{id} | Changes the name Shelf shows (filename). |
move_document | PATCH /api/v1/files/{id} | folder_id (or "root"), and/or shelf_id to move it to another shelf. |
reparse_document | POST /api/v1/files/{id}/parse | Reads the document again in the background and answers with the api's 202 body, the new reading's processing state (status queued); poll get_processing_status. It replaces a hand-corrected text. Keyed. For many documents, a reparse changeset (Changesets). |
upload_document | POST /api/v1/files (multipart) | See Upload. Keyed. |
create_upload_url | POST /api/v1/files (multipart), when the PUT arrives | Hosted server only. See Upload. |
delete_document | DELETE /api/v1/files/{id}; dry run POST /api/v1/changesets | Destructive; needs confirm: true. Moves it to the trash; its share links stop working until it is restored. |
restore_document | POST /api/v1/files/{id}/restore | Back from the trash into its folder (or the shelf's top level if that folder is gone). A 409 when its shelf is in the trash. Keyed. |
restore_folder | POST /api/v1/folders/{id}/restore | Back with what was deleted with it, under its parent (or at the top level). Keyed. |
restore_shelf | POST /api/v1/shelves/{id}/restore | Back with what was deleted with it. Keyed. |
create_share_link | POST /api/v1/files/{id}/shares | Optional title, and expires_at (RFC 3339) or expires_in_days. Answers with the link (id, token_hint, status, dates) and its url (https://app.shelf.tri2b.cloud/s/<token>), a credential shown only in this answer. The api's 20-active-links limit comes back as a conflict. Keyed. |
revoke_share_link | DELETE /api/v1/files/{id}/shares/{shareId}, then GET /api/v1/files/{id}/shares | Stops the link at once (destructiveHint: true; no confirm, since it only takes access away). Answers with the link as it now is, revoked. |
apply_changes | POST /api/v1/changesets/{id}/apply | Makes a previewed changeset once (destructiveHint: true: it may delete). See Changesets. Keyed by the changeset. |
Results. Every write answers with what it changed as it now is (the
shelf, folder, document summary with processing, or share link) and its
id, so an agent checks a change without another call; the read tools read it
back too. TestAgentWorkflowAgainstTheRealAPI runs search, inspect, mutate
and verify this way against the real api.
Deletes. The three delete tools carry destructiveHint: true. They
delete only when confirm is the JSON boolean true. With confirm absent
or false, they send no DELETE and return a dry run instead ("true", 1
or any other non-boolean is refused by the schema as invalid_input, and
nothing is sent):
the name, how many documents and folders would go (with example names), and
a document's active share links. The dry run is a one-item changeset
(POST /api/v1/changesets with file.delete, folder.delete or
shelf.delete), worked out by the same checks as the delete itself, and
carries its changeset_id and expires_at. Show the dry run to the person
and, only once they agree, either apply_changes with the changeset_id
(deletes exactly what was shown, and nothing if it changed meanwhile) or
call again with confirm: true. Something missing, in the trash or not the
person's is a not_found error saying nothing was deleted.
Changesets (bulk organisation)
Organising many documents takes two calls, not one per document: preview,
then apply (changeset_tools.go, over the api's changesets, README
"Previewing changes (changesets)").
| Tool | Route | Notes |
|---|---|---|
preview_changes | POST /api/v1/changesets | operation (file.update, file.delete, folder.delete, shelf.delete, reparse) and items, at most 500. A file.update item is {id, filename?, shelf_id?, folder_id?} (folder_id "root" or null for the shelf's top level), each item its own destination, so one changeset files a mixed batch to many places; a delete or reparse item is {id}. Changes nothing in the person's Shelf (readOnlyHint: true). Answers changeset_id, status previewed, expires_at (an hour), atomic: false, summary (items by status) and the items, paged (offset, limit). |
apply_changes | POST /api/v1/changesets/{id}/apply | Applies it once. Sends Idempotency-Key: changeset-apply-<id> unless idempotency_key is given. |
get_changeset | GET /api/v1/changesets/{id} | Reads it back: status, summary, results. status narrows the items to one preview status or result (failed, not_found, ...); paged. |
- Items. Each has its
indexin the request,id,status, andbefore,afterandchanges(with shelf and folder names) or, when it won't be changed,codeandreason. Statuses:ready,unchanged,not_found(missing, in the trash, or another person's: never told apart),invalidandconflict(the same item twice, or inside a folder being deleted). Fingerprints are dropped from the answer. - Bulk reparse.
reparsereads many documents again, asreparse_documentreads one (api#175). An item isready,unchangedwith codenot_ready(already queued, not queued twice),invalidwithunprocessable(Shelf doesn't read it) orplan_limit(over the plan's limits, checked once for the batch), ornot_found. Applying queues each ready document once, recorded asfile.reprocess; watch them withget_processing_statuses. Previewing the same items again finds themunchanged, so nothing is queued twice. - Checked before sending. The operation, at most 500 items, each
id(andshelf_id,folder_id) a UUID, only the fields the operation takes, and afile.updateitem changing something; anything else is aninvalid_inputerror and no request is sent. - Every item authorised on its own. The api plans each item with the
check its single-item route uses, as the caller: an item of someone
else's is
not_foundand skipped, never assumed from another item. - Apply is per item, not all-or-nothing. If any item changed since the
preview, nothing is changed:
apply_changesfails withconflict, "stale, nothing was changed", naming each changed item (item 4 (<id>): previewed ready, now not_found), and the changeset can't be applied any more: preview again. Otherwise each ready item is applied in order and has aresult:applied,skipped(it wasn't ready),stale(changed at the last moment; left alone) orfailed(with a code). The changeset'sstatusisapplied(every ready item),partialorfailed(none): never plain success when an item failed. - Retries. A changeset applies once.
apply_changeskeys the call by the changeset, so a retried call (after a timeout, say) is answered with the first one's results, markedreplayed. If the api kept no answer to replay (an answer over 1 MB, or another key), the api's 409 for a changeset already applied is turned into the same:get_changeset's results, markedreplayed. One still being applied is a retryableconflictpointing atget_changeset. - Scopes. The scope of the change:
documents:writeforfile.updateandreparse,documents:deleteforfile.delete,shelves:deletefor folder and shelf deletes, to preview, read and apply alike. The three tools are listed for a connection holding any one of these (toolSpec.anyScope); the api refuses an operation whose scope the connection lacks withinsufficient_scopeandrequired_scope. - Audit. The preview is
changeset.previewand the applychangeset.applyinget_activity; each applied item is its own row (file.update,file.delete, ...) with the samerequest_id.
TestBulkOrganisationAgainstTheRealAPI (cmd/mcp/changeset_workflow_test.go)
files a mixed batch of 500 against the real api: one preview, one apply,
a retry that changes nothing, a stale changeset refused whole, and a
folder delete applied from its dry run; TestBulkReparseAgainstTheRealAPI
previews and applies a reparse changeset, retries it, and previews it
again.
Evidence across documents
Questions about many documents at once ("what did we pay Acme last year?",
"which invoices have no due date?") are answered with what Shelf holds about
each document, every value tied to the document it came from
(evidence_tools.go, over the api's GET /api/v1/evidence, api#166, README
"Evidence across documents"). Shelf writes no answer: the agent reasons from
the evidence and cites document ids. All three tools are read-only and need
documents:read.
| Tool | Route | Notes |
|---|---|---|
gather_evidence | GET /api/v1/evidence | The matching documents, limit (1-100, default 25) a page, cursor/next_cursor to page. Each has its reading, parser, fields (value, raw, where it was read, confidence, reviewed), missing_fields, the fragments of text with q's words (page and line; fragments 0-20, default 5), labels and, with rows, table rows. Every value has its document_id and origin (parser, document_text, vision_model). aggregate (up to 5 fields) adds totals over every match. |
summarise_field | GET /api/v1/evidence (aggregate=<fields>, limit=0) | fields (1-5, required). Answers total, counts by reading, and per field: with_value, without_value (the documents with none), from_unreviewed, numbers (exact sum, min, max with their documents), dates (earliest, latest, months covered and missing) and the most common values. No documents. |
find_exceptions | GET /api/v1/evidence (missing=, else reading=unread,failed; fragments=0) | The documents missing every field in missing, or, with none named, the unread and failed ones (reading overrides). unreadable lists unread and failed documents a field filter couldn't look at. |
- Filters (all three):
q(every word in the text, up to 10 words),shelf_idsandfolder_ids(UUIDs, at most 20 each; a folder includes its subfolders),parser,parser_id,label,reading(parsed,needs_review,text_only,unread,failed),uploaded_fromanduploaded_to(YYYY-MM-DD),where("Total>=800","Supplier~acme"; at most 10 withmissing) andreviewed_only. - Partial answers.
partialandpartial_reasons(more_pages,unread_documents,failed_documents,unreadable_documents,unreviewed_values,fragments_truncated,rows_truncated,aggregate_capped) say when an answer isn't everything; the descriptions tell the agent to say so. - Owner scoping. The api limits every query, totals included, to the
caller's live documents; another person's shelf or folder is
not_found. - Parsers off.
parserandparser_idare dropped and the descriptions speak of "the fields Shelf read".
Writing parsers with an agent
An agent writes a parser from example documents, tests it, revises it and
rolls it out (parser_tools.go, over the api's candidate routes, api#168).
Nothing reads a document with a candidate until it is activated, testing
changes no document, and activating reads none: only apply_parser does.
All eleven are behind the parsers flag.
| Tool | Route | Scope | Notes |
|---|---|---|---|
get_parser_schema | GET /api/v1/parsers/schema | parsers:read | The file format, its limits and an example per way of reading. |
validate_parser | POST /api/v1/parsers/validate | parsers:read | spec (1 to 262144 characters). valid, the parser as read, and diagnostics (severity, code, line, path, message). Saves nothing. |
list_parser_candidates | GET /api/v1/parsers/candidates | parsers:read | The latest 100, newest first, summarised (no spec or per-document results; warnings is a count, last_test the latest summary). Paged client-side (offset, limit). |
get_parser_candidate | GET /api/v1/parsers/candidates/{id} | parsers:read | candidate_id. The candidate as the api has it, with its latest test. |
create_parser_candidate | POST /api/v1/parsers/candidates | parsers:write | spec, parser_id (revise that parser, at its current revision), idempotency_key. A new parser will be a Premium plugin, coming soon (402 until then). A 422 comes back as an unprocessable tool error listing every diagnostic with its line and path. Answers the candidate plus next. |
revise_parser_candidate | PUT /api/v1/parsers/candidates/{id} | parsers:write | candidate_id, spec: the next version, untested. 422 as above; 409 once activated. |
discard_parser_candidate | DELETE /api/v1/parsers/candidates/{id} | parsers:write | Permanent (no trash); a parser it made stays. No confirm: a candidate reads nothing. |
test_parser_candidate | POST /api/v1/parsers/candidates/{id}/test | parsers:write | document_ids (1-50) sent as file_ids. Per document source: candidate result, current, diff, would_match, outcome, error_code for those it can't read; summary and field coverage. Not keyed (the api exempts it); a repeat tests again. next follows the summary. |
activate_parser_candidate | POST /api/v1/parsers/candidates/{id}/activate | parsers:write | version (activate only that version), idempotency_key. 409 when untested, at another version, activated already, or the parser moved past base_revision. Answers candidate, parser and next (apply it). |
apply_parser | POST /api/v1/parsers/{id}/apply | parsers:execute | parser_id, document_ids (1-100) as file_ids, idempotency_key. Synchronous; each document changed, unchanged, skipped (not_found, wrong_kind, not_read, hand_edited, changed_meanwhile) or failed. Applying again is unchanged. destructiveHint: true: the reading it replaces is not kept. |
list_parser_revisions | GET /api/v1/parsers/{id}/revisions | parsers:read | Newest first, each with its spec, current and candidate_id. Paged client-side. |
TestParserCandidatesAgainstTheRealAPI
(cmd/mcp/parser_workflow_test.go) runs them against the real api with
the flag on: an invalid spec saves nothing; a test changes no document and
reports another person's document as not_found and an unread one as
not_read; another person reaches none of the candidate's tools; an
untested or other version can't be activated; activation reads nothing;
apply_parser changes exactly the owned, readable documents and a re-apply
is unchanged; a candidate written against an old revision is a 409; agent
keys with parsers:read, parsers:write or parsers:execute are offered
and allowed exactly their tools; and with the flag off the tools are absent
and a call to one is an unknown tool.
Filing (classify and file documents)
The agent classifies, the person approves, Shelf moves (filing_tools.go,
over /api/v1/filing, api#167, README "Filing documents"). Shelf runs no
model here and charges no credits.
| Tool | Route | Scope | Notes |
|---|---|---|---|
list_filing_candidates | GET /api/v1/filing/candidates | documents:read | The documents to file, oldest first: by default the unfiled ones (a shelf's top level); shelf_id, folder_id or any_folder (not both). Each with a text excerpt (text_chars 0-8000, default 1000), the parser and its fields, labels, processing state, identical copies elsewhere and hints (where documents read by the same parser were filed). Shelf and folder names and paths only with shelves:read. limit 1-200 (default 50); after = the previous next_after. |
list_filing_destinations | GET /api/v1/filing/destinations | shelves:read | Every shelf's top level and folder by path, with files and the parsers that read most of them. Paged client-side (offset, limit). |
plan_filing | POST /api/v1/filing/plan | documents:write | decisions (1-500): {document_id, folder_id?, shelf_id?, confidence?, uncertain?, category?, reason?}; min_confidence 0.5-1 (default 0.8); the source the documents came from (source_shelf_id, source_folder_id, source_any_folder; by default the unfiled ones). Answers changeset_id (null when nothing would move), summary and categories, each decision's outcome (file, uncertain, already_filed, out_of_scope, not_found, destination_not_found, invalid_destination, processing, duplicate, conflict) with its reason, and the changeset's status, summary and expires_at. Nothing moves: readOnlyHint: true, like preview_changes. |
Apply a plan with apply_changes and its changeset_id (it is a
file.update changeset, so documents:write); get_changeset reads its
items. Every item is checked again on apply, as for any changeset. A
decision about another person's document is not_found, and one naming
their folder destination_not_found; the plan's category and reason
go to the activity log only, never onto the document.
TestEvidenceAndFilingAgainstTheRealAPI
(cmd/mcp/evidence_filing_workflow_test.go) runs the six against the real
api with two people: evidence, totals and exceptions hold only the
caller's documents; a plan files only the confident, owned decisions, and
the other person can't apply it; and MCP connections with shelves:read,
documents:read or documents:read + documents:write are offered and
allowed exactly the tools their scopes cover.
Trash
Since api#152 a delete moves to the trash rather than removing anything.
Each delete tool's description says so: "moves to the trash, restorable for
30 days; a folder or shelf takes its contents"; its dry run's next says the
same, and its answer has a trash line naming the restore tool. A folder or
shelf goes with everything in it under one deletion_id, and restoring it
brings back exactly that; what was deleted on its own before stays in the
trash. list_deleted shows the trash and, for each item, which restore
brings it back (restore, deleted_with).
The restore tools are POSTs and send an Idempotency-Key, as the api asks:
a retry whose first try went through is answered with that outcome
(replayed) rather than a 404. A restore that is refused says "nothing was
restored": a 404 (not in the trash: never deleted, restored already, purged,
or not the caller's) points at list_deleted; a 409 (the shelf is in the
trash, or a name is taken now) keeps the api's reason; a 402 keeps
plan_limit, since a restore counts toward the plan as an upload does.
No purge tool. POST /{files,folders,shelves}/{id}/purge removes for good
and needs full access; shelf-mcp's own login is full access, so a tool would
let an agent purge with no scope in the way. The api purges the trash 30 days
after a delete; purging sooner stays in the web app. TestNoToolPurges pins
that.
Conflicts. A rename or move that hits a 409 says "conflict, nothing was changed" and gives the api's reason.
Upload
upload_document checks the size and type before sending anything, using
the web app's list of accepted types: JPEG, PNG, WebP and GIF images, PDF,
Word (.docx, .doc), Excel (.xlsx, .xls), and UTF-8 .txt, .md and
.json (text files are recognised by their extension). Other files are
identified from their bytes, the same way the api identifies them.
| Mode | Accepted input | Limit |
|---|---|---|
| stdio | path (a regular local file), source_url or content_base64 + filename | 25 MB for path (the api's limit); 5 MB decoded for base64 |
| HTTP | source_url (preferred) or content_base64 + filename; path is not in the schema and is refused | 25 MB for source_url; 5 MB decoded for base64 |
source_url is an https link the server downloads itself, so the bytes never
pass through the model (a model pasting a large image as base64 can corrupt it
silently). It is fetched with no proxy, and every connection, including each
of at most three redirects, is refused if it goes to a loopback, private,
link-local (cloud metadata), CGNAT or multicast address, or leaves https. The
file name comes from the URL path unless filename is given.
expected_sha256 (64 hex characters, shasum -a 256 file) works with every
source: if the received bytes do not hash to it, the call fails with both
hashes and nothing is stored, so a corrupted transfer is loud and a retry is
safe.
The hosted server cannot read files on your computer, and it will not read
files on its own disk, which is why path exists in stdio mode only.
create_upload_url (hosted server only, scope documents:upload) is for a
file the caller can reach from a shell but the model should not carry. It
takes filename (required), optionally expected_sha256, shelf_id,
folder_id, client_ref and on_duplicate, and answers with a single-use
URL below the MCP URL, <MCP_RESOURCE_URL>/upload/<token>, valid for 15
minutes and held in the server's memory only. The caller sends the raw bytes:
curl -X PUT --data-binary @file "<url>"
The PUT takes up to 25 MB at the MCP; the hosted URL is also subject to the
landing proxy's request-size limit, which is smaller today (see the landing
README). The hash can come from expected_sha256 or an X-Content-SHA256
header. Answers: 201 with the same result as upload_document; 413 for a
file over the size limit; 422 for a type that is not accepted or bytes that
do not hash to the expected value (nothing is stored and the URL stays usable,
so a refused PUT can be sent again); 404 for a URL that is unknown,
expired or already used. Once a file is stored the URL is spent: a second
PUT is 404 and a new URL is needed.
Optional arguments: shelf_id (the default shelf when omitted), folder_id,
client_ref (a UUID naming the upload, so a retry returns it),
idempotency_key, and on_duplicate.
Duplicates (api#139). When the person already has a document with
exactly these bytes, on any shelf, the api stores nothing and answers 200
with that document. upload_document then answers duplicate: true with
the existing document and an existing line naming its id, name, shelf and
folder. on_duplicate: "keep_both" stores a second copy instead (it sends
the api's on_duplicate form field); return_existing is the default.
Documents carry content_sha256 in get_document, list_documents and
the upload's answer, so identical files can be grouped.
Retries and idempotency keys
The tools that POST (create_shelf, create_folder, upload_document,
reparse_document, create_share_link, restore_document,
restore_folder, restore_shelf, apply_changes,
create_parser_candidate, activate_parser_candidate, apply_parser)
send an Idempotency-Key header
(api#147) with it. The key is the tool's
idempotency_key argument when given, or a fresh UUID for each tool call
(apply_changes: changeset-apply-<id>, the same for every call).
Within one call, a failure after which the api kept no outcome (the api
unreachable, a retryable 5xx, or 409 idempotency_key_in_use) is retried
up to three times in all with the same key and the same bytes, waiting the
api's Retry-After (at most 5 s). A replayed answer (Idempotent-Replayed:
true) is marked replayed in upload_document, reparse_document,
create_share_link, the restore tools and apply_changes, and said in
next by the three keyed parser tools.
preview_changes (and a delete's dry run) sends no key: a preview changes
nothing, and a repeat only makes another changeset; nor do
validate_parser and test_parser_candidate, which the api exempts.
A keyed call that still fails carries idempotency_key in its error, so the
agent can retry the tool call itself with that key and get the first call's
outcome, never a second copy. 422 idempotency_key_reused (the key with
other arguments: nothing ran) and 409 idempotency_key_in_use keep the
api's codes and get hints (errors.go); an in-use 409 is not mistaken for a
name conflict. PATCH and DELETE tools send no key: they set state, and the
api ignores the header on them.
Scopes
Each tool declares the capability scopes its requests need
(toolSpec.scopes, from internal/auth), and its description ends with
them ("If this connection's permissions are limited, it needs the
documents:write scope."). For each caller, tools/list reads
GET /api/v1/credential (api#141; remembered for a minute per token) and
leaves out the tools needing a scope the credential lacks. A full-access
credential, an api without /credential, or one that fails to answer sees
every tool. Hiding is a convenience, not a boundary: the api checks every
request's scope, and a call to a hidden tool gets its insufficient_scope
error.
| Scope | Tools |
|---|---|
| none | guide, whoami |
shelves:read | list_shelves, get_shelf, list_folders, list_filing_destinations |
shelves:write | create_shelf, rename_shelf, create_folder, rename_folder, move_folder |
shelves:delete | delete_shelf |
shelves:read + shelves:delete | delete_folder (it reads the shelf's folders) |
shelves:delete | restore_shelf, restore_folder |
documents:read | list_documents, get_document, get_document_text, get_document_site, search, get_processing_status, get_processing_statuses, gather_evidence, summarise_field, find_exceptions, list_filing_candidates (place names only with shelves:read) |
documents:upload | upload_document, create_upload_url (hosted only) |
documents:write | rename_document, move_document, reparse_document, plan_filing |
documents:delete | delete_document, restore_document |
one of documents:write, documents:delete, shelves:delete | preview_changes, apply_changes, get_changeset (the api checks the one the operation needs) |
documents:read + shelves:read | list_deleted |
shares:read | list_share_links |
shares:write | create_share_link, revoke_share_link |
parsers:read | list_parsers, get_parser, get_parser_schema, validate_parser, list_parser_candidates, get_parser_candidate, list_parser_revisions (and the parsers flag, as for every parser tool) |
parsers:write | create_parser_candidate, revise_parser_candidate, discard_parser_candidate, test_parser_candidate, activate_parser_candidate |
parsers:execute | apply_parser |
audit:read | get_activity |
Deliberately not tools (yet)
- Webhooks: there are no tools to create, rotate or test them (and none to read them: they stay off). A webhook's signing secret is a credential, and delivering to an arbitrary URL is an outward side effect.
- Overwriting a document's text (
PATCH /api/v1/files/{id}withcontent): no tool does this. A test asserts that both of these are absent. - Purging the trash: see Trash.
- Other parser changes: parsers are written, tested, activated and
rolled out through candidates (above),
but there are no tools to import a parser file, use the studio's drafts,
edit a parser in place, re-read every document a parser reads, review a
document or delete a parser. Reviewing is done on the document's page in
the web app, where the person sees what Shelf read.
TestParserToolsAnnotationsFlagsAndScopes(cmd/mcp/parser_tools_test.go) pins the parser tool set.
Workflow inventory
Every human workflow in Shelf's web app, the api route behind it, and the MCP tool that does it, or why it stays with the person. Business logic stays in the api: each tool is one or a few of the routes the apps call, with the caller's own bearer, so the api's authorisation, owner scoping, scopes, plan limits and idempotency apply unchanged. No tool has a route or privilege of its own.
| Workflow | API | MCP tool |
|---|---|---|
| See who I am and what this credential may do | GET /auth/me, GET /credential | whoami |
| Find documents, folders and shelves by word | GET /search | search |
| Browse shelves | GET /shelves, GET /shelves/{id} | list_shelves, get_shelf |
| Browse a shelf's folders | GET /shelves/{id}/folders | list_folders |
| List documents (all, a shelf's, a folder's) | GET /files, GET /shelves/{id}/files | list_documents |
| Read a document's details, labels and parser result | GET /files/{id} | get_document |
| Read a document's text | GET /files/{id} | get_document_text |
| Open or download the original file | GET /files/{id} (download_url) | get_document with include_download_url (a credential) |
| See where processing is, and why it failed | GET /files/{id}/processing, GET /files/processing | get_processing_status, get_processing_statuses |
| Upload a document | POST /files | upload_document (duplicates, on_duplicate, keyed) |
| Upload a file the model should not carry (hosted) | POST /files | create_upload_url, then a PUT of the bytes |
| Process a document again | POST /files/{id}/parse | reparse_document |
| Create, rename, delete a shelf | POST/PATCH/DELETE /shelves[/{id}] | create_shelf, rename_shelf, delete_shelf |
| Create, rename, move, delete a folder | POST /shelves/{id}/folders, PATCH/DELETE /folders/{id} | create_folder, rename_folder, move_folder, delete_folder |
| Rename a document; move it to a folder or shelf | PATCH /files/{id} | rename_document, move_document |
| Delete a document | DELETE /files/{id} | delete_document |
| Move, rename or delete many at once, previewed first | POST /changesets, POST /changesets/{id}/apply, GET /changesets/{id} | preview_changes, apply_changes, get_changeset |
| Answer a question across many documents, with the evidence | GET /evidence | gather_evidence |
| Total or summarise a field across documents | GET /evidence (aggregate) | summarise_field |
| Find documents missing a field, unread or failed | GET /evidence (missing, reading) | find_exceptions |
| Classify and file documents into folders, approved first | GET /filing/candidates, GET /filing/destinations, POST /filing/plan, POST /changesets/{id}/apply | list_filing_candidates, list_filing_destinations, plan_filing, apply_changes |
| See the trash | GET /files/deleted, GET /folders/deleted, GET /shelves/deleted | list_deleted |
| Restore a document, folder or shelf from the trash | POST /{files,folders,shelves}/{id}/restore | restore_document, restore_folder, restore_shelf (keyed) |
| See a document's share links | GET /files/{id}/shares | list_share_links |
| Share a document by link; stop sharing | POST /files/{id}/shares, DELETE /files/{id}/shares/{shareId} | create_share_link, revoke_share_link |
| See parsers | GET /parsers, GET /parsers/{id} | list_parsers, get_parser (behind the parsers flag) |
| Write a parser from examples, test it, activate it | GET /parsers/schema, POST /parsers/validate, /parsers/candidates… | get_parser_schema, validate_parser, create_parser_candidate, revise_parser_candidate, test_parser_candidate, activate_parser_candidate, list_parser_candidates, get_parser_candidate, discard_parser_candidate (behind the parsers flag) |
| Roll a parser out to chosen documents | POST /parsers/{id}/apply | apply_parser (keyed) |
| See a parser's earlier revisions | GET /parsers/{id}/revisions | list_parser_revisions |
| See what was changed, when, and by which credential | GET /audit | get_activity |
Human-only, on purpose:
| Workflow | API | Why it stays with the person |
|---|---|---|
| Correct a document's text or HTML | PATCH /files/{id} (content, content_html) | Overwrites what Shelf read; deferred by the human (2026-09-30). |
| Review a document Shelf wasn't sure of | POST /files/{id}/review… | The person checks what Shelf read against the page, on the document's page. |
| Import, draft in the studio, edit in place, delete or re-read parsers | POST /parsers/import, /parsers/drafts…, PUT/DELETE /parsers/{id}, POST /parsers/{id}/reread | Candidates are the agent's way to make and change a parser, tested before anything reads with it; re-reading every document a parser reads stays with the person. |
| Webhooks | /webhooks/… | Off: secrets are credentials, and delivery is an outward side effect. |
| Purge from the trash now | POST /{files,folders,shelves}/{id}/purge | Can't be undone, and full access only; the api purges after 30 days anyway. |
| Bulk download links | POST /downloads | A link that downloads many files is a credential with a wide reach; get_document gives one file's. |
| Links shared with me | /shared-with-me/…, GET /shares/by-token/{token} | The person's own record of links opened in their browser. |
| MCP connections, billing, plan | /mcp-connections/…, /billing/… | full_access only: no connection can make or widen a connection, or spend money. |
Missing in the api for a core workflow (listed, not built here):
- Move a folder to another shelf.
PATCH /folders/{id}takes ashelf_idnow, butmove_folderdoesn't expose it yet.
Tool errors
A failed call is an MCP tool error (isError: true), never a JSON-RPC
error, with two halves (cmd/mcp/errors.go):
- Text, for the model: starts with
error:, keeps the wording it always had, and ends with a line such as[code: rate_limited; retryable: true; retry_after_seconds: 7]for a client that shows only text. structuredContent, for the agent's code to branch on:
{"code": "not_found", "message": "GET /api/v1/shelves/…: 404 not found",
"retryable": false, "http_status": 404,
"hint": "Check the id with a list_ or search tool; …"}
| Field | Meaning |
|---|---|
code | The api's stable code (README, "Errors"), or one below for failures before the api answered |
retryable | Whether the same call may succeed later |
retry_after_seconds, max_retries | Only when retryable: wait this long, double it each time, at most max_retries (3) tries |
http_status | The api's status; absent when the api never answered |
field | The argument at fault, when the api named one or the tool's schema refused it |
resource_id | The caller's existing resource the error is about: create_shelf/create_folder name the clashing shelf/folder |
idempotency_key | The key a failed keyed write was sent with; retry with it |
hint | A safe next step |
The code is the api's own code when the body has one; for a body that
predates it, error when that is itself a code (plan_limit,
plan_unavailable, not_reviewable, …); otherwise it follows from the
status (apiutil.CodeForStatus). Retry-After is honoured. So a client
can always tell apart:
| Situation | code | Retryable |
|---|---|---|
| Bad argument, checked before sending | invalid_input | no |
| No token, or the token was rejected | unauthenticated | no: call guide |
| The plan lacks MCP (the gate) or the feature | plan_limit | no |
| Not allowed with this credential | forbidden | no |
The connection lacks a scope (required_scope names it) | insufficient_scope | no |
An idempotency_key reused with other arguments; nothing ran | idempotency_key_reused | no: use a new key |
| The first call with this key is still running | idempotency_key_in_use | yes, with the same key |
| Missing, or someone else's | not_found | no |
| Duplicate name, count limit | conflict | no |
| Still being prepared (draft, re-read, search index) | not_ready | yes |
| Too many requests | rate_limited | yes, after Retry-After |
| The api failed, or a service behind it | internal, upstream_failed | yes |
| The api is unreachable or down | unavailable | yes |
| The server doesn't run the feature (search) | not_configured | no |
| The api's answer couldn't be decoded (a version mismatch) | internal | no |
The plan gate's refusal keeps its old fields (error: "plan_limit",
reason, feature, plan, upgrade_url) and adds code, message,
retryable, http_status and hint. Fields are only added, and codes are
only added; analytics' error_class still reads the text prefixes.
TestToolErrorsCarryStableCodes and TestToolErrorsBeforeTheAPI
(cmd/mcp/errors_test.go) pin the codes.
Hosted HTTP endpoint
shelf-mcp --http :8080
This serves MCP streamable HTTP, shaped like projects-mcp's hosted endpoint:
| Route | Auth | Answer |
|---|---|---|
POST/GET/DELETE /mcp | bearer | MCP. With no bearer or an invalid one: 401 + WWW-Authenticate: Bearer realm="shelf", resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp" (plus error="invalid_token" when a token was rejected). |
GET /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-protected-resource | none | RFC 9728 metadata: resource, authorization_servers, scopes_supported, bearer_methods_supported. |
GET /healthz | none | ok |
GET /version | none | The build's version (-X main.version, Dockerfile.mcp's VERSION), JSON {"version","commit"}; dev and unknown when unstamped |
The bearer is verified with the api's own verifier
(internal/auth.NewIssuerVerifier: OIDC discovery and JWKS of OIDC_ISSUER,
the issuer exactly, and OIDC_PROJECT_ID in aud), or, for an MCP
connection's token (internal/mcpconn), by asking the api (GET
/api/v1/credential; connectionGate, believed for 30 s). That token, and only that token, is
forwarded to the api for the request. SHELF_TOKEN, token files and
shelf-mcp login are never read in HTTP mode, and tokens are never logged.
Hardening: security headers (nosniff, DENY, no-referrer, CSP). When
X-Forwarded-Proto says plain http, credentials are refused with 403; a
comma-separated or repeated header is checked hop by hop, and any hop that
is not https refuses. A
body over 8 MiB on /mcp gets 413. The header read timeout is 10 s and
there is no write timeout, so SSE streams are not cut off.
| Setting | Default | Meaning |
|---|---|---|
--http | (stdio) | Listen address |
SHELF_API_URL | (required with --http) | The api's base URL, without /api/v1 |
MCP_RESOURCE_URL | https://shelf.tri2b.cloud/mcp | Public URL of /mcp; the metadata path and URL are derived from it |
OIDC_ISSUER | https://auth.tri2b.cloud | Token issuer, exactly as its discovery document states it (no trailing slash); the same as the api's |
OIDC_PROJECT_ID | (required) | The Zitadel project id of Shelf; bearers must carry it in aud. The same as the api's |
MCP_AUTHORIZATION_SERVERS | OIDC_ISSUER (or the MCP origin when the proxy is on) | Comma-separated override for the metadata's authorization_servers |
MCP_ALLOW_INSECURE_CREDENTIALS | 1 accepts a bearer behind a proxy that forwards plain http | |
MCP_SSE_HEARTBEAT | 30s | How often an open GET /mcp SSE stream gets a JSON-RPC ping, as a Go duration (30s, 1m), so proxies don't close it as idle (Cloudflare, in front of shelf.tri2b.cloud, drops a response silent for about 100 s). Only legacy clients (MCP revisions before 2026-07-28, which initialize and open the session's GET /mcp stream) get it; 2026-07-28 has no GET /mcp stream (405), so a modern client is never pinged. 0 sends none; a negative or unparsable value stops the server at startup |
Protocol: the SDK (mark3labs/mcp-go v1.1.1) serves both protocol eras on
/mcp, decided per request from the version the request declares:
- Legacy (2024-11-05 to 2025-11-25):
initialize, thenMcp-Session-Idon every request, and an optionalGET /mcpSSE stream thatMCP_SSE_HEARTBEATkeeps alive. - 2026-07-28 (stateless): no
initializeand no session. Every request carries_meta["io.modelcontextprotocol/protocolVersion"]and the matchingMcp-Protocol-VersionandMcp-Methodheaders (Mcp-Nametoo ontools/call).server/discoveranswerssupportedVersions(2026-07-28 down to 2024-11-05),capabilities(tools), the instructions and_meta["io.modelcontextprotocol/serverInfo"]{name: "shelf", version}.GETandDELETE /mcpare405.
server/discover is an ordinary MCP request: without a valid bearer it is
401 with the same resource_metadata challenge as any other, and like
tools/list and initialize it is never plan-gated. Clients that predate
2026-07-28 never send it and keep working through initialize.
Behind the landing proxy
https://shelf.tri2b.cloud is the landing app. Its nginx proxies the MCP
paths to the Fly app at https://tri2b-shelf-mcp.fly.dev:
/mcpand/mcp/*(the uploadPUTURLs live there)/.well-known/oauth-protected-resourceand/.well-known/oauth-protected-resource/mcp/.well-known/oauth-authorization-serverand/.well-known/openid-configuration/oauth/
It sends X-Forwarded-Proto: https and X-Forwarded-Host: shelf.tri2b.cloud.
Every URL the MCP advertises (resource, authorization_servers, the
WWW-Authenticate resource_metadata, the authorization-server metadata,
and the redirect_uri it sends to Zitadel) comes from MCP_RESOURCE_URL and
MCP_OAUTH_PROXY_ISSUER in fly.mcp.toml. It never comes from Host or
X-Forwarded-Host, so a forged header cannot change them. For the plain-http guard above the
request header that matters is X-Forwarded-Proto. For the /oauth/register
limit, X-Real-IP is believed as the client only when the request also
carries X-Shelf-Proxy-Secret equal to TRUSTED_PROXY_SECRET (and
CF-Connecting-IP only from Cloudflare's ranges).
https://tri2b-shelf-mcp.fly.dev/mcp also answers, and it advertises the
same shelf.tri2b.cloud URLs.
Connector sign-in (OAuth proxy)
claude.ai and ChatGPT connectors sign in by themselves. They read the
protected-resource metadata, register a client with Dynamic Client
Registration (DCR), and then run authorization code + PKCE. Zitadel
publishes no registration endpoint, and every connector's callback URL
would have to be allowlisted. So, as projects-mcp does, with
MCP_OAUTH_PROXY=1 the MCP acts as the authorization server and signs
everyone in through one pre-registered Zitadel native app, shelf-mcp. The
upstream authorization and token endpoints come from OIDC_ISSUER's
discovery document, read at startup:
| Route | Answer |
|---|---|
GET /.well-known/oauth-authorization-server (and /.well-known/openid-configuration) | RFC 8414 metadata: issuer, /oauth/authorize, /oauth/token, /oauth/register, S256, auth methods none, client_secret_post, client_secret_basic |
POST /oauth/register | DCR. Redirect URIs are limited to https://claude.ai/api/mcp/auth_callback, https://claude.com/api/mcp/auth_callback, https://chatgpt.com/connector_platform_oauth_redirect, https://chatgpt.com/connector/oauth/<id>, or an RFC 8252 loopback callback for native clients such as Claude Code (http://127.0.0.1:<port>/<path>, http://[::1]:<port>/<path> or http://localhost:<port>/<path>); for a loopback callback only the port may differ at /oauth/authorize (RFC 8252 §7.3). Rate limited to 10/min per address and 120/min overall (sliding windows, shared by every MCP instance through REDIS_URL when set). |
GET /oauth/authorize | Checks the client and a registered redirect_uri and requires S256 PKCE. Then redirects to Zitadel's authorization_endpoint (/oauth/v2/authorize) as MCP_OIDC_CLIENT_ID, with redirect_uri=<issuer>/oauth/callback and the connector's scopes plus offline_access and urn:zitadel:iam:org:project:id:<OIDC_PROJECT_ID>:aud, and urn:zitadel:iam:org:id:<MCP_OIDC_ORG_ID> when that is set. |
GET /oauth/callback | Zitadel redirects here. The proxy redeems Zitadel's code itself, with its own PKCE verifier, and shows Shelf's consent page: the client's name, the host it is sent back to, the connection's name (prefilled with the client's), the presets Read only, Organiser, Uploader and All permissions, a checkbox per capability scope with what it allows, and Allow / Cancel. |
POST /oauth/consent | The consent form. Allow creates an MCP connection through the api with the person's Zitadel token, then redirects to the connector's callback with its own state and a proxy code. Cancel redirects there with error=access_denied. |
POST /oauth/token | authorization_code: the client, redirect_uri and PKCE verifier are checked, and each code works once. The answer is a connection access token the api mints for the connection (one hour), with only the scopes the person allowed, and a sealed refresh token. refresh_token refreshes the person's sign-in at Zitadel (without a scope, keeping the project audience) and has the api mint a new token; once the person disconnects the connection it is invalid_grant, and the connector has to connect again. |
Nothing is stored. Client ids (with the registered client name), the state
sent through Zitadel, the consent form, the codes and the refresh tokens
handed back are sealed with AES-GCM under MCP_OAUTH_PROXY_KEY, and the
client_secret_* secrets are HMAC-derived from the client id and checked.
The key must therefore stay the same across restarts; rotating it makes
every connector sign in again. With the proxy on, authorization_servers in
the protected-resource metadata is the MCP's own origin. A connector never
holds a Zitadel token: it gets a connection access token, which acts as the
person narrowed to the scopes they allowed, and the activity log names the
connection (actor_kind mcp_connection). The person sees and disconnects
their connections in Shelf's web app, under Settings → MCP connections.
The consent form is bound to the browser that signed in (a __Host- cookie
and a CSRF token derived from it), refused from another origin, and
answered once. It offers only the person's own scopes, less those of
features not yet on for them, and accepts no others: a connection can only
narrow what the person may do.
| Setting | Default | Meaning |
|---|---|---|
MCP_OAUTH_PROXY | 1 turns the proxy on | |
MCP_OIDC_CLIENT_ID | (required) | Client id of the Zitadel native app shelf-mcp |
MCP_OIDC_ORG_ID | (unset) | The Zitadel organization id of Shelf. Set, sign-in asks for urn:zitadel:iam:org:id:<id>, so Zitadel shows that organization's login; unset, no org scope is sent |
MCP_OAUTH_PROXY_KEY | (required) | At least 32 bytes, raw or base64 (openssl rand -base64 32); a Fly secret |
MCP_OAUTH_PROXY_ISSUER | origin of MCP_RESOURCE_URL | The proxy's issuer; must be https |
TRUSTED_PROXY_SECRET | (unset) | Optional. The landing nginx's PROXY_SECRET. The landing sends it in X-Shelf-Proxy-Secret beside X-Real-IP; only then is X-Real-IP believed as the client for the /oauth/register limit. Unset, every client behind the landing counts as the landing's own address and shares one bucket |
REDIS_URL | (unset) | Optional. Counts the /oauth/register limits in Redis, and remembers which consents and codes were used, shared by every instance; unset or unreachable, each process keeps its own. A malformed value stops the MCP; the URL is never logged |
Install it in claude.ai, Claude Desktop, Claude Code or ChatGPT with the server URL
https://shelf.tri2b.cloud/mcp (mcp-guides.md
has the steps for each client). If creating the connector
fails, check that:
GET https://shelf.tri2b.cloud/.well-known/oauth-protected-resource/mcphasresourcehttps://shelf.tri2b.cloud/mcpand listshttps://shelf.tri2b.cloudinauthorization_servers;GET https://shelf.tri2b.cloud/.well-known/oauth-authorization-serverlists/oauth/register,/oauth/authorize,/oauth/token,S256and the three auth methods;- the Zitadel app shelf-mcp has the redirect URI
https://shelf.tri2b.cloud/oauth/callback; - after signing in,
whoamianswers with yoursub.
Zitadel app shelf-mcp
shelf-mcp login and the OAuth proxy share one app in the Zitadel project
Shelf (org Shelf, issuer https://auth.tri2b.cloud), created by
deploy/zitadel/setup.sh:
- type native, auth method none (a public client using PKCE);
- redirect URIs:
https://shelf.tri2b.cloud/oauth/callback(the proxy) andhttp://127.0.0.1:8765/callback(login; a native app also accepts another loopback port, for--port); - grant types Authorization Code, Refresh Token and Device Code
(for
login --device); - JWT access tokens, which the api and the MCP verify against the JWKS.
Its client id goes to MCP_OIDC_CLIENT_ID on the hosted server and to
shelf-mcp login (-X main.defaultOIDCClientID, --client-id or
SHELF_OIDC_CLIENT_ID); the project id to OIDC_PROJECT_ID and
-X main.defaultOIDCProjectID / --project-id / SHELF_OIDC_PROJECT_ID; the
org id to MCP_OIDC_ORG_ID and -X main.defaultOIDCOrgID / --org-id /
SHELF_OIDC_ORG_ID.
guide: onboarding without a shell
An agent connected over MCP may have no terminal and no copy of this repo.
The guide tool reads embedded markdown and makes no network call, so it
still works when the credential is the problem, which is when it is needed.
{"name": "guide", "arguments": {}} // onboarding: check, sign in, register
{"name": "guide", "arguments": {"topic": "topics"}} // list the topics
{"name": "guide", "arguments": {"topic": "documents"}} // finding and reading documents
A tool that fails with "not signed in" or "token rejected" points at
guide. A local server is fixed by shelf-mcp login (or a new token file)
on that machine. A hosted server gets its bearer from the MCP client's own
OAuth sign-in.
Related
- mcp-guides.md: client setup and end-to-end agent
workflows, checked against the tool surface (
TestGuidesMatchTheToolSurface) - README: MCP server: a short summary with a link here
- README: API: the REST routes the tools call
- ADR 0009: why the MCP server is a REST client that forwards the caller's identity
- nebula/projects
docs/mcp.md: theprojects-mcpdesign this follows
MCP tool inventory (shelf-mcp)
Every tool shelf-mcp publishes, what a limited MCP connection needs to call it, what
it changes, and how to undo it, with what the contract audit of 2026-10-05
changed. mcp.md has each tool's route and behaviour in full; this
page is the contract view.
mcp-guides.md shows the tools in use: client setup and
five end-to-end workflows, whose tool calls TestGuidesMatchTheToolSurface
checks against this surface.
The published surface is pinned: cmd/mcp/testdata/tool_surface.golden.json
is every tool exactly as tools/list sends it (name, annotations,
description, input schema), plus its scopes, feature flag, parsers-off
description and the hosted server's upload_document and create_upload_url.
TestToolSurfaceSnapshot fails on any change to it. A deliberate change is
recorded with
go test ./cmd/mcp -run TestToolSurfaceSnapshot -update
reviewed in the golden file's diff, and reflected here
(TestInventoryDocumentListsEveryTool checks every tool has a row).
Inventory
55 tools (54 over stdio, which has no create_upload_url), the set a full-access caller with every flag on sees. Scope is
what an MCP connection whose permissions the person limited needs
(tools/list hides a tool whose scope the connection lacks); a signed-in person's token has full access. "any of" means the
changeset tools need the scope of the change they carry. Side effects
are on the person's Shelf. Every tool but guide is refused until the Premium
plugin for MCP access, coming soon, is available to the account.
| Tool | Scope | Side effects | Reversibility |
|---|---|---|---|
guide | none | None; reads embedded playbooks, no api call. | n/a |
whoami | none | None. | n/a |
list_shelves | shelves:read | None. | n/a |
get_shelf | shelves:read | None. | n/a |
list_folders | shelves:read | None. | n/a |
list_documents | documents:read | None. | n/a |
get_document | documents:read | None. include_download_url mints a short-lived signed URL, a credential. | The URL expires on its own. |
get_document_text | documents:read | None. | n/a |
get_document_site | documents:read | None; reads the document's site, builds nothing and costs nothing. | n/a |
search | documents:read | None. | n/a |
list_share_links | shares:read | None. Tokens are never returned, only token_hint. | n/a |
list_parsers | parsers:read (flag parsers) | None. | n/a |
get_parser | parsers:read (flag parsers) | None. | n/a |
get_parser_schema | parsers:read (flag parsers) | None. | n/a |
validate_parser | parsers:read (flag parsers) | None; checks a spec, saves nothing. | n/a |
list_parser_candidates | parsers:read (flag parsers) | None. | n/a |
get_parser_candidate | parsers:read (flag parsers) | None. | n/a |
list_parser_revisions | parsers:read (flag parsers) | None. | n/a |
create_parser_candidate | parsers:write (flag parsers) | Stores a candidate; reads no document. A new parser will be a Premium plugin, coming soon. | discard_parser_candidate. Keyed by idempotency_key. |
revise_parser_candidate | parsers:write (flag parsers) | Replaces the candidate's spec as its next version, untested. | revise_parser_candidate with the old spec (another version). |
discard_parser_candidate | parsers:write (flag parsers) | Deletes the candidate and its tests; a parser it made stays. | Not reversible: submit the spec again. |
test_parser_candidate | parsers:write (flag parsers) | Keeps the test on the candidate; no document changes. | n/a (the next test replaces it). |
activate_parser_candidate | parsers:write (flag parsers) | Makes a parser, or the parser's next revision; reads no document. | A candidate with the earlier spec (list_parser_revisions) and parser_id, activated. Keyed. |
apply_parser | parsers:execute (flag parsers) | Reads the chosen documents with the parser and stores what it reads, replacing their reading; hand-edited ones are skipped. | Not undoable: the replaced reading is not kept; apply another parser or reparse_document. Keyed; a re-apply is unchanged. |
get_processing_status | documents:read | None. | n/a |
get_processing_statuses | documents:read | None. | n/a |
gather_evidence | documents:read | None. | n/a |
summarise_field | documents:read | None. | n/a |
find_exceptions | documents:read | None. | n/a |
create_shelf | shelves:write | Creates a shelf. | delete_shelf (to the trash). A retry with the same idempotency_key, or the same name, creates nothing new. |
rename_shelf | shelves:write | Renames a shelf. | rename_shelf back. |
delete_shelf | shelves:delete | Without confirm: true: none, a dry run (a one-item changeset). With it: the shelf, its folders and documents go to the trash. | restore_shelf within 30 days; purged after. |
create_folder | shelves:write | Creates a folder. | delete_folder (to the trash). Keyed like create_shelf. |
rename_folder | shelves:write | Renames a folder. | rename_folder back. |
move_folder | shelves:write | Moves a folder and everything in it within its shelf. | move_folder back to the old parent_id. |
delete_folder | shelves:read and shelves:delete | Like delete_shelf, for a folder, its subfolders and their documents. | restore_folder within 30 days. |
rename_document | documents:write | Renames a document (the name Shelf shows). | rename_document back. |
move_document | documents:write | Moves one document to another folder, its shelf's top level or another shelf. | move_document back. |
reparse_document | documents:write | Queues a new reading of one document in the background; a running one is superseded. Replaces a hand-corrected text with what Shelf reads. (Many documents: a reparse changeset.) | Not undoable: a hand-corrected text is lost. Otherwise the new reading simply replaces the old. |
upload_document | documents:upload | Stores a new document (or, for bytes the person already has, nothing: duplicate: true) and queues its reading. | delete_document. Keyed by idempotency_key or client_ref. |
create_upload_url | documents:upload | Hosted server only. Records an upload and answers with a single-use PUT URL (valid 15 minutes) below the MCP URL: the caller sends the raw bytes there with curl, so a big or easily corrupted file never passes through the model. The PUT checks size, type and the expected_sha256 (or an X-Content-SHA256 header), stores nothing on a mismatch (the URL stays usable), and answers like upload_document. Pending URLs live in the server's memory. The PUT takes up to 25 MB, the hosted URL at shelf.tri2b.cloud included (the landing proxy allows a little more on /mcp/upload/, landing#48, so the MCP's own 25 MB limit is the one that answers). | delete_document. A PUT refused for its bytes can be sent again; once a file is stored the URL is spent, a second PUT is 404, and a new URL is needed. |
delete_document | documents:delete | Like delete_shelf, for one document; its share links stop working while it is deleted. | restore_document within 30 days; the links work again. |
list_deleted | documents:read and shelves:read | None. | n/a |
restore_document | documents:delete | Brings a document back from the trash. | delete_document. |
restore_folder | shelves:delete | Brings a folder back with what was deleted with it. | delete_folder. |
restore_shelf | shelves:delete | Brings a shelf back with what was deleted with it. | delete_shelf. |
preview_changes | any of documents:write, documents:delete, shelves:delete | None to the person's documents; stores the previewed changeset, which expires after an hour. | Expires on its own. |
apply_changes | any of documents:write, documents:delete, shelves:delete | Applies a previewed changeset once, item by item (not all-or-nothing): moves, renames, deletes to the trash, or reparses (each ready document queued to be read again, once). | Moves and renames: another changeset back. Deletes: the restore tools within 30 days. Reparses: not undoable, as reparse_document. |
get_changeset | any of documents:write, documents:delete, shelves:delete | None. | n/a |
list_filing_candidates | documents:read (shelf and folder names only with shelves:read) | None. | n/a |
list_filing_destinations | shelves:read | None. | n/a |
plan_filing | documents:write | None to the person's documents; stores a previewed file.update changeset of the confident moves, which expires after an hour. Category and reason go to the activity log only. | Expires on its own. Once applied with apply_changes: another changeset (or move_document) back. |
create_share_link | shares:write | Creates a public link: anyone with the url can open, read and download the document without signing in. | revoke_share_link (at once, for everyone). Whoever already downloaded the document keeps the copy. |
revoke_share_link | shares:write | Stops a link for good. | Not reversible: create a new link (a new url). |
get_activity | audit:read | None. | n/a |
Before and after the audit
The audit (2026-10-05) changed no tool's name and no required parameter: the same 36 tools, called the same way. It changed what a tool tells an agent and what it refuses.
Descriptions
Each description's first sentence now says what the tool does in words no
other tool's first sentence shares, so the description alone picks the
right tool. TestToolSelectionByDescription checks it for search, move,
upload, reparse and share intents (with every flag on, with parsers off,
and for the hosted upload_document): each intent's words must be in the
first sentence of exactly one tool.
| Tool | Before | After |
|---|---|---|
search | "Search the user's documents, folders and shelves: …" | Says it finds the documents that mention some words, and when to use it (a document described by what it is or says); notes that hits carry ids and that page/per_page page through them. |
list_documents | "(identical files share it)" read as sharing; folder_id said nothing about subfolders | "identical files have the same one"; folder_id says subfolders are not included; points to search for finding by content; says how to page. |
move_document | "Move a document …" | "Move one document …"; says to pass folder_id, shelf_id or both, that nothing else changes, to use preview_changes for many, and that it answers with the document. |
reparse_document | "Process a document again …" | "Reparse (reprocess) one document …": the words an agent asks with ("one" since the bulk reparse, below). |
upload_document | "Upload a document to Shelf: …" | "Upload a file to Shelf as a new document: …". |
create_share_link | "Create a public share link to one document …" | "Share a document through a public link …": the person's word, share. |
list_share_links | "List a document's share links …" | "List the public links made to a document …"; says it is not paged (at most 20 active). |
revoke_share_link | "Revoke one of a document's share links …" | "Revoke one of a document's public links …". |
delete_document | "delete a document; its share links stop working …" | "delete a document, moving it to the trash. While it is deleted, its public links stop working." |
restore_document | "… its text, what Shelf read from it, the person's edits and its share links." | "… with its text, what Shelf read from it and the person's edits; its public links work again." |
get_processing_status | "Get where one document is in Shelf's processing, after an upload or reparse_document: …" | "Get one document's processing state: …"; when to use it moves to a later sentence. |
get_processing_statuses | "… in one call, to watch a batch of uploads or reparses: …" | "… in one call: …"; the batch use moves to the last sentence. |
get_activity | "Read the person's activity log: every change (uploads, edits, moves, …)" | "Read the person's activity log, the record of who changed what in their Shelf, newest first." The list of changes follows. |
The ambiguity the old first sentences had: get_activity named uploads,
moves and share links; get_processing_status(es), uploads; and
list_documents, delete_document and restore_document, sharing. An
agent matching on them could pick a reader for a write.
Schemas
| Change | Tools | Before | After |
|---|---|---|---|
| Unknown arguments refused | all | ignored (additionalProperties unset) | additionalProperties: false: a typo or another tool's parameter is an invalid_input error naming the arguments the tool takes |
| Id parameters checked | every *_id, client_ref, document_ids, preview_changes items | type: string, checked by the handler (after the plan check) | pattern: a UUID; "root" too where the shelf's top level is meant (list_documents/move_document folder_id, create_folder/move_folder parent_id, preview_changes items' folder_id). "ROOT" and padded or braced UUIDs, accepted before, are refused. The activity filters (resource_id, actor_id, …) pass any id to the api, as before. |
| Counts are integers | offset, limit, page, per_page, expires_in_days | type: number (2.5 was truncated) | type: integer |
| Lengths | search.q; name of the create and rename tools; create_share_link.title; idempotency_key; preview_changes items[].filename | checked by the handler or the api | q 1-200 characters, names and filenames at least 1, title at most 100, idempotency_key printable ASCII up to 255 |
| Array bounds | preview_changes.items, get_processing_statuses.document_ids | at most 500 / 200, checked by the handler | minItems: 1 / maxItems in the schema |
confirm must be a boolean | delete_shelf, delete_folder, delete_document | "true" or 1 gave a dry run | refused as invalid_input; nothing is deleted either way |
Validation before anything is sent
Every call is checked against the tool's published schema (cmd/mcp/schema.go)
before the plan check and before any request to the api: a refused call
sends nothing. The error is invalid_input, its text starts
invalid arguments, nothing was sent: and names each fault
(items[0].folder_id must be a UUID or "root", got "up"), and its
structured field is the first argument at fault.
TestSchemaValidationRejectsBeforeAnyRequest derives invalid calls for
every tool from its schema (an unknown argument, each required argument
missing, each argument of the wrong type, each id not a UUID), adds
hand-picked enum, bound and length cases, and runs them through a client
whose transport records every request, with the plan gate and scope cache
on: zero requests.
The handlers keep their own checks for what a schema can't say (a blank
name, path or content_base64 but not both, expires_at or
expires_in_days but not both).
Deprecated aliases
A renamed tool keeps its old name for one release (deprecatedAliases in
cmd/mcp/tools.go): a call to the old name runs the new tool, its
description starts DEPRECATED:, and tools/list leaves it out. The
snapshot test refuses a tool that disappears without one.
| Old name | Now | Removed in |
|---|---|---|
| (none) |
The audit renamed nothing: the names already describe their domain action,
and the near-pairs (get_processing_status and get_processing_statuses,
list_deleted and the restore tools) differ in behaviour their descriptions
spell out.
Evidence and filing (2026-10-05)
Six tools added after the audit, over the api's evidence (api#166) and filing (api#167) routes, with the same strict schemas, validated before anything is sent. No existing tool changed.
| Tool | Route | What it is for |
|---|---|---|
gather_evidence | GET /api/v1/evidence | A question across many documents: each matching document's fields (where each was read), the lines of text with q's words (page and line), labels and, with rows, table rows; every value carries its document_id and origin (parser, document_text, vision_model). aggregate adds totals. Paged by cursor. |
summarise_field | GET /api/v1/evidence with aggregate= and limit=0 | Totals only, over every matching document: per field (1-5), count, exact sum, min and max, date coverage and missing months, the most common values, and which documents have no value. |
find_exceptions | GET /api/v1/evidence with missing=, or reading=unread,failed when no field is named | The documents missing a field, or not read yet or failed; unreadable lists the unread ones a field filter couldn't look at. fragments=0. |
list_filing_candidates | GET /api/v1/filing/candidates | The documents to classify and file (by default the unfiled ones) with what Shelf read of each: excerpt, parser and fields, labels, processing, duplicates and hints. Paged by after. |
list_filing_destinations | GET /api/v1/filing/destinations | Every shelf and folder by path, with what is in it. The api answers the whole list; the tool pages it (offset, limit). |
plan_filing | POST /api/v1/filing/plan | The agent's decisions (document_id, destination, confidence, category, reason), at most 500. The confident ones become a previewed changeset; every other is left where it is with an outcome and a reason. Applied with the existing apply_changes. |
Schema notes: the evidence tools take shelf_ids and folder_ids as
arrays of UUIDs (at most 20 each), reading as an enum array,
uploaded_from/uploaded_to as YYYY-MM-DD (refused otherwise, must be
a date as YYYY-MM-DD), and where/missing/fields/aggregate as
bounded string arrays. plan_filing's decisions are objects with
additionalProperties: false (a destination folder_id is a UUID, never
"root": a shelf alone is its top level), confidence from 0 to 1, and
min_confidence from 0.5 to 1: the only number parameters on the
surface, every count stays an integer. The decision's id is document_id,
as everywhere else in shelf-mcp; the api's file_id is what the plan's
items echo back.
Parsers off: gather_evidence, summarise_field and find_exceptions
drop parser and parser_id, and their and list_filing_candidates' and
list_filing_destinations' descriptions say "the fields Shelf read"
instead of naming parsers.
TestToolSelectionByDescription now also checks the filing intents
(classify documents, file documents into folders pick
list_filing_candidates, the entry point; propose where a document
belongs picks plan_filing) and the evidence intents (gather evidence
across documents picks gather_evidence; total across documents and
sum a field across documents pick summarise_field; documents missing
a field or unread picks find_exceptions).
TestEvidenceAndFilingAgainstTheRealAPI runs them against the real api:
answers and totals hold only the caller's documents, another person's
shelf is not_found, their document and folder are not_found and
destination_not_found in a plan, and an MCP connection without
documents:read, shelves:read or documents:write is neither offered
nor allowed the tools that need it.
Agent-assisted parsers (2026-10-05)
Eleven tools added over the api's parser candidate routes (api#168), all
behind the parsers flag (hidden from tools/list, and an unknown tool
when called, with it off; no parsers-off variants), with the same strict
schemas, validated before anything is sent. list_parsers and
get_parser changed only their descriptions: they no longer say no tool
makes a parser, and point to create_parser_candidate and
list_parser_revisions. The documents guide's Parsers section now walks
through the workflow.
| Tool | Route | What it is for |
|---|---|---|
get_parser_schema | GET /api/v1/parsers/schema | The parser file format to write a spec in. |
validate_parser | POST /api/v1/parsers/validate | Check a spec without saving: valid, the parser, diagnostics. |
list_parser_candidates | GET /api/v1/parsers/candidates | The person's candidates, summarised; paged client-side. |
get_parser_candidate | GET /api/v1/parsers/candidates/{id} | One candidate in full, with its latest test. |
create_parser_candidate | POST /api/v1/parsers/candidates | Write a new parser from example documents (or, with parser_id, a revision) as a candidate. A 422 lists every diagnostic with its line and path. |
revise_parser_candidate | PUT /api/v1/parsers/candidates/{id} | The candidate's next version, to be tested again. |
discard_parser_candidate | DELETE /api/v1/parsers/candidates/{id} | Discard a candidate. |
test_parser_candidate | POST /api/v1/parsers/candidates/{id}/test | Test against 1-50 documents: per document the candidate's result, the current one, the diff and would_match; failures and coverage. Changes no document. |
activate_parser_candidate | POST /api/v1/parsers/candidates/{id}/activate | Make the tested version a parser or revision; 409 when untested, another version, or the parser moved on. |
apply_parser | POST /api/v1/parsers/{id}/apply | Roll a parser out to 1-100 chosen documents, synchronously, with skip reasons. |
list_parser_revisions | GET /api/v1/parsers/{id}/revisions | A parser's history: each revision's spec and the candidate that made it. |
Naming follows this page's conventions: create_, get_, list_ as
elsewhere; revise_, test_, activate_, discard_ and apply_ are the
domain actions. The API's suggested parser_schema and
submit_parser_candidate became get_parser_schema and
create_parser_candidate. discard_parser_candidate is not delete_:
the delete_ tools move to a trash and take confirm, and a candidate
reads nothing, so it takes neither. Documents are document_ids (sent as
the api's file_ids), the candidate is candidate_id (a UUID pattern,
like every id), spec is 1 to 262144 characters, version is an integer
of at least 1, and test_parser_candidate/apply_parser bound
document_ids to 50 and 100. create_parser_candidate,
activate_parser_candidate and apply_parser send an Idempotency-Key;
validate_parser and test_parser_candidate don't (the api exempts them).
The write tools answer with next, what the agent does now (test,
activate with the version tested, apply).
TestToolSelectionByDescription now also checks the parser intents (write
a new parser from examples picks create_parser_candidate, test a parser
candidate test_parser_candidate, roll a parser out to documents
apply_parser, and validate, revise, activate, file format and
history their tools), and that with parsers off no description matches
them at all. TestParserCandidatesAgainstTheRealAPI runs the workflow
against the real api with the flag on (see mcp.md).
Bulk reparse (2026-10-06)
preview_changes takes a fifth operation, reparse (api#175): read many
documents again, as reparse_document reads one, previewed and applied as
any changeset. No tool was added.
- Items are
{id}only, at most 500; an item withfilename,shelf_idorfolder_idis refused before anything is sent (reparse takes only an id). Scope:documents:write, asreparse_document. - Preview. Each item is
ready, or says why not:unchangedwith codenot_ready(already queued; it isn't queued twice),invalidwithunprocessable(Shelf doesn't read that document) orplan_limit(the account is over its plan's limits, checked once for the whole batch), andnot_found.before/aftercarryparse_status. - Apply queues each ready document's reading once (an activity row
file.reprocesseach) and is idempotent: a retriedapply_changesis answered with the first one's results, and the same items previewed again areunchanged. Watch the readings withget_processing_statuses. - Descriptions.
preview_changes' first sentence adds "or a bulk reparse of many documents";reparse_document's now says "one document" and points topreview_changesfor many;apply_changessays reparsed items are queued.TestToolSelectionByDescriptiontells them apart:reparse one documentpicksreparse_document,reparse many documentspreview_changes.
TestBulkReparseAgainstTheRealAPI (cmd/mcp/changeset_workflow_test.go)
previews a reparse of two read documents, a queued one, an unreadable one
and a missing one against the real api, applies it, retries the apply and
previews it again: two readings queued, nothing queued twice.