# REST and MCP reference Full endpoint and MCP client reference. Everyday usage is in [operations.md](operations.md); the design is in [ARCHITECTURE.md](../ARCHITECTURE.md#rest-api). ## Generated reference (OpenAPI) [`openapi.json`](openapi.json) is a committed OpenAPI 3.1 description of everything this binary serves: every REST route with its parameters and response schemas, the error shape, the MCP endpoint (`POST`, the standalone `GET` stream and the session `DELETE`), and an `x-mcp-tools` extension listing each MCP tool with the description and input JSON Schema the tool router reports (eight tools, or ten with `[peers] enabled = true`). `tests/openapi.rs` keeps it true: it fails if a route of the real router is undocumented, if a tool is missing from `x-mcp-tools`, or if the file is stale. - `GET /api/v1/openapi.json` returns the document for the running instance, behind the same bearer token as the rest of `/api/v1`. Peer routes appear only when peers are enabled. - `GET /docs` renders it with Redoc. The page (`/docs`) and the Redoc 2.5.4 bundle (`/docs/redoc.standalone.js`, embedded in the binary) are public, static and hold no host data; the page asks for a bearer token, keeps it in `sessionStorage` and sends it only to `GET /api/v1/openapi.json`, so the spec itself stays behind auth. With `[auth] enabled = false` it loads without asking. The page answers with a strict `Content-Security-Policy` (no external origins), so nothing is fetched from a CDN. Redoc shows REST operations; the MCP tools in `x-mcp-tools` are in the JSON, not in the rendered page. - `slinuxm openapi [--peers]` prints the same document offline: no config file, no token, no server, no port. `--peers` describes a consolidator; without it you get the peer-less instance. - Regenerate after changing a route, a tool, a response type or the crate version: ```sh cargo run -- openapi --peers > docs/openapi.json ``` ## REST Base: `http://127.0.0.1:1984`. Errors are `{"error":{"code","message"}}`. | Route | Notes | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `GET /healthz` | public, `{"status":"ok","version":...}`, `version` is the build stamp `YYYY.MM.DD--` | | `GET /docs`, `GET /docs/redoc.standalone.js` | public static Redoc viewer for the OpenAPI document, see [Generated reference](#generated-reference-openapi) | | `GET /api/v1/systemd/units?state=failed` | `state` is an active state (`failed`, `active`, ...) | | `GET /api/v1/systemd/units/{name}` | one unit with details; read-only, so only units systemd has loaded (unloaded or unknown is 404) | | `GET /api/v1/systemd/timers` | | | `GET /api/v1/journal?unit=&priority=err&lines=100` | priority by name or number | | `GET /api/v1/journal/follow?unit=&priority=` | SSE, event `journal` | | `GET /api/v1/docker/ps` | `503` when Docker is unavailable | | `GET /api/v1/docker/containers/{name}` | | | `GET /api/v1/docker/containers/{name}/logs?tail=&since=&follow=0\|1` | JSON, or SSE with events `stdout`/`stderr` | | `GET /api/v1/peers` | consolidator only; sorted status list; absent when peers are disabled | | `GET /api/v1/peers/{peer}` | one peer's status object; unknown name is 404 | | `GET /api/v1/peers/{peer}/...` | GET-only pass-through of that peer's documented routes | | `GET /api/v1/openapi.json` | this document, OpenAPI 3.1 (see [Generated reference](#generated-reference-openapi)) | ```sh TOKEN=slinuxm_... curl -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/systemd/units?state=failed' curl -N -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/journal/follow?priority=err' ``` ### Peers Present only when `[peers] enabled = true`. The same inbound token as the rest of `/api/v1` is required. `GET /api/v1/peers` returns `{"peers":[...]}` sorted by name, including disabled peers. `GET /api/v1/peers/{peer}` returns one object, not wrapped: ```json { "name": "beta", "enabled": true, "url": "http://beta:1984", "server": { "up": true, "since": "2026-10-19T10:00:00Z", "last_checked": "2026-10-19T10:00:09Z", "last_error": null, "latency_ms": 1 }, "api": { "up": true, "since": "2026-10-19T10:00:00Z", "last_checked": "2026-10-19T10:00:05Z", "last_error": null, "latency_ms": 7, "auth": "ok", "peer_version": "0.1.0" } } ``` `server` is the TCP check and `api` is the authenticated ping. `auth` is `ok`, `rejected` or `unknown`. Before the first check, `up` is false, `auth` is `unknown` and the timestamps are null. An unknown name is `404` `{"error":{"code":"not_found","message":"peer : unknown peer"}}`. `GET /api/v1/peers/{peer}/{path}` forwards a GET to that peer and returns the peer's status and body. The path has to be one of the documented read routes: `systemd/units`, `systemd/units/{name}`, `systemd/timers`, `journal`, `journal/follow`, `docker/ps`, `docker/containers/{name}`, `docker/containers/{name}/logs`. `ping` and `peers/...` are not forwarded. `systemd/units/{name}` accepts exactly what the local route accepts, including escaped names (`mnt-data\x2dbackup.mount`, sent as `%5C`) and `-.mount`. `..`, encoded slashes, NUL/CRLF, a second encoding layer and any other path are `400` `peer : path not allowed`. Query keys are the same ones the local route accepts (`state`, `unit`, `priority`, `lines`, `since`, `all`, `tail`, `follow`); anything else is `400` `peer : unsupported query parameter`. The `unit` value is checked with the same unit-name rule as `systemd/units/{name}`, so escaped names work as both `%5C` and a literal backslash (`/api/v1/peers/beta/journal?unit=mnt-data%5Cx2dbackup.mount`). The caller's `Authorization` and `Cookie` are not forwarded; the consolidator sends the peer's own token. A request that already has `x-slinuxm-hop` is `400` `peer : chained requests are not allowed`. Other methods are `405`. `journal/follow` and docker logs with `follow=1` are `text/event-stream` with `Cache-Control: no-cache`, like the local follow routes, cut off at `limits.max_follow_secs` or shutdown. Bodies larger than `peers.max_response_bytes` are `503` `peer : oversize`. Only `2xx` from the peer is passed through; any other status becomes the section 4 error for that peer (a peer `404` is `404 not_found`, a peer `401`/`403` is `503 peer rejected credentials`, anything else is `503 http_`), so a redirect or the peer's own error body never reaches the caller. Every proxied response for a configured peer, including the consolidator's own errors (`400`, `404`, `500`, `503`), carries `x-slinuxm-peer: `. A request for an unknown or malformed peer name is `404` with no peer header: it did not come from a peer. A peer failure never becomes `401`: a peer refusing the consolidator's token is `503` `peer : peer rejected credentials`, so the caller does not re-authenticate against the wrong host. ```sh curl -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/peers/beta/systemd/units?state=failed' ``` ## MCP Endpoint: `http://127.0.0.1:1984/mcp` (Streamable HTTP). `POST /mcp` carries the JSON-RPC messages; the default session mode also serves `GET /mcp` (standalone `text/event-stream` for server-to-client messages) and `DELETE /mcp` (end the session named by `Mcp-Session-Id`; 202 on success). Eight tools (`list_systemd_units`, `get_systemd_unit`, `list_systemd_timers`, `get_journal_logs`, `tail_journal`, `list_containers`, `get_container`, `get_container_logs`), two prompts (`diagnose_unit`, `container_health_report`) two resources (`systemd://units/failed`, `docker://containers`) and two resource templates (`systemd://unit/{name}`, `docker://container/{name}`, same JSON as `get_systemd_unit` and `get_container`; percent-encode unusual characters in the name). Log content is untrusted data and is labelled as such in tool results. Generic client config (header-capable clients): ```json { "mcpServers": { "linux-tracker": { "url": "http://127.0.0.1:1984/mcp", "headers": { "Authorization": "Bearer slinuxm_..." } } } } ``` Claude Code: `claude mcp add --transport http linux-tracker http://127.0.0.1:1984/mcp --header "Authorization: Bearer $TOKEN"`. Inspector: `npx @modelcontextprotocol/inspector`, transport Streamable HTTP, add the bearer header. Raw handshake with curl: ```sh curl -si -X POST http://127.0.0.1:1984/mcp \ -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' ``` ### Origin and Host checks `/mcp` validates `Origin` and `Host` to defend against DNS rebinding from browsers. Loopback names, `server.bind` and the configured port are accepted by default. Requests without an `Origin` header (non-browser clients) pass this check, so the bearer token remains the real gate. If you bind to `0.0.0.0` or serve behind a name, add the names clients use to `server.allowed_hosts` (for example `["monitor.lan:1984"]`) and any browser origins to `server.allowed_origins`. With `auth.enabled = false` (loopback only), REST requests are checked against a Host allowlist (loopback names, `server.bind` and `server.allowed_hosts`) and get `403` otherwise, to blunt DNS rebinding. There is no Origin check on REST and no token in that mode, so keep auth enabled on any multi-user host. If the host is reachable beyond a trusted network, enable native TLS (see [tls.md](tls.md)) or terminate TLS in a reverse proxy.