aion-mcp (mcpbuilder)

A Model Context Protocol server that gives an MCP client (Claude Desktop, Codex, etc.) a single set of tools for driving the AION assistant stack and the surrounding home fleet. It speaks MCP over stdio and is spawned on demand by the client — there is no long-running daemon to manage.

It is the client half of the aion-suite integration: aion-mcp calls aion-core (Flask, 127.0.0.1:5000), which in turn talks to Ollama and Postgres.

MCP client (Claude Desktop / Codex)
        │  stdio
        ▼
   aion-mcp  ──HTTP──▶  aion-core (Flask :5000)  ──▶  Ollama (GPU) + Postgres
        │
        └──SSH──▶  fleet machines (draydev / ec2) + Kali container

Tool groups

Tools are organized into modules under src/, exposing ~45 tools total:

Related MCP server: mcp-ssh-multi

Build & run

npm install
npm run build     # tsc → dist/
npm start         # node dist/index.js  (stdio server)
npm run dev       # tsx src/index.ts     (no build step)
npm run gateway   # node dist/fleet-gateway.js  (read-only fleet status over HTTP :5100)

Fleet gateway

fleet-gateway.ts is a tiny read-only HTTP service (localhost :5100) that exposes the same fleet_status probe used by the MCP fleet_status tool, so a web page can read machine/agent health even though the MCP server itself is stdio-only. It backs AION's /fleet topology page and chat control hook.

• GET /health, GET /fleet/status — read-only, background-refreshed cache (fast page loads).

• POST /fleet/run, POST /fleet/review — guarded writes wrapping fleet_run / fleet_review.

Writes are gated: if FLEET_GATEWAY_TOKEN is set they require a matching x-fleet-token header (the status probe stays open); set FLEET_GATEWAY_WRITE=off to disable writes entirely. AION stages a confirmation before calling the write endpoints. Config: FLEET_GATEWAY_PORT (5100), FLEET_GATEWAY_HOST (127.0.0.1), FLEET_GATEWAY_TTL_MS (120000), FLEET_GATEWAY_TOKEN, FLEET_GATEWAY_WRITE.

The compiled dist/ is committed so the server runs via npx/node dist/index.js without a build step on the client machine.

Configuration

All host-specific values and secrets come from the environment — nothing sensitive is committed. .env and claude_desktop_config.json are git-ignored; there are no hardcoded credential fallbacks (an unset secret disables the affected tool with a clear error rather than falling back to a real password).

Claude Desktop

Register the server in claude_desktop_config.json (kept local, not committed):

{
  "mcpServers": {
    "aion": {
      "command": "node",
      "args": ["/mnt/c/projects/mcpbuilder/dist/index.js"],
      "env": {
        "AION_SERVICE_TOKEN": "…",
        "AION_SESSION_TOKEN": "…"
      }
    }
  }
}

To get AION_SESSION_TOKEN: log in to AION at http://127.0.0.1:5000, open DevTools → Application → Cookies, and copy the aion_token value.

Security notes

• No secrets in the repo: .env and claude_desktop_config.json are ignored and were scrubbed from history; committed source has no credential fallbacks.

• aion_memory_browse and all session-scoped tools require AION_SESSION_TOKEN — they do not silently run unauthenticated.

• kali_* and fleet_* run commands on remote hosts over SSH and are intended for the author's own lab/home fleet only.

Status

Built and tested working end-to-end against a live AION stack — see aion-suite/QA_MCP_AION_FLEET_REPORT.md (45 tools registered, service + session endpoints passing, fleet fan-out verified).