Developers

Shelf MCP: setup and agent workflows

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

Coming soon: MCP access will be a paid plugin, and paid plans and plugins are not on sale yet. See the pricing page.

Setup for each kind of client, then the workflows step by step. Every tool and its scope, side effects and reversibility are on the MCP page; the HTTP API behind them at /docs/api.

How to connect an MCP client to Shelf, keep its credential safe, and run the five workflows Shelf is built for, end to end: what to ask, the exact tool calls, which of them change anything, and what to do when one fails.

mcp.md has every tool's route and behaviour, and mcp-tools.md each tool's scope, side effects and reversibility. This page uses the current tool names and arguments, and TestGuidesMatchTheToolSurface (cmd/mcp/guides_doc_test.go) fails when a tool or argument named here leaves the surface (see How this page is checked).

Before you start

  • Plan. MCP and agent access will be a Premium plugin, coming soon. Until it is available, every tool but guide fails with plan_limit and an upgrade URL for an account without access (a complimentary plan grant that includes it counts); guide always works.
  • Parsers. The parser tools (workflow 3) are shown only to accounts with the parsers feature; without it they are not in tools/list and a call to one is an unknown tool.
  • Identity. Every tool acts as one person, with that person's access or less. No tool reaches another person's documents: theirs answer not_found, exactly as a missing one does.

Connecting a client

