@aicommander/mcp

@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 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.
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?"). Requires an API key (AICOMMANDER_TOKEN); takes no arguments.

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

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 is NOT auto-bumped, so a code change without a publish silently leaves npm + the registry stale (clients keep getting the old tools). Easy to forget — don't.

Steps:

• Bump version in both package.json and server.json (keep them in sync).

• 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