Developers

MCP server (shelf-mcp)

From the api repo’s docs/mcp.md at 509805b and docs/mcp-tools.md

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 /mcp in Claude Code, pick shelf and 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 at https://shelf.tri2b.cloud/mcp through the landing proxy. shelf-mcp login and 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 "run shelf-mcp login again".

Two ways to run it

shelf-mcp is one binary with two transports:

TransportHow it's reachedUsed 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 --port to change the port, and --no-browser to 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.

FlagEnvDefault
--issuerSHELF_OIDC_ISSUERhttps://auth.tri2b.cloud
--client-idSHELF_OIDC_CLIENT_IDthe build's -X main.defaultOIDCClientID; none in an unstamped build
--project-idSHELF_OIDC_PROJECT_IDthe build's -X main.defaultOIDCProjectID; none in an unstamped build
--org-idSHELF_OIDC_ORG_IDthe build's -X main.defaultOIDCOrgID; optional, none sends no org scope
--deviceoff (PKCE loopback)
--port8765
--no-browseroff

Other token sources

The stdio server looks for a token in this order and uses the first one it finds:

  1. the SHELF_TOKEN environment variable;
  2. the file named by --token-file or SHELF_TOKEN_FILE;
  3. the stored shelf-mcp login;
  4. ~/.config/shelf/token ($XDG_CONFIG_HOME/shelf/token when 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)

FlagEnvDefaultMeaning
--api-urlSHELF_API_URLhttp://localhost:18080The api's base URL, without /api/v1
--token-fileSHELF_TOKEN_FILE~/.config/shelf/tokenA file holding an access token
SHELF_TOKENAn 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

