# AI agents (MCP)

639 Shell has an MCP server, so any MCP agent (Claude Code, Codex, Cursor, VS Code Copilot,
Gemini CLI, Muse Code, Claude Desktop and the rest) can create machines, run code in them and delete them by
itself, dozens at a time, within your account's limits.

## Connect an agent

The server is a standard MCP server over SSH: your agent runs `ssh` and talks MCP over it. Your
SSH key is the login, so there's no token to paste. The app's **Connect an agent** screen shows
each of these for your account, with `c` to copy.

| Agent | Setup |
|---|---|
| Claude Code | `claude mcp add 639 -- ssh -T -o BatchMode=yes mcp@shell.639cloud.com` |
| Codex | `codex mcp add 639 -- ssh -T -o BatchMode=yes mcp@shell.639cloud.com` |
| Cursor | `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project): the JSON below |
| VS Code (Copilot) | `.vscode/mcp.json`: the JSON below, with `"servers"` for `"mcpServers"` and `"type": "stdio"` |
| Claude Desktop | `claude_desktop_config.json` (Settings → Developer → Edit Config): the JSON below |
| Gemini CLI | `~/.gemini/settings.json`: the JSON below |
| Muse Code (Meta) | `~/.config/muse/settings.json`: `{"schema_version": 1, "mcp_servers": {"639": {"transport": "stdio", "command": "ssh", "args": [the args below], "mode": "optional"}}}` |
| Anything else | any MCP client that can run a local (stdio) server: command `ssh`, the arguments below |

```json
{
  "mcpServers": {
    "639": {
      "command": "ssh",
      "args": ["-T", "-o", "BatchMode=yes", "mcp@shell.639cloud.com"]
    }
  }
}
```

- `BatchMode=yes` means ssh never stops to ask a question: your key needs to be loaded in your
  SSH agent (or have no passphrase).
- If a session drops, reconnect the server in your agent (in Claude Code: `/mcp`, then `639`).
  After a 639 Shell update, an open session gets a warning a few minutes before it closes;
  agents connected over HTTPS keep working without reconnecting.
- Notes an agent leaves are labelled with the agent's own name, e.g. "Cursor via MCP · Ana Ruiz".

## From claude.ai, ChatGPT and other web agents (beta)

Agents that run in a browser or in the cloud can't use your SSH key, so they connect over HTTPS
instead, at `https://api.shell.639cloud.com/mcp`. Beta: accounts not on the beta yet are refused
(`403`).

- **claude.ai:** Settings → Connectors → **Add custom connector**, paste the URL.
- **ChatGPT:** Settings → Connectors → **Create**, paste the URL.

A 639 page opens: sign in the way you signed up (**Continue with Google**, or, for an account
made with an approval code, **Email me a sign-in code** and type the 6-digit code), check where
it will send you back to, and **Allow**. The agent gets **full access** to your account, the same tools as
above: it can create, run commands in, resize, sleep and delete your machines, read and write
their files, and leave notes. Rules your account requires still apply.

See what's connected, and disconnect any of it, in the app (**Agents → API keys → Connected agents**) or
from a terminal:

```sh
ssh keys@shell.639cloud.com connections
ssh keys@shell.639cloud.com disconnect g_… --yes
```

A connection that isn't used for 30 days ends by itself. Up to 10 at a time.

## From any HTTPS client

Coding tools, scripts and hosted agent platforms that speak MCP over HTTPS (Streamable HTTP) use
the same URL with an API key: `Authorization: Bearer 639_…` (make one with
`ssh keys@shell.639cloud.com new NAME`). Beta: accounts not on the beta yet get `403`.

## What an agent can do

| Tool |
|---|
| `list_notifications` |
| `whoami` |
| `list_connected_agents` |
| `list_machines` |
| `create_machine` |
| `exec` |
| `write_file` / `read_file` |
| `resize` |
| `restart` |
| `rename_machine` |
| `create_machine_from_url` |
| `boot_log` |
| `protect_machine` |
| `sleep` / `delete` |
| `set_auto_sleep` |
| `set_lifetime` |
| `set_labels` |
| `set_isolated_memory` |
| `set_network` / `set_inbound` |
| `history` |
| `vpc_create`, `vpc_list`, `vpc_delete` |
| `machine_vpc_attach`, `machine_vpc_detach` |
| `ip_reserve`, `ip_list`, `ip_release` |
| `machine_ip_attach`, `machine_ip_detach` |
| `create_api_key`, `list_api_keys`, `revoke_api_key` |
| `list_notes`, `add_note`, `edit_note`, `delete_note` |
| `get_rules`, `ack_rules` |

Beta accounts also get:

| Tool | Does |
|---|---|
| `snapshot_machine`, `list_snapshots`, `restore_snapshot`, `delete_snapshot` | save a machine's exact state and put it back (see Snapshots and undo); `exec` also takes `checkpoint` |
| `fork_machine` | a new machine from a snapshot, or from a machine as it is now; `count` makes up to 50 at once, and `secrets`, `labels`, `lifetime_minutes` apply to each (see Forking) |
| `create_template`, `list_templates`, `fork_template` | name a machine's snapshot for the org, and make machines from it (see Forking) |
| `set_history` | a restore point every time the machine sleeps |
| `create_link`, `list_links`, `delete_link`, `sign_in_link` | HTTPS links that wake a machine (see Web links) |

**Limits.** Each person's agents make up to 20 calls a second (bursts to 40), and delete (or give
a lifetime to) at most 5 existing machines that aren't sandboxes in any 10 minutes, shared with
their API keys; past that, a person does it in the app.

## Watch what your agents do

**Agents → Activity** in the app is the account's history as it happens: every action on a
machine, newest first, with when it happened, who did it (an agent, the API, the app, `ssh`, or
639 Shell itself: auto-sleep, a sandbox's lifetime ending), what, which machine, and whether it
worked. It updates by itself while it's open. The same history is the `history` tool for an
agent and `GET /v1/history` in the API.

## Tips

- Machines sleep between an agent's steps, so a fleet of idle agent machines costs nothing.
- For a long job, have the agent start it with `nohup keepawake CMD > log 2>&1 &` and check the
  log later.
- `history` shows exactly what the agent did and when.