# Substrate On-Demand GPU — MCP agent context

You are using the **Substrate On-Demand GPU** MCP server. It forwards your tool calls to Substrate’s on-demand GPU API with the **user’s Substrate MCP token** (Bearer on the connection). The server does not store that token.

- **Public MCP endpoint:** `https://mcp-ondemand.substrate.ai/mcp`
- **Service root (no auth):** `https://mcp-ondemand.substrate.ai/`

Do **not** print, log, or repeat full API tokens in replies.

---

## Tool summary

| Tool | Use |
|------|-----|
| `ping` | **Always run first** when debugging connectivity or auth. |
| `list_inventory` | Find GPU offers; read `inventory_gpu_id` and `os_options`. |
| `list_ssh_keys` | Get `ssh_key_id` for launches that need SSH. |
| `launch_instance` | Creates an instance — **billing starts immediately**. |
| `poll_instance_until_active` | After launch; wait until `active`, then share SSH hints. |
| `get_instance` | One instance by UUID. |
| `list_instances` | All non-deleted instances for the org. |
| `update_instance` | Rename and/or replace tags (at least one field). |
| `delete_instance` | **Irreversible** termination — see safety below. |

---

## Provisioning workflow (quick reference)

<!-- workflow-guide-start -->
## Substrate On-Demand GPU — Workflow

1. `ping()` → verify token + API reachability  
2. `list_inventory(gpu_type="H100")` → pick `inventory_gpu_id` + `os` from `os_options`  
3. `list_ssh_keys()` → pick `ssh_key_id` (recommended)  
4. `launch_instance(...)` → status becomes `creating`  
5. `poll_instance_until_active(instance_id="...")` → wait until `active`, returns `ssh_command`  
6. User SSH: `ssh substrate@<ip_address> -p 22 -i ~/.ssh/your-key`  
7. `delete_instance(instance_id="...")` → terminates + stops billing (**IRREVERSIBLE**)

**Status flow:** `creating` → `pending` → `active` → `deleting` → `deleted`

**Rules:** Billing starts at launch; final hour charged on deletion. **Always confirm with the user before `delete_instance`.**  
**`max_price` (inventory filter)** is **EUR/hour**.  
**Regions (filters):** Europe, North America, Asia Pacific, Australia, South America, Middle East, Africa.

<!-- workflow-guide-end -->

---

## `list_inventory` (optional filters)

- `gpu_type` — partial case-insensitive match (e.g. H100, A4000)  
- `location` — partial region (e.g. `europe`, `north america`)  
- `gpu_count` — positive integer  
- `max_price` — max **EUR/hour** (must be greater than 0 if set)

---

## `launch_instance`

**Required:** `inventory_gpu_id` (UUID), `name` (non-empty, ≤ 50 characters).

**Optional:** `ssh_key_id` (UUID), `os` (from inventory, e.g. `ubuntu22.04_cuda12.8`), `tags` (list of strings).

**Optional Docker launch:** set `docker_image`; then optionally `docker_args`, `docker_envs` (e.g. `[{"name":"HF_TOKEN","value":"hf_..."}]`), `docker_port_mappings` (e.g. `[{"container_port":8000,"host_port":8000}]`).

After a successful launch, call **`poll_instance_until_active`** unless the user only needs the instance ID.

---

## `poll_instance_until_active`

- `instance_id` (UUID, required)  
- `timeout_seconds` (default 300)  
- `poll_interval_seconds` (default 10, minimum 5)

If it times out, use `get_instance` to inspect status.

---

## Safety & cost

1. **`delete_instance`** — Destructive and **irreversible**. Only call after **explicit user confirmation**. Remind the user to save data first.  
2. **`launch_instance`** — Starts billing at once. For expensive SKUs, confirm budget with the user when appropriate.  
3. Treat instance IDs and org data as sensitive; do not assume resources are shareable across organisations.

---

## MCP resources (optional reads)

| URI | Content |
|-----|---------|
| `substrate://agent-context` | This full document |
| `substrate://workflow-guide` | Short provisioning workflow (marked section above) |
| `substrate://config` | Non-secret server metadata (version, transport, timeouts — **not** secrets) |

---

## Prompts

The server may expose **`launch_gpu_prompt`** to structure a training/inference style GPU request — follow its steps when the user invokes it.