3.5 KiB
REST and MCP reference
Full endpoint and MCP client reference. The short version is in the README; the design is in ARCHITECTURE.md.
REST
Base: http://127.0.0.1:1984. Errors are {"error":{"code","message"}}.
| Route | Notes |
|---|---|
GET /healthz |
public, {"status":"ok","version":...} |
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 |
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'
MCP
Endpoint: http://127.0.0.1:1984/mcp (Streamable HTTP). 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):
{
"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:
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) or terminate TLS in a reverse proxy.