Transports
How a request reaches the tools over stdio and over Streamable HTTP, which routes the HTTP server answers, and how tools read and hand out files in each mode. It is for contributors and reviewers; operators start with Remote mode.
stdio and HTTP
- stdio (default): for local clients such as Claude Desktop, Claude Code, Cursor or VS Code.
- Streamable HTTP (
--http,src/http/): for remote clients such as claude.ai custom connectors. It is for self-hosting; there is no public hosted instance. The operator's guide is Remote mode (HTTP), the decisions are ADR 0006 and ADR 0007.
Stateless MCP, one instance
POST /mcp goes to the SDK's createMcpHandler(factory, {legacy: "stateless"}): every request
gets a fresh server instance from the factory, there is no MCP session, and GET and DELETE on
/mcp answer 405. The protocol would let any instance serve any request, but the server supports
exactly one: the grant store (with a lock on its state directory), pending approvals, the
confirmation nonces and codec key, and the rate limits live in the process. Sharing them would
need a database, which the design avoids.
Authentication
The HTTP mode refuses to start without it:
bearer: one shared secret (or two while rotating), compared as HMACs in constant time; the server holds one sevDesk token, so there is one fixed account context.oauth: the server is its own OAuth 2.1 authorization server (src/http/oauth/): clients identified by Client ID Metadata Documents (CIMD) from an allowlist, PKCE with S256, an exact RFC 8707 audience check,issin the authorization response (RFC 9207), sealed tokens (AES-256-GCM, keys derived fromSEVDESK_HTTP_SECRETper purpose with HKDF), rotating refresh tokens with replay detection, and a grant store that holds no tokens. The user pastes their sevDesk token once on the consent page; it travels sealed inside their own tokens.
Request path
Every URL the server prints or redirects to is built from the configured public origin
(SEVDESK_HTTP_PUBLIC_URL), never from Host or X-Forwarded-* headers.
- Proxy. TLS ends at a reverse proxy, a platform's edge or a tunnel.
SEVDESK_HTTP_TRUST_PROXYsays how many entries ofX-Forwarded-For(from the right) were added by proxies; the client IP for rate limits and logs is the next one. - Bridge (
node-bridge.ts,serve.ts): converts betweennode:httpand WebRequest/Response, refuses bodies over the route's cap with 413 before reading more (1 MiB on/mcp, 8 KiB on/authorize, 4 KiB on/tokenand/revoke), aborts the request's signal when the client disconnects, answers 408 when a body does not arrive in time, and streams responses without buffering, a large chunk in slices of 64 KiB (a client that takes no slice for a minute is dropped). Server timeouts: 15 s for headers, 65 s keep-alive, and for a whole request the longest body window of any route plus 30 s (45 s; 120 s with the upload page, whose body may take 90 s); at most 256 connections. - Hardening (
router.ts,hardening.ts,rate-limit.ts): theHostallowlist (the SDK's validator;/healthzis exempt for platform health checks), the route match (404, or 405 withAllowfor other methods), token-bucket rate limits per client address (IPv6 per /64; 429 withRetry-After), caps on requests in flight (64 in all, 8 per client address, 8 per sevDesk account on/mcp, and 8 of the 64 kept for the routes other than/mcp), a 120 s deadline, the route'sOriginpolicy (/mcp: the SDK's validator, which compares host names against the allowed origins; there is no CORS, so web pages on other origins cannot call/mcp; HTML forms: same-origin POSTs only, neverOrigin: null), and security headers on every response (nosniff,no-store, no-transform, a referrer policy, HSTS on https). One JSON log line per request, redacted (log.ts). - Auth. Bearer:
bearer.ts. OAuth: the SDK'srequireBearerAuthwith our verifier, which opens the access token, checks type, issuer, expiry and audience, looks the grant up in the store (so revocation is immediate), checks its account and client against the current allowlists and puts aVerifiedGrantintoAuthInfo. Failures answer 401 withWWW-Authenticate(in OAuth mode pointing to the protected resource metadata). - Account resolver (
src/accounts/resolver.ts): bearer and stdio have one fixed context. OAuth gets a frozenConfigper account with the tiers of the grant ∩SEVDESK_ALLOW, no local folders and no browser opening, and a sevDesk client whose pacing is shared by all contexts of the account. Contexts are cached (64, 15 minutes idle). - Server factory (
src/server.ts): registers the tools of the context's tiers with the context'sConfigand client. From here on a call runs exactly as over stdio (Lifecycle of a tool call).
Routes
| Route | What | Access |
|---|---|---|
POST /mcp | MCP (Streamable HTTP, stateless) | bearer secret or OAuth access token |
GET /healthz | {"status":"ok"}, 503 while shutting down | open, no Host check |
GET /.well-known/oauth-protected-resource[/mcp], /.well-known/oauth-authorization-server | OAuth metadata (404 in bearer mode) | open, CORS * |
GET/POST /authorize | consent page | CSRF cookie and token, same-origin POSTs |
POST /token, POST /revoke | code and refresh exchange, revocation (RFC 7009) | PKCE, the tokens themselves |
GET /approvals, GET/POST /approvals/<id> | approval inbox (only with SEVDESK_CONFIRM=browser) | session cookie, CSRF token, same-origin POSTs |
POST /approvals/login, POST /approvals/logout | browser sign-in (with the inbox or file transfer) | sevDesk token, CSRF token, same-origin POSTs |
GET/POST /uploads/<id> | upload page of an upload request (file transfer) | session of the record's account, CSRF token |
GET /files/<id> | download link (file transfer), attachment only | session of the record's account |
GET /assets/<name> | fonts and the icon of the pages (whenever the server shows pages) | open, rate-limited, immutable |
Shutdown
On SIGTERM /healthz answers 503, running requests get 10 seconds, then the grant store is written
and its lock released.
Files
Tools get file bytes and hand files out through a FileAccess (src/safety/file-access.ts) that
the registry builds for every call from the configuration and the request's principal. There are
two implementations (src/safety/file-sources.ts):
- Local (stdio, and HTTP with file transfer off): reads only inside
SEVDESK_FILE_DIRS(src/safety/local-files.ts: real paths, no symlink escapes,O_NOFOLLOWplus an inode check, content sniffing, size caps); deliveries are new files inSEVDESK_OUTPUT_DIR(src/safety/output-files.ts: exclusive creation, mode 0600, never overwriting). - Remote (HTTP with
SEVDESK_HTTP_FILES, on by default): a file argument may be anupload:<id>reference fromsevdesk_upload_request, for which the human uploads the file on a page of the server; deliveries become short-lived download links. Both pages need a browser session of the record's account (src/http/browser-session.ts, shared with the approval inbox), so a link the model passes on is not a capability. The records live insrc/safety/transfer-store.ts(per grant and account, with limits per account and overall, and nothing ever evicted); the bytes live insrc/safety/blob-store.ts, encrypted with a key drawn per process, in memory or in the state directory, and gone after a restart. The pages aresrc/http/transfer-routes.tsandtransfer-pages.ts. Bearer mode can still use local folders, andSEVDESK_OUTPUT_DIR, when set, wins over download links.
The model never sees or sends file bytes, and it cannot put text on the upload page. Operator details, limits and lifetimes are in Files over HTTP; the decisions are in ADR 0008. How tools are kept to this path is in Safety model.