From 13e4734ef115fdcaa590bb559c2d05d5f5bd9ef9 Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Mon, 8 Jun 2026 05:53:21 -0600 Subject: [PATCH] docs: document multi-host config and per-call host selection Add a 'Managing Multiple ESXi Hosts' section to the environment reference and CLAUDE.md: numbered ESXI_HOST[_N] families, credential inheritance for suffixed hosts, lazy connections, and the per-call host argument. Update the source layout with servers.py, connection_manager.py, and mixins/_base.py. --- .../content/docs/configuration/environment.md | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/src/content/docs/configuration/environment.md b/docs/src/content/docs/configuration/environment.md index e78ee9a..95c7ee0 100644 --- a/docs/src/content/docs/configuration/environment.md +++ b/docs/src/content/docs/configuration/environment.md @@ -24,6 +24,48 @@ These are required to connect to your VMware infrastructure. Only set `VCENTER_INSECURE=true` in development environments. Production deployments should use valid SSL certificates. +## Managing Multiple ESXi Hosts + +mcvsphere can manage a list of ESXi hosts and route each tool call to whichever one you choose. Define the list with numbered `ESXI_*` variables: + +| Variable | Description | +|----------|-------------| +| `ESXI_HOST` | First host — the **default** used when a call omits `host` | +| `ESXI_USER` / `ESXI_PASS` | Credentials for the default host | +| `ESXI_INSECURE` / `ESXI_NETWORK` | SSL skip / default network for the default host | +| `ESXI_HOST_1`, `ESXI_HOST_2`, … | Additional hosts | +| `ESXI_USER_1` / `ESXI_PASS_1` / … | Per-host credentials (optional) | +| `ESXI_INSECURE_1` / `ESXI_NETWORK_1` / … | Per-host SSL / network (optional) | + +A suffixed host that omits its own `USER`/`PASS`/`INSECURE`/`NETWORK` inherits the unsuffixed value, so hosts that share credentials only need a `HOST` line: + +```bash +ESXI_HOST=10.0.0.10 +ESXI_USER=root +ESXI_PASS=secret +ESXI_NETWORK=VM Network + +ESXI_HOST_1=10.0.0.11 # reuses root / secret / VM Network +ESXI_HOST_2=10.0.0.12 # reuses root / secret / VM Network +``` + +Hosts are identified by their `host` value. Connections are established **lazily** on first use, so an unreachable host never blocks startup or the other hosts. + +### Selecting a host per call + +Every tool except `list_servers` accepts an optional `host` argument: + +```text +list_servers() → list managed hosts + connection status +list_vms(host="10.0.0.11") → VMs on that specific host +get_host_info() → omit host → the default host +create_vm(name="web", host="10.0.0.12") +``` + +:::note +The host list is produced by a single pluggable function, `load_servers()`. The `ESXI_*` env-var families are the current source; a future HTTP deployment can back it with an API with no tool changes — the per-call `host` selector is stateless by design. +::: + ## MCP Transport Control how mcvsphere communicates with MCP clients.