ToolRouteNotes
guidenoneEmbedded playbooks (cmd/mcp/guides/*.md): topics onboarding (the default) and documents; pass "topics" to list them. Needs no credential and makes no api call.
whoamiGET /auth/me, GET /api/v1/credentialWho 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)

ToolRouteNotes
list_shelvesGET /api/v1/shelvesWith document and folder counts.
get_shelfGET /api/v1/shelves/{id}
list_foldersGET /api/v1/shelves/{id}/foldersFlat 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_documentsGET /api/v1/files or GET /api/v1/shelves/{id}/filesfolder_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_documentGET /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_textGET /api/v1/files/{id}The text, sliced by offset/limit in characters; returns total_chars and next_offset.
get_document_siteGET /api/v1/files/{id}/siteThe 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").
searchGET /api/v1/searchq, 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_linksGET /api/v1/files/{id}/sharesStatus 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_parsersGET /api/v1/parsers
get_parserGET /api/v1/parsers/{id}Including its YAML spec.
get_processing_statusGET /api/v1/files/{id}/processingOne 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_statusesGET /api/v1/files/processingMany 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_deletedGET /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_activityGET /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)

ToolRouteNotes
create_shelfPOST /api/v1/shelvesNames are unique per person. On a 409 the error names the existing shelf's id, so retrying is safe. Keyed (see Retries).
rename_shelfPATCH /api/v1/shelves/{id}
delete_shelfDELETE /api/v1/shelves/{id}; dry run POST /api/v1/changesetsDestructive; needs confirm: true. Moves the shelf, its folders and documents to the trash (Trash).
create_folderPOST /api/v1/shelves/{id}/foldersOptional parent_id. On a 409 the error names the existing folder's id. Keyed.
rename_folderPATCH /api/v1/folders/{id}
move_folderPATCH /api/v1/folders/{id}parent_id is a folder on the same shelf, or "root". Folders cannot move between shelves.
delete_folderGET /api/v1/shelves/{id}/folders, DELETE /api/v1/folders/{id}; dry run POST /api/v1/changesetsDestructive; needs confirm: true. The folder must be on the given shelf_id. Moves it, its subfolders and their documents to the trash.
rename_documentPATCH /api/v1/files/{id}Changes the name Shelf shows (filename).
move_documentPATCH /api/v1/files/{id}folder_id (or "root"), and/or shelf_id to move it to another shelf.
reparse_documentPOST /api/v1/files/{id}/parseReads 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_documentPOST /api/v1/files (multipart)See Upload. Keyed.
create_upload_urlPOST /api/v1/files (multipart), when the PUT arrivesHosted server only. See Upload.
delete_documentDELETE /api/v1/files/{id}; dry run POST /api/v1/changesetsDestructive; needs confirm: true. Moves it to the trash; its share links stop working until it is restored.
restore_documentPOST /api/v1/files/{id}/restoreBack 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_folderPOST /api/v1/folders/{id}/restoreBack with what was deleted with it, under its parent (or at the top level). Keyed.
restore_shelfPOST /api/v1/shelves/{id}/restoreBack with what was deleted with it. Keyed.
create_share_linkPOST /api/v1/files/{id}/sharesOptional 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_linkDELETE /api/v1/files/{id}/shares/{shareId}, then GET /api/v1/files/{id}/sharesStops the link at once (destructiveHint: true; no confirm, since it only takes access away). Answers with the link as it now is, revoked.
apply_changesPOST /api/v1/changesets/{id}/applyMakes 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)").

ToolRouteNotes
preview_changesPOST /api/v1/changesetsoperation (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_changesPOST /api/v1/changesets/{id}/applyApplies it once. Sends Idempotency-Key: changeset-apply-<id> unless idempotency_key is given.
get_changesetGET /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 index in the request, id, status, and before, after and changes (with shelf and folder names) or, when it won't be changed, code and reason. Statuses: ready, unchanged, not_found (missing, in the trash, or another person's: never told apart), invalid and conflict (the same item twice, or inside a folder being deleted). Fingerprints are dropped from the answer.
  • Bulk reparse. reparse reads many documents again, as reparse_document reads one (api#175). An item is ready, unchanged with code not_ready (already queued, not queued twice), invalid with unprocessable (Shelf doesn't read it) or plan_limit (over the plan's limits, checked once for the batch), or not_found. Applying queues each ready document once, recorded as file.reprocess; watch them with get_processing_statuses. Previewing the same items again finds them unchanged, so nothing is queued twice.
  • Checked before sending. The operation, at most 500 items, each id (and shelf_id, folder_id) a UUID, only the fields the operation takes, and a file.update item changing something; anything else is an invalid_input error 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_found and 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_changes fails with conflict, "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 a result: applied, skipped (it wasn't ready), stale (changed at the last moment; left alone) or failed (with a code). The changeset's status is applied (every ready item), partial or failed (none): never plain success when an item failed.
  • Retries. A changeset applies once. apply_changes keys the call by the changeset, so a retried call (after a timeout, say) is answered with the first one's results, marked replayed. 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, marked replayed. One still being applied is a retryable conflict pointing at get_changeset.
  • Scopes. The scope of the change: documents:write for file.update and reparse, documents:delete for file.delete, shelves:delete for 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 with insufficient_scope and required_scope.
  • Audit. The preview is changeset.preview and the apply changeset.apply in get_activity; each applied item is its own row (file.update, file.delete, ...) with the same request_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.

ToolRouteNotes
gather_evidenceGET /api/v1/evidenceThe 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_fieldGET /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_exceptionsGET /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_ids and folder_ids (UUIDs, at most 20 each; a folder includes its subfolders), parser, parser_id, label, reading (parsed, needs_review, text_only, unread, failed), uploaded_from and uploaded_to (YYYY-MM-DD), where ("Total>=800", "Supplier~acme"; at most 10 with missing) and reviewed_only.
  • Partial answers. partial and partial_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. parser and parser_id are 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.

ToolRouteScopeNotes
get_parser_schemaGET /api/v1/parsers/schemaparsers:readThe file format, its limits and an example per way of reading.
validate_parserPOST /api/v1/parsers/validateparsers:readspec (1 to 262144 characters). valid, the parser as read, and diagnostics (severity, code, line, path, message). Saves nothing.
list_parser_candidatesGET /api/v1/parsers/candidatesparsers:readThe 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_candidateGET /api/v1/parsers/candidates/{id}parsers:readcandidate_id. The candidate as the api has it, with its latest test.
create_parser_candidatePOST /api/v1/parsers/candidatesparsers:writespec, 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_candidatePUT /api/v1/parsers/candidates/{id}parsers:writecandidate_id, spec: the next version, untested. 422 as above; 409 once activated.
discard_parser_candidateDELETE /api/v1/parsers/candidates/{id}parsers:writePermanent (no trash); a parser it made stays. No confirm: a candidate reads nothing.
test_parser_candidatePOST /api/v1/parsers/candidates/{id}/testparsers:writedocument_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_candidatePOST /api/v1/parsers/candidates/{id}/activateparsers:writeversion (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_parserPOST /api/v1/parsers/{id}/applyparsers:executeparser_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_revisionsGET /api/v1/parsers/{id}/revisionsparsers:readNewest 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.

ToolRouteScopeNotes
list_filing_candidatesGET /api/v1/filing/candidatesdocuments:readThe 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_destinationsGET /api/v1/filing/destinationsshelves:readEvery shelf's top level and folder by path, with files and the parsers that read most of them. Paged client-side (offset, limit).
plan_filingPOST /api/v1/filing/plandocuments:writedecisions (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.

ModeAccepted inputLimit
stdiopath (a regular local file), source_url or content_base64 + filename25 MB for path (the api's limit); 5 MB decoded for base64
HTTPsource_url (preferred) or content_base64 + filename; path is not in the schema and is refused25 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.

ScopeTools
noneguide, whoami
shelves:readlist_shelves, get_shelf, list_folders, list_filing_destinations
shelves:writecreate_shelf, rename_shelf, create_folder, rename_folder, move_folder
shelves:deletedelete_shelf
shelves:read + shelves:deletedelete_folder (it reads the shelf's folders)
shelves:deleterestore_shelf, restore_folder
documents:readlist_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:uploadupload_document, create_upload_url (hosted only)
documents:writerename_document, move_document, reparse_document, plan_filing
documents:deletedelete_document, restore_document
one of documents:write, documents:delete, shelves:deletepreview_changes, apply_changes, get_changeset (the api checks the one the operation needs)
documents:read + shelves:readlist_deleted
shares:readlist_share_links
shares:writecreate_share_link, revoke_share_link
parsers:readlist_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:writecreate_parser_candidate, revise_parser_candidate, discard_parser_candidate, test_parser_candidate, activate_parser_candidate
parsers:executeapply_parser
audit:readget_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} with content): 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.

WorkflowAPIMCP tool
See who I am and what this credential may doGET /auth/me, GET /credentialwhoami
Find documents, folders and shelves by wordGET /searchsearch
Browse shelvesGET /shelves, GET /shelves/{id}list_shelves, get_shelf
Browse a shelf's foldersGET /shelves/{id}/folderslist_folders
List documents (all, a shelf's, a folder's)GET /files, GET /shelves/{id}/fileslist_documents
Read a document's details, labels and parser resultGET /files/{id}get_document
Read a document's textGET /files/{id}get_document_text
Open or download the original fileGET /files/{id} (download_url)get_document with include_download_url (a credential)
See where processing is, and why it failedGET /files/{id}/processing, GET /files/processingget_processing_status, get_processing_statuses
Upload a documentPOST /filesupload_document (duplicates, on_duplicate, keyed)
Upload a file the model should not carry (hosted)POST /filescreate_upload_url, then a PUT of the bytes
Process a document againPOST /files/{id}/parsereparse_document
Create, rename, delete a shelfPOST/PATCH/DELETE /shelves[/{id}]create_shelf, rename_shelf, delete_shelf
Create, rename, move, delete a folderPOST /shelves/{id}/folders, PATCH/DELETE /folders/{id}create_folder, rename_folder, move_folder, delete_folder
Rename a document; move it to a folder or shelfPATCH /files/{id}rename_document, move_document
Delete a documentDELETE /files/{id}delete_document
Move, rename or delete many at once, previewed firstPOST /changesets, POST /changesets/{id}/apply, GET /changesets/{id}preview_changes, apply_changes, get_changeset
Answer a question across many documents, with the evidenceGET /evidencegather_evidence
Total or summarise a field across documentsGET /evidence (aggregate)summarise_field
Find documents missing a field, unread or failedGET /evidence (missing, reading)find_exceptions
Classify and file documents into folders, approved firstGET /filing/candidates, GET /filing/destinations, POST /filing/plan, POST /changesets/{id}/applylist_filing_candidates, list_filing_destinations, plan_filing, apply_changes
See the trashGET /files/deleted, GET /folders/deleted, GET /shelves/deletedlist_deleted
Restore a document, folder or shelf from the trashPOST /{files,folders,shelves}/{id}/restorerestore_document, restore_folder, restore_shelf (keyed)
See a document's share linksGET /files/{id}/shareslist_share_links
Share a document by link; stop sharingPOST /files/{id}/shares, DELETE /files/{id}/shares/{shareId}create_share_link, revoke_share_link
See parsersGET /parsers, GET /parsers/{id}list_parsers, get_parser (behind the parsers flag)
Write a parser from examples, test it, activate itGET /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 documentsPOST /parsers/{id}/applyapply_parser (keyed)
See a parser's earlier revisionsGET /parsers/{id}/revisionslist_parser_revisions
See what was changed, when, and by which credentialGET /auditget_activity

Human-only, on purpose:

WorkflowAPIWhy it stays with the person
Correct a document's text or HTMLPATCH /files/{id} (content, content_html)Overwrites what Shelf read; deferred by the human (2026-09-30).
Review a document Shelf wasn't sure ofPOST /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 parsersPOST /parsers/import, /parsers/drafts…, PUT/DELETE /parsers/{id}, POST /parsers/{id}/rereadCandidates 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 nowPOST /{files,folders,shelves}/{id}/purgeCan't be undone, and full access only; the api purges after 30 days anyway.
Bulk download linksPOST /downloadsA 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 a shelf_id now, but move_folder doesn'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; …"}
FieldMeaning
codeThe api's stable code (README, "Errors"), or one below for failures before the api answered
retryableWhether the same call may succeed later
retry_after_seconds, max_retriesOnly when retryable: wait this long, double it each time, at most max_retries (3) tries
http_statusThe api's status; absent when the api never answered
fieldThe argument at fault, when the api named one or the tool's schema refused it
resource_idThe caller's existing resource the error is about: create_shelf/create_folder name the clashing shelf/folder
idempotency_keyThe key a failed keyed write was sent with; retry with it
hintA 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:

SituationcodeRetryable
Bad argument, checked before sendinginvalid_inputno
No token, or the token was rejectedunauthenticatedno: call guide
The plan lacks MCP (the gate) or the featureplan_limitno
Not allowed with this credentialforbiddenno
The connection lacks a scope (required_scope names it)insufficient_scopeno
An idempotency_key reused with other arguments; nothing ranidempotency_key_reusedno: use a new key
The first call with this key is still runningidempotency_key_in_useyes, with the same key
Missing, or someone else'snot_foundno
Duplicate name, count limitconflictno
Still being prepared (draft, re-read, search index)not_readyyes
Too many requestsrate_limitedyes, after Retry-After
The api failed, or a service behind itinternal, upstream_failedyes
The api is unreachable or downunavailableyes
The server doesn't run the feature (search)not_configuredno
The api's answer couldn't be decoded (a version mismatch)internalno

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:

RouteAuthAnswer
POST/GET/DELETE /mcpbearerMCP. 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-resourcenoneRFC 9728 metadata: resource, authorization_servers, scopes_supported, bearer_methods_supported.
GET /healthznoneok
GET /versionnoneThe 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.

SettingDefaultMeaning
--http(stdio)Listen address
SHELF_API_URL(required with --http)The api's base URL, without /api/v1
MCP_RESOURCE_URLhttps://shelf.tri2b.cloud/mcpPublic URL of /mcp; the metadata path and URL are derived from it
OIDC_ISSUERhttps://auth.tri2b.cloudToken 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_SERVERSOIDC_ISSUER (or the MCP origin when the proxy is on)Comma-separated override for the metadata's authorization_servers
MCP_ALLOW_INSECURE_CREDENTIALS1 accepts a bearer behind a proxy that forwards plain http
MCP_SSE_HEARTBEAT30sHow 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, then Mcp-Session-Id on every request, and an optional GET /mcp SSE stream that MCP_SSE_HEARTBEAT keeps alive.
  • 2026-07-28 (stateless): no initialize and no session. Every request carries _meta["io.modelcontextprotocol/protocolVersion"] and the matching Mcp-Protocol-Version and Mcp-Method headers (Mcp-Name too on tools/call). server/discover answers supportedVersions (2026-07-28 down to 2024-11-05), capabilities (tools), the instructions and _meta["io.modelcontextprotocol/serverInfo"] {name: "shelf", version}. GET and DELETE /mcp are 405.

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:

  • /mcp and /mcp/* (the upload PUT URLs live there)
  • /.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp
  • /.well-known/oauth-authorization-server and /.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:

RouteAnswer
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/registerDCR. 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/authorizeChecks 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/callbackZitadel 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/consentThe 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/tokenauthorization_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.

SettingDefaultMeaning
MCP_OAUTH_PROXY1 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_ISSUERorigin of MCP_RESOURCE_URLThe 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/mcp has resource https://shelf.tri2b.cloud/mcp and lists https://shelf.tri2b.cloud in authorization_servers;
  • GET https://shelf.tri2b.cloud/.well-known/oauth-authorization-server lists /oauth/register, /oauth/authorize, /oauth/token, S256 and the three auth methods;
  • the Zitadel app shelf-mcp has the redirect URI https://shelf.tri2b.cloud/oauth/callback;
  • after signing in, whoami answers with your sub.

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) and http://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.

  • 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: the projects-mcp design 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.

ToolScopeSide effectsReversibility
guidenoneNone; reads embedded playbooks, no api call.n/a
whoaminoneNone.n/a
list_shelvesshelves:readNone.n/a
get_shelfshelves:readNone.n/a
list_foldersshelves:readNone.n/a
list_documentsdocuments:readNone.n/a
get_documentdocuments:readNone. include_download_url mints a short-lived signed URL, a credential.The URL expires on its own.
get_document_textdocuments:readNone.n/a
get_document_sitedocuments:readNone; reads the document's site, builds nothing and costs nothing.n/a
searchdocuments:readNone.n/a
list_share_linksshares:readNone. Tokens are never returned, only token_hint.n/a
list_parsersparsers:read (flag parsers)None.n/a
get_parserparsers:read (flag parsers)None.n/a
get_parser_schemaparsers:read (flag parsers)None.n/a
validate_parserparsers:read (flag parsers)None; checks a spec, saves nothing.n/a
list_parser_candidatesparsers:read (flag parsers)None.n/a
get_parser_candidateparsers:read (flag parsers)None.n/a
list_parser_revisionsparsers:read (flag parsers)None.n/a
create_parser_candidateparsers: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_candidateparsers:write (flag parsers)Replaces the candidate's spec as its next version, untested.revise_parser_candidate with the old spec (another version).
discard_parser_candidateparsers:write (flag parsers)Deletes the candidate and its tests; a parser it made stays.Not reversible: submit the spec again.
test_parser_candidateparsers:write (flag parsers)Keeps the test on the candidate; no document changes.n/a (the next test replaces it).
activate_parser_candidateparsers: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_parserparsers: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_statusdocuments:readNone.n/a
get_processing_statusesdocuments:readNone.n/a
gather_evidencedocuments:readNone.n/a
summarise_fielddocuments:readNone.n/a
find_exceptionsdocuments:readNone.n/a
create_shelfshelves:writeCreates a shelf.delete_shelf (to the trash). A retry with the same idempotency_key, or the same name, creates nothing new.
rename_shelfshelves:writeRenames a shelf.rename_shelf back.
delete_shelfshelves:deleteWithout 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_foldershelves:writeCreates a folder.delete_folder (to the trash). Keyed like create_shelf.
rename_foldershelves:writeRenames a folder.rename_folder back.
move_foldershelves:writeMoves a folder and everything in it within its shelf.move_folder back to the old parent_id.
delete_foldershelves:read and shelves:deleteLike delete_shelf, for a folder, its subfolders and their documents.restore_folder within 30 days.
rename_documentdocuments:writeRenames a document (the name Shelf shows).rename_document back.
move_documentdocuments:writeMoves one document to another folder, its shelf's top level or another shelf.move_document back.
reparse_documentdocuments:writeQueues 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_documentdocuments:uploadStores 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_urldocuments:uploadHosted 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_documentdocuments:deleteLike delete_shelf, for one document; its share links stop working while it is deleted.restore_document within 30 days; the links work again.
list_deleteddocuments:read and shelves:readNone.n/a
restore_documentdocuments:deleteBrings a document back from the trash.delete_document.
restore_foldershelves:deleteBrings a folder back with what was deleted with it.delete_folder.
restore_shelfshelves:deleteBrings a shelf back with what was deleted with it.delete_shelf.
preview_changesany of documents:write, documents:delete, shelves:deleteNone to the person's documents; stores the previewed changeset, which expires after an hour.Expires on its own.
apply_changesany of documents:write, documents:delete, shelves:deleteApplies 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_changesetany of documents:write, documents:delete, shelves:deleteNone.n/a
list_filing_candidatesdocuments:read (shelf and folder names only with shelves:read)None.n/a
list_filing_destinationsshelves:readNone.n/a
plan_filingdocuments:writeNone 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_linkshares:writeCreates 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_linkshares:writeStops a link for good.Not reversible: create a new link (a new url).
get_activityaudit:readNone.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.

ToolBeforeAfter
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

ChangeToolsBeforeAfter
Unknown arguments refusedallignored (additionalProperties unset)additionalProperties: false: a typo or another tool's parameter is an invalid_input error naming the arguments the tool takes
Id parameters checkedevery *_id, client_ref, document_ids, preview_changes itemstype: 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 integersoffset, limit, page, per_page, expires_in_daystype: number (2.5 was truncated)type: integer
Lengthssearch.q; name of the create and rename tools; create_share_link.title; idempotency_key; preview_changes items[].filenamechecked by the handler or the apiq 1-200 characters, names and filenames at least 1, title at most 100, idempotency_key printable ASCII up to 255
Array boundspreview_changes.items, get_processing_statuses.document_idsat most 500 / 200, checked by the handlerminItems: 1 / maxItems in the schema
confirm must be a booleandelete_shelf, delete_folder, delete_document"true" or 1 gave a dry runrefused 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 nameNowRemoved 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.

ToolRouteWhat it is for
gather_evidenceGET /api/v1/evidenceA 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_fieldGET /api/v1/evidence with aggregate= and limit=0Totals 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_exceptionsGET /api/v1/evidence with missing=, or reading=unread,failed when no field is namedThe 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_candidatesGET /api/v1/filing/candidatesThe 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_destinationsGET /api/v1/filing/destinationsEvery shelf and folder by path, with what is in it. The api answers the whole list; the tool pages it (offset, limit).
plan_filingPOST /api/v1/filing/planThe 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.

ToolRouteWhat it is for
get_parser_schemaGET /api/v1/parsers/schemaThe parser file format to write a spec in.
validate_parserPOST /api/v1/parsers/validateCheck a spec without saving: valid, the parser, diagnostics.
list_parser_candidatesGET /api/v1/parsers/candidatesThe person's candidates, summarised; paged client-side.
get_parser_candidateGET /api/v1/parsers/candidates/{id}One candidate in full, with its latest test.
create_parser_candidatePOST /api/v1/parsers/candidatesWrite 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_candidatePUT /api/v1/parsers/candidates/{id}The candidate's next version, to be tested again.
discard_parser_candidateDELETE /api/v1/parsers/candidates/{id}Discard a candidate.
test_parser_candidatePOST /api/v1/parsers/candidates/{id}/testTest 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_candidatePOST /api/v1/parsers/candidates/{id}/activateMake the tested version a parser or revision; 409 when untested, another version, or the parser moved on.
apply_parserPOST /api/v1/parsers/{id}/applyRoll a parser out to 1-100 chosen documents, synchronously, with skip reasons.
list_parser_revisionsGET /api/v1/parsers/{id}/revisionsA 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 with filename, shelf_id or folder_id is refused before anything is sent (reparse takes only an id). Scope: documents:write, as reparse_document.
  • Preview. Each item is ready, or says why not: unchanged with code not_ready (already queued; it isn't queued twice), invalid with unprocessable (Shelf doesn't read that document) or plan_limit (the account is over its plan's limits, checked once for the whole batch), and not_found. before/after carry parse_status.
  • Apply queues each ready document's reading once (an activity row file.reprocess each) and is idempotent: a retried apply_changes is answered with the first one's results, and the same items previewed again are unchanged. Watch the readings with get_processing_statuses.
  • Descriptions. preview_changes' first sentence adds "or a bulk reparse of many documents"; reparse_document's now says "one document" and points to preview_changes for many; apply_changes says reparsed items are queued. TestToolSelectionByDescription tells them apart: reparse one document picks reparse_document, reparse many documents preview_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.