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:

Module	Tools	What it does
aion-api-tools.ts	aion_api_chat, aion_channels, aion_channel_history, aion_channel_presence, aion_activity, aion_memory_browse, aion_admin_*, aion_vast_*, aion_admin_network_run	AION Core HTTP API: service chat, channels/presence, activity feed, fact-memory browse, admin, and Vast.ai GPU orchestration
memory-tools.ts	memory + conversation/profile tools	Read/write AION's SQLite-backed memory and conversation history
chat-tools.ts	chat/image/model tools	Direct chat, image generation, and model endpoints
sonchat-tools.ts	sonchat_*	Bridge to the sonchat service
portal-tools.ts	portal_*	Portal service endpoints
fleet-tools.ts	fleet_status, fleet_run, fleet_review	Fan out agent runs across wsl / draydev / ec2 over SSH
kali-tools.ts	kali_*	Run security tooling inside a Kali Docker container over SSH
system-tools.ts	system_status, …	Local host/service status

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).

Variable	Used by	Default	Notes
AION_HOST / AION_PORT	aion-api	127.0.0.1 / 5000	AION Core Flask API
AION_SERVICE_TOKEN	aion_api_chat	—	X-Aion-Service-Token for /api/service/chat; no user session needed. Required — chat is disabled if unset
AION_SESSION_TOKEN	session-scoped aion tools	—	Value of the aion_token cookie after logging in; required for channels/activity/memory/admin/vast tools
KALI_HOST / KALI_USER / KALI_PASS / KALI_IMAGE	kali	192.168.0.200 / draygen / — / kali-custom:latest	KALI_PASS required; kali tools return an error if unset
FLEET_DRAYDEV_HOST / FLEET_DRAYDEV_USER / FLEET_DRAYDEV_PASS	fleet	derived / draygen / —	draydev SSH; if no password/SSH string is configured the machine is skipped with a clear error
FLEET_EC2_SSH, FLEET_TIMEOUT_MS, FLEET_MAX_DEPTH	fleet	— / 180000 / 2	ec2 SSH string; per-run timeout; recursion guard on delegated fleet runs

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).