Developers
Shelf MCP: setup and agent workflows
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
guidefails withplan_limitand an upgrade URL for an account without access (a complimentary plan grant that includes it counts);guidealways works. - Parsers. The parser tools (workflow 3) are shown only to accounts with
the
parsersfeature; without it they are not intools/listand 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)
- In claude.ai, Settings → Connectors → Add custom connector. Name it
Shelfand give the URLhttps://shelf.tri2b.cloud/mcp. Leave the OAuth client id and secret empty: the server registers the connector itself. - 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.
- Claude Desktop shows connectors added in claude.ai under the same account: enable Shelf in Settings → Connectors there, or add it the same way.
- In a chat, ask: *"Call whoami on Shelf and tell me who I am connected
as."* The answer has your
sub, andfull_access: falsewith 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(POSTfor JSON-RPC,GETfor the server's SSE stream,DELETEto end a session). A JSON-RPC body is at most 8 MiB. Hosted files are at most 5 MB inline as base64, and throughsource_urlor 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
401withWWW-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/registerand 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 /mcpstream gets a JSON-RPCpingevery 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:writeonly 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_documentreturns one only withinclude_download_url: true, andcreate_share_linkonly once, in its answer: hand them to the person, don't store or forward them. whoamiis 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 code | What it means | Recovery |
|---|---|---|
unauthenticated | No token, or it was rejected | Call guide; a person signs in again (connector: reconnect; stdio: shelf-mcp login) |
plan_limit | The plan lacks MCP or the feature | Tell the person; the error has the upgrade URL |
insufficient_scope | The connection lacks required_scope | Ask the person to connect again and allow that scope (workflow 4); don't look for a way round it |
invalid_input | The arguments don't fit the schema; nothing was sent | Fix the argument named in field |
rate_limited, unavailable, internal, upstream_failed | Passing | Wait 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."
| Step | Tool | Arguments | Mutates |
|---|---|---|---|
| Check the connection | whoami | no | |
| Find the documents | search | q, category, mode, per_page | no |
| Read one document's details | get_document | document_id | no |
| Read its text, in pages | get_document_text | document_id, offset, limit | no |
| Gather values across documents | gather_evidence | q, fields, uploaded_from, uploaded_to, limit | no |
| Total a field | summarise_field | fields, q, uploaded_from, uploaded_to | no |
{"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.
| Failure | Recovery |
|---|---|
search says search is unavailable (not_configured) | Browse instead: list_shelves, list_documents with excerpt, get_document_text |
| No hits | Try mode exact for whole words, fewer words, or gather_evidence with q; say so rather than guessing |
not_found on a document | It was deleted or the id is wrong; search again |
Text is empty and processing.next_action is wait | Not read yet: say so, or follow workflow 5 |
get_document_text has a next_offset | The 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."
| Step | Tool | Arguments | Mutates |
|---|---|---|---|
| List what to file, with what Shelf read | list_filing_candidates | limit, text_chars, after | no |
| List where things can go | list_filing_destinations | limit, offset | no |
| Make a missing folder (only if the person agrees) | create_folder | shelf_id, name, parent_id, idempotency_key | yes |
| Propose the moves | plan_filing | decisions, document_id, folder_id, confidence, category, reason, uncertain, min_confidence | no |
| Move, once the person agrees | apply_changes | changeset_id | yes |
| Check what happened | get_changeset | changeset_id, status | no |
| Check one document | get_document | document_id | no |
{"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>"}}
| Failure | Recovery |
|---|---|
changeset_id is null | Nothing 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 partial | Report each failed or stale item from get_changeset; the rest moved |
A retry of apply_changes after a timeout | Safe: it answers the first call's results, marked replayed |
| The person wants it undone | preview_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."
| Step | Tool | Arguments | Mutates |
|---|---|---|---|
| Find the examples | search | q, category | no |
| Read them | get_document_text | document_id, limit | no |
| Learn the file format | get_parser_schema | no | |
| Check a draft without saving | validate_parser | spec | no |
| Save it as a candidate | create_parser_candidate | spec, parser_id, idempotency_key | yes |
| Test it, changing no document | test_parser_candidate | candidate_id, document_ids | yes |
| Fix it (a new, untested version) | revise_parser_candidate | candidate_id, spec | yes |
| Make it a parser, once the person agrees | activate_parser_candidate | candidate_id, version, idempotency_key | yes |
| Read chosen documents with it | apply_parser | parser_id, document_ids, idempotency_key | yes |
| Or read one document again from scratch | reparse_document | document_id, idempotency_key | yes |
| Or read many again, previewed | preview_changes | operation, items, id | no |
| Watch the readings | get_processing_statuses | document_ids | no |
{"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>"]}}
| Failure | Recovery |
|---|---|
create_parser_candidate or revise_parser_candidate fails with unprocessable | The 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_failed | Shelf has no text for it yet: pick another example, or see workflow 5 |
activate_parser_candidate fails with conflict | The 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 activate | A new parser will be a Premium plugin, coming soon; tell the person |
apply_parser skips documents | Each 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_ready | Already queued; it isn't queued twice |
| The person wants the old parser back | list_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 unknown | The 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.
| Preset | Scopes | What the agent gets |
|---|---|---|
| Read only | shelves:read documents:read | Workflow 1, list_filing_candidates, processing status; no change of any kind |
| Organiser | shelves:read shelves:write documents:read documents:write | Workflow 2, renames, folders, reparses; no deleting, sharing or uploading |
| Uploader | shelves:read documents:upload | upload_document, and list_shelves/list_folders to pick where; no reading documents and no other change |
| Activity reader (add to either) | audit:read | get_activity: what every credential changed |
Prompt (Read only connection): "Check what you are allowed to do on Shelf, then file my unfiled documents."
Expected:
whoamishows 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 alloweddocuments:write.
| Step | Tool | Arguments | Mutates |
|---|---|---|---|
| See what this credential may do | whoami | no | |
| Read (allowed) | list_filing_candidates | limit | no |
| A write it lacks the scope for | plan_filing | decisions | no |
Audit what a connection did (with audit:read) | get_activity | actor_kind, actor_id, since, limit | no |
{"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.
| Failure | Recovery |
|---|---|
insufficient_scope | Tell 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 disconnect | The 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."
| Step | Tool | Arguments | Mutates |
|---|---|---|---|
| Upload | upload_document | filename, content_base64 or source_url, expected_sha256, shelf_id, client_ref, on_duplicate | yes |
| Watch one reading | get_processing_status | document_id | no |
| Watch many, or find the failed ones | get_processing_statuses | document_ids, status, limit | no |
| Find unread and failed documents | find_exceptions | reading, shelf_ids | no |
| Read again, when retrying can help | reparse_document | document_id, idempotency_key | yes |
| Read many again, previewed | preview_changes | operation, items, id | no |
{"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_action | Meaning | What to do |
|---|---|---|
wait | Queued 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) |
none | Done; 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 |
review | Done with a partial result (needs_review): stages.parser.problems says what is missing | Tell the person; they review it on the document's page in the web app |
retry | Failed for a reason that may pass (error.retryable: true, e.g. processing_timeout, vision_error) | reparse_document, once |
report | Failed 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>"}]}}
| Failure | Recovery |
|---|---|
The upload answers duplicate: true | Nothing 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 out | Call again with the same client_ref (or idempotency_key): you get the first upload, never a copy |
Still wait after several minutes | Report 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 again | Stop after one retry and report the error.code; a person decides |
A reparse answers not_ready | A reading is already queued; poll instead |
| A reparse would replace a hand-corrected text | reparse_document replaces it with what Shelf reads; ask the person first |
plan_limit on upload or reparse | Over 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
```jsonblock 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 (
noexactly when the tool isreadOnlyHint); - 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.