# machines-mcp

Production-oriented **Model Context Protocol** server for [Dedalus Machines](https://www.dedaluslabs.ai).

Lets agents create persistent VMs, wait until they are running, execute commands, and run basic diagnostics — without hand-rolled polling loops.

## Tools

| Tool | Description |
|------|-------------|
| `machines_create_and_wait` | Create a machine and block until `running` |
| `machines_get` | Retrieve machine status |
| `machines_list` | List machines |
| `machines_run` | Run a shell command via executions API |
| `machines_sleep` / `machines_wake` | Lifecycle controls |
| `machines_destroy` | Destroy a machine |
| `machines_doctor` | Auth + API + optional machine health check |

## Quickstart

```bash
export DEDALUS_API_KEY=dsk-...
# optional:
# export DEDALUS_BASE_URL=https://api.dedaluslabs.ai
# export DEDALUS_ORG_ID=...

uv sync
uv run python -m src.main
```

Server listens on Streamable HTTP (`:8080` by default).

### Claude / Cursor MCP config

```json
{
  "mcpServers": {
    "dedalus-machines": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.main"],
      "cwd": "/path/to/machines-mcp",
      "env": {
        "DEDALUS_API_KEY": "dsk-..."
      }
    }
  }
}
```

## Design notes

- Built on `dedalus-mcp` (Dedalus MCP framework) + official `dedalus` Python SDK
- Create-and-wait uses client-side polling with timeout / terminal-phase failures
- `machines_doctor` is safe for onboarding: checks key presence, API reachability, lists machines

## License

MIT