The hosted server is https://shelf.tri2b.cloud/mcp (MCP streamable HTTP, served through the landing site's proxy). Every client connects with OAuth sign-in: the client opens Shelf's sign-in at auth.tri2b.cloud (Zitadel) the first time it connects, and then Shelf's consent step asks you to

  • name the connection (prefilled with the client's own name);
  • pick its permissions: a preset (Read only, Organiser, Uploader, All permissions) or any set of scopes (agent-scopes.md);
  • Allow it, or Cancel.

The client then acts as you, within those permissions only, until you disconnect it. Connecting again makes a new connection, with permissions picked afresh. OAuth sign-in is the only way to connect: there is no key to make or paste.

Your connections are in the web app under Settings → MCP connections (<https://app.shelf.tri2b.cloud/settings/mcp-connections>): the number of active connections above a table of them (name, client, permissions, when each was connected and last used, and whether it is active), with Disconnect on each row. Disconnecting takes effect on the client's next request; Show disconnected lists the ones you disconnected.

claude.ai and Claude Desktop (connector)

  1. In claude.ai, Settings → Connectors → Add custom connector. Name it Shelf and give the URL https://shelf.tri2b.cloud/mcp. Leave the OAuth client id and secret empty: the server registers the connector itself.
  2. Connect, sign in to Shelf when asked, and on the consent step name the connection and pick its permissions. The connector keeps the grant; no token passes through the chat.
  3. Claude Desktop shows connectors added in claude.ai under the same account: enable Shelf in Settings → Connectors there, or add it the same way.
  4. In a chat, ask: *"Call whoami on Shelf and tell me who I am connected as."* The answer has your sub, and full_access: false with the scopes you allowed (or every scope, if you allowed them all).

Claude Code

Hosted server, signed in as yourself:

claude mcp add --transport http shelf https://shelf.tri2b.cloud/mcp

Then run /mcp in Claude Code, pick shelf and Authenticate: the browser sign-in and consent step return to a loopback address on your machine, which the server accepts.

Local stdio server (for development, or uploads from local paths): install shelf-mcp and sign in, as in mcp.md:

shelf-mcp login
claude mcp add shelf -e SHELF_API_URL=https://app.shelf.tri2b.cloud -- ~/.local/bin/shelf-mcp

The stdio server acts as your own login, with full access. For an agent that should do less, use the hosted server and limit its permissions on the consent step.

Any other remote MCP client

  • Transport: streamable HTTP at https://shelf.tri2b.cloud/mcp (POST for JSON-RPC, GET for the server's SSE stream, DELETE to end a session). A JSON-RPC body is at most 8 MiB. Hosted files are at most 5 MB inline as base64, and through source_url or a single-use upload address the hosted server takes 25 MB, the advertised limit (the landing proxy allows a little more on /mcp/upload/, so the MCP's own limit is the one that answers).
  • OAuth: a request with no bearer gets 401 with WWW-Authenticate: Bearer … resource_metadata="https://shelf.tri2b.cloud/.well-known/oauth-protected-resource/mcp". From there the client finds the authorization server (/.well-known/oauth-authorization-server), registers itself at /oauth/register and runs authorization code + PKCE (S256). Registration accepts the claude.ai, claude.com and ChatGPT connector callbacks and loopback callbacks (http://127.0.0.1:<port>/…, http://[::1]:<port>/…, http://localhost:<port>/…); any other redirect URI is refused.
  • Consent: after sign-in, Shelf's consent step names the connection and its permissions; Cancel answers the client access_denied. The tokens the client gets are bound to that connection, and are passed on to Shelf with every tool call, so a disconnected connection stops working at once.
  • Keep-alive: an open GET /mcp stream gets a JSON-RPC ping every 30 seconds, so proxies (Cloudflare cuts a silent response after about 100 s) don't close it. Clients need do nothing; ignore or answer the pings as the MCP spec says.

Handling the credential

  • Never put a token or key in a prompt, a tool argument, a document, a commit or an MCP config file. No Shelf tool takes a credential as an argument; anything pasted into a chat is in the transcript for good.
  • Give an agent the least it needs: Read only for questions, documents:write only for filing (workflow 4), picked on the consent step.
  • Disconnect what you no longer use in Settings → MCP connections; it takes effect on the next request.
  • Signed download URLs and share-link URLs are credentials too. get_document returns one only with include_download_url: true, and create_share_link only once, in its answer: hand them to the person, don't store or forward them.
  • whoami is the check: it names who the tools act as and what the credential may do, and never shows the token.

Operator setting: MCP_SSE_HEARTBEAT

For whoever runs shelf-mcp --http: MCP_SSE_HEARTBEAT is how often an open GET /mcp stream gets a ping, as a Go duration (30s, 1m). Default 30s; 0 turns it off. A negative or unparsable value stops the server at startup. Keep it under the idle timeout of every proxy in front of the server (Cloudflare's is about 100 s). See mcp.md.

Reading the workflows

Each workflow has a prompt to paste, a table of the calls with the arguments that matter, and the calls themselves. Mutates says whether the tool can change the person's Shelf (it is the tool's readOnlyHint turned round): preview_changes and plan_filing store a preview that expires in an hour but change no document, so they are no. Values in <angle brackets> come from an earlier answer. Every failed call is a tool error with a stable code and retryable (mcp.md); the failure tables say what to do with each.

These apply to every workflow:

Error codeWhat it meansRecovery
unauthenticatedNo token, or it was rejectedCall guide; a person signs in again (connector: reconnect; stdio: shelf-mcp login)
plan_limitThe plan lacks MCP or the featureTell the person; the error has the upgrade URL
insufficient_scopeThe connection lacks required_scopeAsk the person to connect again and allow that scope (workflow 4); don't look for a way round it
invalid_inputThe arguments don't fit the schema; nothing was sentFix the argument named in field
rate_limited, unavailable, internal, upstream_failedPassingWait retry_after_seconds, at most max_retries tries; a keyed write retries with the same idempotency_key

1. Search, inspect, answer with provenance

Read-only. Needs documents:read (and shelves:read to browse shelves).

Prompt: "Using Shelf, how much did we pay Acme in 2025? Cite every document you used by name and id, say where in it each figure came from, and tell me if anything is missing or unread."

StepToolArgumentsMutates
Check the connectionwhoamino
Find the documentssearchq, category, mode, per_pageno
Read one document's detailsget_documentdocument_idno
Read its text, in pagesget_document_textdocument_id, offset, limitno
Gather values across documentsgather_evidenceq, fields, uploaded_from, uploaded_to, limitno
Total a fieldsummarise_fieldfields, q, uploaded_from, uploaded_tono
{"name": "whoami", "arguments": {}}
{"name": "search", "arguments": {"q": "Acme invoice", "category": "documents", "per_page": 20}}
{"name": "get_document", "arguments": {"document_id": "<id from a search hit>"}}
{"name": "get_document_text", "arguments": {"document_id": "<id from a search hit>", "offset": 0, "limit": 4000}}

For a question over many documents, ask Shelf for the evidence instead of reading each one:

{"name": "gather_evidence", "arguments": {"q": "Acme", "fields": ["Total", "Invoice date"], "uploaded_from": "2025-01-01", "uploaded_to": "2025-12-31", "limit": 25}}
{"name": "summarise_field", "arguments": {"fields": ["Total"], "q": "Acme", "uploaded_from": "2025-01-01", "uploaded_to": "2025-12-31"}}

Answering with provenance. Every value gather_evidence returns carries its document_id and origin (parser, document_text or vision_model); a text fragment carries its page and line, and a field says whether the person reviewed it. Cite the document name and id for every figure, say which values come from unreviewed readings, and when the answer has partial: true, say why from partial_reasons (more_pages: page on with cursor; unread_documents or failed_documents: some documents could not be counted, see workflow 5). Shelf writes no answer itself: the agent reasons from the evidence.

FailureRecovery
search says search is unavailable (not_configured)Browse instead: list_shelves, list_documents with excerpt, get_document_text
No hitsTry mode exact for whole words, fewer words, or gather_evidence with q; say so rather than guessing
not_found on a documentIt was deleted or the id is wrong; search again
Text is empty and processing.next_action is waitNot read yet: say so, or follow workflow 5
get_document_text has a next_offsetThe text goes on: call again with offset set to it

2. Find unfiled documents, classify, preview, organise, verify

A scoped write. Needs documents:read, shelves:read and documents:write. Nothing moves until the person agrees to the preview.

Prompt: "Look at my unfiled Shelf documents, work out what each one is, and propose a folder for each. Only propose moves you are sure of, show me the plan, and don't move anything until I say yes. Then check that everything ended up where you said."

StepToolArgumentsMutates
List what to file, with what Shelf readlist_filing_candidateslimit, text_chars, afterno
List where things can golist_filing_destinationslimit, offsetno
Make a missing folder (only if the person agrees)create_foldershelf_id, name, parent_id, idempotency_keyyes
Propose the movesplan_filingdecisions, document_id, folder_id, confidence, category, reason, uncertain, min_confidenceno
Move, once the person agreesapply_changeschangeset_idyes
Check what happenedget_changesetchangeset_id, statusno
Check one documentget_documentdocument_idno
{"name": "list_filing_candidates", "arguments": {"limit": 50, "text_chars": 1000}}
{"name": "list_filing_destinations", "arguments": {"limit": 100}}
{"name": "plan_filing", "arguments": {"decisions": [{"document_id": "<candidate id>", "folder_id": "<destination folder id>", "confidence": 0.93, "category": "invoice", "reason": "Acme invoice, like the others in Invoices/2025"}, {"document_id": "<candidate id>", "uncertain": true}], "min_confidence": 0.8}}

Show the person plan_filing's answer: what would move (outcome file), and what stays and why (every other outcome). Only after they agree:

{"name": "apply_changes", "arguments": {"changeset_id": "<changeset_id from plan_filing>"}}
{"name": "get_changeset", "arguments": {"changeset_id": "<changeset_id from plan_filing>", "status": "failed"}}
{"name": "list_filing_candidates", "arguments": {"limit": 50, "text_chars": 0}}

Verify: the changeset's status is applied (every item) or partial; get_changeset with status failed (or stale) lists the ones that didn't move; the moved documents are no longer in list_filing_candidates. A destination folder that doesn't exist yet:

{"name": "create_folder", "arguments": {"shelf_id": "<shelf id>", "name": "Invoices 2025", "idempotency_key": "<a UUID you choose>"}}
FailureRecovery
changeset_id is nullNothing would move: every decision's outcome says why (uncertain, already_filed, processing, duplicate, destination_not_found, ...). Report that; don't loosen min_confidence to force it
apply_changes fails with conflict, "stale, nothing was changed"Something changed since the plan; nothing moved. Plan again
The plan expired (an hour)Plan again; nothing was moved
Status partialReport each failed or stale item from get_changeset; the rest moved
A retry of apply_changes after a timeoutSafe: it answers the first call's results, marked replayed
The person wants it undonepreview_changes with operation file.update and each document's old folder_id (from before), shown and then applied; or move_document for one

3. Example documents, draft and test a parser, activate, reparse

A scoped write to parsers, then to documents. Needs the parsers feature, documents:read, parsers:read and parsers:write; rolling out needs parsers:execute (apply_parser) or documents:write (reparse). Testing changes no document, and activating reads none.

Prompt: "These three Shelf documents are Acme invoices: write a parser that reads the invoice number, date and total. Test it on them and on two documents that are not Acme invoices, show me the results, and only activate it and apply it to the Acme invoices once I agree."

StepToolArgumentsMutates
Find the examplessearchq, categoryno
Read themget_document_textdocument_id, limitno
Learn the file formatget_parser_schemano
Check a draft without savingvalidate_parserspecno
Save it as a candidatecreate_parser_candidatespec, parser_id, idempotency_keyyes
Test it, changing no documenttest_parser_candidatecandidate_id, document_idsyes
Fix it (a new, untested version)revise_parser_candidatecandidate_id, specyes
Make it a parser, once the person agreesactivate_parser_candidatecandidate_id, version, idempotency_keyyes
Read chosen documents with itapply_parserparser_id, document_ids, idempotency_keyyes
Or read one document again from scratchreparse_documentdocument_id, idempotency_keyyes
Or read many again, previewedpreview_changesoperation, items, idno
Watch the readingsget_processing_statusesdocument_idsno
{"name": "search", "arguments": {"q": "Acme invoice", "category": "documents"}}
{"name": "get_document_text", "arguments": {"document_id": "<example id>", "limit": 8000}}
{"name": "get_parser_schema", "arguments": {}}
{"name": "validate_parser", "arguments": {"spec": "<the YAML spec>"}}
{"name": "create_parser_candidate", "arguments": {"spec": "<the YAML spec>", "idempotency_key": "<a UUID you choose>"}}
{"name": "test_parser_candidate", "arguments": {"candidate_id": "<candidate id>", "document_ids": ["<example 1>", "<example 2>", "<example 3>", "<not an Acme invoice>", "<not an Acme invoice>"]}}

Check the test: the examples have would_match: true and their fields, the others would_match: false, and fields shows each field's coverage. If not, revise and test again (each revision is a new version):

{"name": "revise_parser_candidate", "arguments": {"candidate_id": "<candidate id>", "spec": "<the fixed YAML spec>"}}
{"name": "test_parser_candidate", "arguments": {"candidate_id": "<candidate id>", "document_ids": ["<example 1>", "<example 2>", "<example 3>", "<not an Acme invoice>", "<not an Acme invoice>"]}}

Show the person the test. Once they agree, activate the version you tested, then read the chosen documents with it:

{"name": "activate_parser_candidate", "arguments": {"candidate_id": "<candidate id>", "version": 2, "idempotency_key": "<a UUID you choose>"}}
{"name": "apply_parser", "arguments": {"parser_id": "<parser id from the activation>", "document_ids": ["<example 1>", "<example 2>", "<example 3>"], "idempotency_key": "<a UUID you choose>"}}

apply_parser reads each document with this parser, synchronously, from the text Shelf already has. To read documents again from scratch instead (text extraction too, then the best-matching parser), reparse them: one with reparse_document, many through a previewed changeset. Readings run in the background, so watch them:

{"name": "reparse_document", "arguments": {"document_id": "<example 1>", "idempotency_key": "<a UUID you choose>"}}
{"name": "preview_changes", "arguments": {"operation": "reparse", "items": [{"id": "<example 2>"}, {"id": "<example 3>"}]}}
{"name": "apply_changes", "arguments": {"changeset_id": "<changeset_id from preview_changes>"}}
{"name": "get_processing_statuses", "arguments": {"document_ids": ["<example 1>", "<example 2>", "<example 3>"]}}
FailureRecovery
create_parser_candidate or revise_parser_candidate fails with unprocessableThe spec isn't valid; nothing was saved. Each diagnostic has its line and path: fix and resubmit (validate_parser checks without saving)
A test document has error_code not_read or read_failedShelf has no text for it yet: pick another example, or see workflow 5
activate_parser_candidate fails with conflictThe current version isn't tested, version isn't the current one, or the parser moved on: test the current version, or start a new candidate from the parser's current spec (get_parser)
plan_limit on create or activateA new parser will be a Premium plugin, coming soon; tell the person
apply_parser skips documentsEach has a reason_code: hand_edited (a corrected text is never replaced), not_read, wrong_kind, changed_meanwhile (apply again), not_found
A reparse item is unchanged with not_readyAlready queued; it isn't queued twice
The person wants the old parser backlist_parser_revisions for the old spec, then create_parser_candidate with it and the parser_id, test, activate and apply. A reading apply_parser replaced is not kept
The parser tools are unknownThe account doesn't have the parsers feature; tell the person

4. Read-only access versus scoped write access

What an agent can do is decided by its credential, not by the prompt. A person signed in with shelf-mcp login gives full access; an MCP connection gives only the permissions the person allowed on the consent step. The api checks every request, and tools/list leaves out the tools a connection can't use.

Permissions are picked when the client connects, where only the signed-in person can: no connection can make or widen a connection. To change them, the person connects again and disconnects the old one in Settings → MCP connections.

PresetScopesWhat the agent gets
Read onlyshelves:read documents:readWorkflow 1, list_filing_candidates, processing status; no change of any kind
Organisershelves:read shelves:write documents:read documents:writeWorkflow 2, renames, folders, reparses; no deleting, sharing or uploading
Uploadershelves:read documents:uploadupload_document, and list_shelves/list_folders to pick where; no reading documents and no other change
Activity reader (add to either)audit:readget_activity: what every credential changed

Prompt (Read only connection): "Check what you are allowed to do on Shelf, then file my unfiled documents."

Expected: whoami shows the two read scopes; the agent lists candidates and proposes folders in the chat, but cannot plan or move, and says it needs a connection allowed documents:write.

StepToolArgumentsMutates
See what this credential may dowhoamino
Read (allowed)list_filing_candidateslimitno
A write it lacks the scope forplan_filingdecisionsno
Audit what a connection did (with audit:read)get_activityactor_kind, actor_id, since, limitno
{"name": "whoami", "arguments": {}}
{"name": "list_filing_candidates", "arguments": {"limit": 20}}
{"name": "plan_filing", "arguments": {"decisions": [{"document_id": "<candidate id>", "folder_id": "<folder id>", "confidence": 0.9}]}}
{"name": "get_activity", "arguments": {"actor_kind": "mcp_connection", "actor_id": "<connection id from an event's actor.id>", "since": "2026-10-01T00:00:00Z", "limit": 50}}

With the Read only connection, plan_filing is not in tools/list; a client that calls it anyway gets a tool error whose text says the credential lacks the documents:write scope and ends [code: insufficient_scope; retryable: false], with required_scope: "documents:write" in its structuredContent. The api refused it, so nothing changed. With an Organiser connection the same call answers a plan, and apply_changes then moves the documents; a delete_document with it is refused the same way (documents:delete).

Older activity may name a retired agent key (actor_kind agent_key); get_activity still filters and shows it.

FailureRecovery
insufficient_scopeTell the person which scope (required_scope) and why; they decide whether to connect again with it allowed. An agent never asks for a credential in the chat
unauthenticated after a disconnectThe person disconnected it; the client connects again (and the person allows it again)
unauthenticated with "Shelf agent keys are retired"The client still sends an old shelf_ak_ key: remove it from the client's configuration and connect with OAuth sign-in

5. A processing job that is still running or has failed

Uploading and reading are asynchronous: an upload answers at once, and Shelf reads the document in the background. Needs documents:read, plus documents:upload to upload and documents:write to read again.

Prompt: "Upload invoice.pdf to my Invoices shelf, wait until Shelf has read it, and tell me what it found. If reading fails, tell me why and whether trying again could help; retry only if it could."

StepToolArgumentsMutates
Uploadupload_documentfilename, content_base64 or source_url, expected_sha256, shelf_id, client_ref, on_duplicateyes
Watch one readingget_processing_statusdocument_idno
Watch many, or find the failed onesget_processing_statusesdocument_ids, status, limitno
Find unread and failed documentsfind_exceptionsreading, shelf_idsno
Read again, when retrying can helpreparse_documentdocument_id, idempotency_keyyes
Read many again, previewedpreview_changesoperation, items, idno
{"name": "upload_document", "arguments": {"filename": "invoice.pdf", "content_base64": "<the file, base64>", "shelf_id": "<Invoices shelf id>", "client_ref": "<a UUID you choose>"}}
{"name": "get_processing_status", "arguments": {"document_id": "<id from the upload>"}}

processing.next_action is the decision:

next_actionMeaningWhat to do
waitQueued or running (attempts counts tries; last_error is the last one's error, being retried)Poll get_processing_status again after a few seconds, backing off; most readings take seconds to a minute (as of 2026-10-23)
noneDone; all Shelf can read is there (result complete, or no_text for a file with nothing to read, which is not a failure)Read it: get_document, get_document_text
reviewDone with a partial result (needs_review): stages.parser.problems says what is missingTell the person; they review it on the document's page in the web app
retryFailed for a reason that may pass (error.retryable: true, e.g. processing_timeout, vision_error)reparse_document, once
reportFailed because of the file (password_protected, damaged_file, unsupported_type, ...)Tell the person the error.code and message; reading it again won't help
{"name": "get_processing_statuses", "arguments": {"status": ["failed"], "limit": 100}}
{"name": "find_exceptions", "arguments": {"reading": ["unread", "failed"], "shelf_ids": ["<Invoices shelf id>"]}}
{"name": "reparse_document", "arguments": {"document_id": "<failed id>", "idempotency_key": "<a UUID you choose>"}}
{"name": "preview_changes", "arguments": {"operation": "reparse", "items": [{"id": "<failed id>"}, {"id": "<another failed id>"}]}}
FailureRecovery
The upload answers duplicate: trueNothing new was stored; the answer is the existing document and where it is. Use on_duplicate keep_both only if the person wants a second copy
The upload timed outCall again with the same client_ref (or idempotency_key): you get the first upload, never a copy
Still wait after several minutesReport it as still running with attempts and last_error; don't reparse a running reading (it would supersede it and start again)
failed with retry, and it fails againStop after one retry and report the error.code; a person decides
A reparse answers not_readyA reading is already queued; poll instead
A reparse would replace a hand-corrected textreparse_document replaces it with what Shelf reads; ask the person first
plan_limit on upload or reparseOver the plan's limits; tell the person

How this page is checked

TestGuidesMatchTheToolSurface (cmd/mcp/guides_doc_test.go) reads this page and checks it against the tools as tools/list publishes them now (every tool, every flag on, as the snapshot test sees them):

  • every ```json block is a series of tool calls, {"name", "arguments"}: the tool exists, every argument is in its schema (nested items too), every required argument is there, and literal values have the right type, enum value and bounds (a <placeholder> string only has to be a string);
  • every workflow table row names a current tool in Tool, only that tool's arguments in Arguments, and the right Mutates (no exactly when the tool is readOnlyHint);
  • every tool-like name in backticks (list_…, get_…, apply_…, and the other verbs tools start with) is a current tool.

Renaming or removing a tool, or an argument used here, fails the test until this page is updated.