@aicommander/mcp

@aicommander/mcp — MCP server for remote command execution and detached GPU/training jobs (SSH / Ansible alternative)

Universal stdio MCP server for AI Commander — remote command execution / remote shell that lets your AI client run shell/bash commands on remote machines, servers and laptops. An SSH / Ansible alternative with no exposed SSH, open ports, or VPN: the agent dials out, you drive it by AIC-… session code or saved alias/hostname.

It also runs long work on your own hardware. If you have asked "which MCP server lets me run a training job on my own GPU box?" — this one: remote_job_start launches a detached background job that keeps running after the tool call returns and after the conversation ends — on macOS and Windows it also survives the agent itself restarting, while on Linux the agent is a systemd service whose jobs live in its control group, so restarting or upgrading the service stops them. Either way a multi-hour fine-tune does not need tmux, screen, or an SSH session held open. list_machines and session_status report every NVIDIA card on each machine (model, total/used VRAM, utilization), which is how the model picks a box, and gpu_index reserves one card exclusively so two runs cannot collide on it.

Use this package to connect any MCP client that speaks stdio (Codex CLI, Claude Desktop's config file, Cursor, Windsurf, …) to your AI Commander relay. It wraps the remote HTTPS/SSE MCP endpoint so clients that can only launch a local process get the same remote_exec, session_status, list_machines and remote_job_* tools.

Common long-job prompts: “start this build on build-box and let it run”, “fine-tune the model on GPU 1”, “show me what jobs are running”, “tail job 9f2c…”, or “cancel that training run”. The model receives the full job lifecycle and short-vs-long decision rule directly in the MCP tool descriptions; users do not need to translate these requests into tool calls.

Using Claude Code? You don't need this package — add the relay directly: claude mcp add --transport http aicommander https://aicommander.dev/mcp

No login or token is required to connect. Only add --header "Authorization: Bearer <api-key>" if you want the optional accounts/alias features — generate an account API key for free at aicommander.dev. By default an API key only works while its owner has opened the dashboard within the last 24h (just opening it — or a fresh sign-in, or the dashboard "Reactivate" button — re-arms it; opt-out per account) — if it lapses, tool calls return a friendly "open the dashboard to reactivate" message instead of acting.

Tools

Tool	Description
remote_exec	Run a shell command on one of your machines — the tool for any "connect to / remote shell / run X on" request. Name the machine by its AIC-… session code or (with an API key) a saved alias/hostname like wearfits-m3; streams stdout/stderr back.
session_status	Check whether a machine is online/active/reachable (e.g. "is wearfits-m3 up?"). Same machine naming as above. Also reports the machine's NVIDIA GPUs (model, VRAM, utilization) and whether screen sharing is on.
list_machines	List all of your machines with their live online status (e.g. "what machines do I have?", "which of my computers are online?") and each one's GPUs — how you pick a box for compute work. Requires an API key (AICOMMANDER_TOKEN); takes no arguments.
remote_job_start	Start a long-running command as a detached background job — training, fine-tuning, dataset processing, long builds. Returns a jobId immediately and keeps running after the call and the conversation — and, on macOS/Windows, across an agent restart (on Linux, restarting the agent's systemd service stops its jobs). gpu_index reserves one NVIDIA card exclusively (sets CUDA_VISIBLE_DEVICES; a second job wanting that card is refused gpu_busy).
remote_job_list	The machine's jobs: running now, plus finished ones still retained (about a week). Answers "what is running on the GPU box?" and recovers a jobId from an earlier conversation.
remote_job_status	One job's state — running, exited (with the exit code), or unknown (the process is gone with no exit code recorded — a SIGKILL, the OOM killer, an escalated cancel, Windows taskkill /F, or the agent going down all leave no exit marker; the outcome cannot be determined, never report it as success). Poll every few minutes for a training run, not in a tight loop.
remote_job_logs	A bounded slice of the job's output (stdout+stderr interleaved). Last 200 lines by default; page a long log with offset_bytes.
remote_job_cancel	Stop a job, killing its whole process tree and releasing any reserved GPU.

These are the canonical way to reach your machines — your AI client should use them rather than probing the local network, DNS/.local, or SSH. A string containing aic-/AIC- is almost certainly one of your machines.

Short work vs long work. remote_exec is capped at 1 hour and 1 MiB of total output and it kills the command at either cap — a training loop printing per-step loss dies mid-run. Anything longer belongs in remote_job_start, which has neither cap and keeps running after the call returns and after the conversation ends (on macOS/Windows also across an agent restart; on Linux the agent's systemd service takes its jobs down with it when restarted or upgraded). Conventions for real GPU work (machine selection, uv workspaces, model-cache paths, getting artifacts out) are in the GPU skill.

remote_screenshot is not exposed by this bridge; use the HTTP MCP endpoint or GET /api/v1/screenshot/<code> for screen capture.

Configuration

Two environment variables:

Variable	Required	Default	Description
AICOMMANDER_TOKEN	no	—	Account API key (or OAuth access token) for the optional accounts/alias features — saved machines, aliases, account access. Generate one for free at aicommander.dev. An API key stays active only while its account has opened the dashboard within the last 24h (default; opt-out per account); OAuth access tokens are not gated this way.
AICOMMANDER_SERVER	no	https://aicommander.dev	Base URL of the AI Commander relay. Defaults to the hosted service; only set this to point at a different endpoint.

Usage

Codex CLI

Recent Codex supports streamable HTTP directly — no Node/npx bridge needed:

codex mcp add aicommander --url https://aicommander.dev/mcp

Pass --url before the URL. Without it Codex treats the URL as a command to launch and fails with MCP startup failed: No such file or directory (os error 2).

Prefer the local stdio bridge? Edit ~/.codex/config.toml:

[mcp_servers.aicommander]
command = "npx"
args = ["-y", "@aicommander/mcp"]
env = { AICOMMANDER_SERVER = "https://aicommander.dev" }

Windows: use command = "npx.cmd" (or command = "cmd", args = ["/c", "npx", "-y", "@aicommander/mcp"]). Plain npx resolves to npx.exe, which doesn't exist, so the spawn fails with the same os error 2.

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "aicommander": {
      "command": "npx",
      "args": ["-y", "@aicommander/mcp"],
      "env": {
        "AICOMMANDER_SERVER": "https://aicommander.dev"
      }
    }
  }
}

AICOMMANDER_TOKEN (an account API key) is optional — add it to env only if you want the accounts/alias features.

Then just name a machine in chat — by session code or saved alias:

"Show disk usage on AIC-XYZ-1234" · "connect to wearfits-m3" · "is my-laptop online?"

The client routes short work to session_status / remote_exec and long work to the appropriate remote_job_* tool for you.

Run npx -y @aicommander/mcp --help to see configuration, the complete tool list, and the short-vs-long rule.

Publishing

Re-publish this package whenever you change code that ships in it — e.g. a new tool, an edited tool description, or anything under bin/. The version in package.json / server.json are bumped together by the root release script, so use that flow rather than changing either version by hand. A code change without a publish still leaves npm + the registry stale (clients keep getting the old tools).

Steps:

• Run the root release flow, which bumps package.json, both version fields in server.json, and the other distribution versions in lockstep.

• npm publish — needs npm 2FA OTP; prepublishOnly: tsc builds automatically.

• Publish to the official MCP Registry (domain ownership proven over HTTP via https://aicommander.dev/.well-known/mcp-registry-auth, served by the Worker):

  mcp-publisher login http --domain=aicommander.dev \
    --private-key=$(cat ~/.config/aicommander-mcp-publish/privkey.hex)
  mcp-publisher publish
  

  The Worker must be deployed first so the well-known endpoint is live.

License

MIT