Safety model
How the server keeps the model from changing more than the user allowed: where tiers are enforced, how a write runs, and how state is kept apart per account. It is for contributors and reviewers; how to configure all this is in Permissions and confirmation.
Tiers
Every tool has exactly one tier, and reads and writes never share a tool. What each tier covers,
its default and the switches (SEVDESK_ALLOW, SEVDESK_READ_ONLY, dry run) are in
Permissions.
Enforcement in three places
- Registration: tools above the allowed tiers are not registered.
- Dispatcher: every call re-checks the tier.
- HTTP client: every request that changes data (any non-GET, and the GETs that change state)
must declare its tier, and is refused before sending in read-only or dry-run mode, when it
declares no tier, when
SEVDESK_ALLOWdoes not enable that tier, or when the tier is below the endpoint's minimum (minimumWriteTierinpaths.ts:sendBy,bookAmount,enshrine,cancelInvoice,resetToDraft,resetToOpen,changeParameter, a sendinggetPdf, DATEVenshrineexports, asaveVoucherwhose voucher is not a draft (the voucher's finalize) andPUT/DELETE /CheckAccountTransaction/{id}(private marking, reset) needcommit;sendViaEmailandsendByWithRenderneedexternal).
Write tools never set the tier: their execute gets a client that stamps it (tierScopedClient,
which applies the endpoint rule too), their prepare one that refuses every write
(readOnlyClient). The client recognizes the state-changing GETs by endpoint, not only by the
caller's sideEffect flag: a getPdf read always goes out with the literal preventSendBy=true
(recorded: drafts stay drafts), while getPdf with preventSendBy off, sendByWithRender, DATEV
exports with an enshrine flag (all commit/external, see
D-023) and the next-number endpoints
unless useNextNumber=false (they reserve a document number; write; the documented
getNextCustomerNumber stays a read) count as writes.
Write flow
A write tool (src/tools/write-flow.ts) has prepare (reads, checks, builds a preview: action,
facts, warnings, irreversible) and execute. A commit or external tool builds the preview
twice from the same data, in English and in German (previewDe; the type of defineWriteTool
requires it): the model, dry runs, the audit log and the elicitation show the English text, the
approval pages show the German one to a reader whose browser asks for German. The flow refuses a
pair that differs in the number of facts or warnings or in irreversible, and the preview hash
covers both texts.
Every call runs prepare, then a dry run stops, commit/external calls are confirmed, the audit
log records executing and only then execute runs. Results are wrapped as
{status: "done" | "dry_run" | "approval_pending" | "declined", result?, preview?, approval?}
(result only when done); the same era rules for outputSchema and structuredContent apply as
for reads.
Human confirmation
SEVDESK_CONFIRM sets how a human approves the preview of a commit or external call
(Confirmation modes,
ADR 0003); what the preview shows and what an
approval binds is in Human confirmation.
In the code, elicit uses the SDK's sealed requestState; browser keeps approvals in
src/safety/approval-store.ts and shows them on the local approval page over stdio
(src/safety/approval-local.ts, opened by src/safety/open-url.ts) or in the
approval inbox over HTTP (src/http/approval-routes.ts,
ADR 0007). The key, the nonces, the approvals and the
audit writer live in one SafetyRuntime (src/safety/runtime.ts) per server factory, shared by
every instance the factory builds.
A confirm: true argument is never a gate, because the model can set it itself. enshrine always
warns that it is irreversible (GoBD).
Pages
Every page a human sees (approval, inbox, sign-in, consent, upload, results and errors) is built
on src/pages/: static HTML without script, every value escaped by the markup template tag, one
style block with a per-response nonce, German or English from Accept-Language. The response
headers come from htmlResponse (src/safety/web.ts): no-store, no framing, and the policy
default-src 'none'; style-src 'nonce-…'; font-src <origin>/assets/; img-src <origin>/assets/; form-action 'self'; frame-ancestors 'none'; base-uri 'none'. Fonts and the icon are embedded in
the build and served by the server itself under /assets/ (immutable, by content hash); nothing
is fetched from anyone else (ADR 0010).
Account scoping
In OAuth mode one process serves several accounts and grants, so everything that holds state is
keyed by the request's principal (grant and account, from requestPrincipal):
- the confirmation codec binds the principal, so a
requestStateissued to one account is refused for another; - a retry takes only an approval its own grant created; the inbox lists and decides per account, and one account's approvals cannot push another account's out of the store;
- every account gets its own frozen
Configand sevDesk client, and the domain caches (account settings, ReceiptGuidance, booking accounts, the bookkeeping system version, country codes) are keyed by that config object, so accounts never share cached data; - the audit log records the account and the grant of every line.
Annotations
Every tool declares all four MCP annotations (readOnlyHint, destructiveHint, idempotentHint,
openWorldHint) explicitly; a test enforces it.
Write integrity
Duplicate check before creating (number, amount, date, description). No retries for writes. Read
back after every write. Optional JSONL audit log via SEVDESK_AUDIT_LOG (src/safety/audit.ts;
its format and integrity are in Audit log). A multi-step
write that fails half-way reports the records it already changed (SevdeskError.completedWrites),
in the error text and the audit log.
Document drafts validate tax rule × rate against the reference tax rules before any API call;
booking accounts against ReceiptGuidance (src/domain/receipt-guidance.ts): voucher drafts and
finalizing check every account × tax rule × rate against it, because sevDesk itself accepts any
combination on a draft. Bank bookings plan every allocation against the document's open amount and
the transaction's remaining amount (from the transaction log) before anything is sent.
Record locks
A check followed by a write is void when two calls run at once: both read the state before either
wrote. So a write tool declares locks: the records its checks depend on (the document, the bank
transaction, the contact, the part, the order or invoice a document is derived from) or an
account-wide key (all bookings; the credit note number range, whose counter sevDesk does not
advance on createFromInvoice; customer numbers; part numbers; new voucher drafts, for their
duplicate refusal). Calls of one account that share a key run one after the other, from prepare
to the end of execute (src/safety/record-locks.ts).
The locks live in one server process; several replicas would need a shared lock. The metadata lint
fails for a write tool without locks unless it is on a short list with its reason: new invoice
and order drafts (their duplicate check only warns) and the DATEV export.
Untrusted text
Contact names, descriptions, bank transfer purposes (Verwendungszweck) and e-invoice fields can be written by third parties and may carry prompt injection. They are stripped of invisible and bidi characters, fenced in output, and never interpolated into error messages or instructions.
Files
Tools never touch the file system or the transfer store directly; every byte they read or hand out
passes the FileAccess of their context (Files). Every tool that reads or
writes files or opens an upload page declares localEffects and is on a reviewed list in the
metadata lint; a read tool that hands out files or opens an upload page (a ticket on this server)
sets readOnlyHint: false, because it changes state outside sevDesk. E-invoice XML is parsed
without entity expansion or DOCTYPEs, with size and depth limits.
Generic read
sevdesk_api_get (toolset advanced, off by default) lets the model choose a GET path, so it has
four independent guards, described in
Generic read surface. The code is
genericGetRefusal in src/sevdesk/paths.ts and src/domain/api-get.ts.
Token
The sevDesk API token has full account access, no scopes and no expiry. It is redacted everywhere, and a 401 is final. Where it comes from depends on the mode:
- stdio: the environment, a
*_FILEor, optionally, the OS keychain, checked at startup withGET /Tools/bookkeepingSystemVersion.SEVDESK_PROFILEfirst overlays a named profile from a local JSON file onto the same variables before they are validated (src/accounts/local-config.ts, ADR 0009). The keychain is read through the operating system's helpers (/usr/bin/securityon macOS,secret-toolon Linux, Windows PowerShell with WinRTPasswordVaulton Windows) under the fixed servicemcp-server-sevdesk, so configuration names only a label. How to use both is in Profiles and keychain. - bearer: the environment or a
*_FILE; the server looks up its account (GET /SevClient) at startup. A failed lookup is logged as a warning and does not stop the server (approvals and audit lines then use the account scopebearer). - OAuth: each user pastes it on the consent page; it is checked with
GET /SevClient, sealed into that user's tokens and checked again on every refresh.
The threat model is in the Security policy; token storage on your own machine is analysed in Local security.