One boundary, and everything behind it

The HTTP surface is deliberately small: a liveness probe, a machine-readable registry card, an OAuth pair, and one authenticated POST. The MCP endpoint is stateless — a fresh server object per request, no session identifier, JSON responses enabled — so the other verbs on that path exist only to say so.

GET /health

A liveness probe. Returns { ok, name, version, ts }, the version read from package.json at boot with a "0.0.0" fallback if that read fails.

GET /.well-known/registry-card

A service description: schema version, name, version, owner, endpoint, transport, and an auth block whose instructions read “Request a bearer token from the operator.”

GET /.well-known/oauth-authorization-server

Standard metadata: authorization and token endpoints, code response type, authorization_code grant, three client auth methods, S256 and plain challenge methods, one scope.

POST /mcp

The authenticated MCP route. Body limit 10 MB. Constructs an McpServer, registers all thirty tools, attaches a streamable HTTP transport, handles the request, and tears both down when the response closes.

GET /mcp · DELETE /mcp

405 with an explanatory body — “Stateless mode: use POST /mcp”. No SSE stream to resume, no session to delete.

Authentication and its error surface

The middleware runs ahead of every other handler on POST /mcp and resolves to one of three outcomes, each with a distinct shape a client can act on. A missing or malformed header sets WWW-Authenticate: Bearer; a credential that does not verify sets WWW-Authenticate: Bearer error="invalid_token". Both return 401 with their own error_description, so a client can tell “you sent nothing” from “you sent the wrong thing”. Server-side misconfiguration returns 500 — the route fails closed rather than falling open.

The OAuth server exists for one client

It implements the authorization-code grant with PKCE so that a connector platform which requires an OAuth handshake can complete one. What the flow identifies is a single known first-party client rather than an end user, which is why the metadata document advertises exactly one scope and why the redirect allowlist has exactly one entry.

One detail is worth pulling out of that table. The authorization code lives only in a process-local map with a five-minute expiry — nothing about a half-finished handshake is written to disk, and a restart invalidates every code still outstanding. The store is deliberately the most forgettable part of the flow.

The audit ledger

One table, two indices, WAL mode, opened once at boot before the token check. The logCall helper is a no-op if the database was never initialised, so a failure to open it degrades logging rather than the server.

export function logCall(
  tool: string,
  args: unknown,
  status: 'success' | 'error',
  latencyMs: number,
  error?: string,
): void {
  if (!db) return;
  const argsHash = createHash('sha256').update(JSON.stringify(args ?? {})).digest('hex').slice(0, 16);
  db.prepare(
    'INSERT INTO calls (tool, args_hash, status, latency_ms, error) VALUES (?, ?, ?, ?, ?)',
  ).run(tool, argsHash, status, latencyMs, error ?? null);
}

Everything eventually becomes a subprocess

Search, graph traversal, credential reads, remote execution, file copies and both CLIs run through the same eighty-line wrapper. It uses spawn with an argument array — never a shell string — copies the environment with overrides applied on top, and enforces two independent limits.

That asymmetry matters for tool output. On success the model sees exactly what the command printed and nothing else; on failure it sees a small structured report it can reason about.

Why nothing builds a shell string

The longest comment in the repository sits above files_read and explains why the path is handed to spawn as its own argument rather than interpolated into a command line. It is reproduced here because it is a better argument for argument arrays than any abstract one.

// Pass path as separate argv to spawn (no shell parsing).
// Quoting a path into a command line is not a substitute for this: the
// rules for what a shell re-expands inside quotes are not the rules any
// string-escaping helper implements.
// head executes directly via execvp; path is a literal argv string, no shell sees it.
if (host === 'local') {
  r = await runShell('head', ['-c', String(max), input.path], { timeoutMs: 30_000, maxBytes: max + 1024 });
} else {
  r = await runShell('ssh', ['-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=accept-new',
    host, 'head', '-c', String(max), input.path], { timeoutMs: 30_000, maxBytes: max + 1024 });
}

Routing a command to a machine

machines_command_exec takes a host that may be a device id, an alias, a hostname, an IP or user@host, and resolves it against two inventories fetched in parallel. The routing ladder has five rungs and reports which one it used in the response — every result is prefixed [via <route>].

A companion tool, machines_access_guide, exists purely to answer a question the model would otherwise get wrong: which access route fits a task. It returns no access at all — only a resolved view of the target and a set of recommendations, including the literal command a human should paste into their own terminal for an interactive session. Its caveats section is the honest part: “[Mesh] online, SSH ready, and remote desktop ready are separate states.”

Connecting to it

$ curl -s "$GATEWAY/health"
{"ok":true,"name":"ian-brain","version":"0.3.0","ts":"2026-07-28T00:00:00.000Z"}

$ curl -s -i -X POST "$GATEWAY/mcp" -d '{}'
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
{"error":"invalid_token","error_description":"Missing Authorization header"}

$ curl -s -i -X POST "$GATEWAY/mcp" -H "Authorization: Bearer wrong" -d '{}'
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"
{"error":"invalid_token","error_description":"Token mismatch"}

$ curl -s "$GATEWAY/mcp"
{"error":"method_not_allowed","message":"Stateless mode: use POST /mcp"}

# register it with a client — from the project README
$ claude mcp add --transport http ian-brain "$GATEWAY/mcp" \
    --header "Authorization: Bearer $TOKEN"

Configuration surface

Every operational decision is an environment variable with a default, which is what makes the repository readable without access to the machine it runs on.

Shutting down

SIGTERM and SIGINT both run the same handler: close every federated client, stop accepting connections, exit zero when the server closes. A five-second timer forces exit if that never happens — and it is unref'd, so a clean shutdown is not delayed by the timer it set to guard itself.

Treat it as the authorized access layer for machines, project systems, credentials, memory, wiki, and workspace tools.

src/server.ts:79 — the first line every client reads