@aicommander/mcp — MCP server for remote command execution (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.

Use this package to connect any MCP client that speaks stdio (Codex CLI, Claude Desktop's config file, Cursor, Windsurp, …) 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 and session_status tools.

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 signed in to the dashboard within the last 24h (a sign-in or the dashboard "Reactivate" button re-arms it; opt-out per account) — if it lapses, tool calls return a friendly "sign in 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. |

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.

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 signed in to 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 it to session_status / remote_exec for you.

License

MIT