Substrate On-Demand GPU — User guide

This guide explains how to connect an MCP client (for example Cursor or Claude Desktop) to the Substrate On-Demand GPU MCP server, what authentication to use, and which tools, resources, and prompts are available.

Agent context

For AI assistants and IDE integrations, download the MCP agent context document (tool summary, provisioning workflow, safety, and MCP resources).

Download agent context

---

Prerequisites

1. Substrate MCP key — Create or copy an mcp_token from the Substrate console (Resources → MCP Keys). The token is sent as Authorization: Bearer <token>.
2. MCP endpoint URL — Hosted service: https://mcp-ondemand.substrate.ai/mcp (service root describes version, mcp_endpoint, and auth in JSON).
3. SSH keys (recommended) — For SSH access to instances, register keys in Substrate (Resources → SSH Keys) and use list_ssh_keys before launching.

---

How to connect

Clients use the streamable HTTP transport. Connect to the MCP URL:

https://mcp-ondemand.substrate.ai/mcp

Authentication: Every request to MCP endpoints must include:

Authorization: Bearer <your-mcp_token>

Paths without a Bearer token return 401, except:

• GET https://mcp-ondemand.substrate.ai/health — liveness (no auth)
• GET https://mcp-ondemand.substrate.ai/ — small JSON describing the service and /mcp (no auth)

Check that the service is up (optional): GET https://mcp-ondemand.substrate.ai/health (no auth).

Cursor (~/.cursor/mcp.json)

Use the url transport and pass your token in headers:

{
  "mcpServers": {
    "substrate-ondemand": {
      "url": "https://mcp-ondemand.substrate.ai/mcp",
      "headers": {
        "Authorization": "Bearer mcp_<your-substrate-token>"
      }
    }
  }
}

Use HTTPS and your real Substrate token in place of mcp_<your-substrate-token>.

Other MCP clients

Any client that supports streamable HTTP + custom headers should use the same pattern: URL = https://mcp-ondemand.substrate.ai/mcp, header = Authorization: Bearer <mcp_token>.

---

Available MCP tools

All tools call Substrate on your behalf using the Bearer token you supplied on the connection.

Tool	Purpose
ping	Verify token and API reachability (run this first when debugging).
list_inventory	List GPU catalog; optional filters (see below).
list_ssh_keys	List organisation SSH keys (for ssh_key_id on launch).
launch_instance	Create a GPU instance (billing starts immediately).
poll_instance_until_active	Wait until the instance is active and get SSH hints.
get_instance	Details for one instance by UUID.
list_instances	All non-deleted instances for the org.
update_instance	Rename and/or replace tags.
delete_instance	Terminate an instance (irreversible — confirm with a human first).

list_inventory parameters (all optional)

Parameter	Meaning
gpu_type	Partial, case-insensitive match (e.g. H100, A4000).
location	Partial region name (e.g. europe, north america).
gpu_count	Exact GPU count (e.g. 1, 4).
max_price	Maximum price per hour in EUR.

launch_instance parameters

Parameter	Required	Notes
inventory_gpu_id	Yes	UUID from list_inventory.
name	Yes	Display name, max 50 characters.
ssh_key_id	No	UUID from list_ssh_keys (recommended).
os	No	From inventory os_options, e.g. ubuntu22.04_cuda12.8.
tags	No	e.g. ["team:ml", "project:v2"].
docker_image	No	If set, launches with Docker (see optional Docker fields).
docker_args	No	Container CLI args.
docker_envs	No	e.g. [{"name": "HF_TOKEN", "value": "hf_..."}].
docker_port_mappings	No	e.g. [{"container_port": 8000, "host_port": 8000}].

poll_instance_until_active parameters

Parameter	Default	Notes
instance_id	—	Required UUID.
timeout_seconds	300	Max wait (seconds).
poll_interval_seconds	10	Polling interval (minimum 5 seconds).

---

Resources

The server exposes MCP resources you can open in supporting clients:

URI	Content
substrate://workflow-guide	Step-by-step workflow for provisioning GPUs (same ideas as below).
substrate://config	Non-secret server metadata (version, transport, retry/timeouts — not your token).

---

Prompts

Prompt	Purpose
launch_gpu_prompt	Optional structured task description (default: train a machine learning model) to guide the assistant through inventory → SSH keys → launch → poll.

---

Recommended workflow (embedded in the server)

1. ping — Confirm token and connectivity.
2. list_inventory — Choose a GPU; note inventory_gpu_id and os_options.
3. list_ssh_keys — Choose ssh_key_id if you need SSH.
4. launch_instance — Start the instance.
5. poll_instance_until_active — Wait until active; use the returned SSH information.
6. Connect with your SSH client (for example ssh substrate@<ip> -p 22 -i ~/.ssh/your-key).
7. delete_instance only after explicit human confirmation — termination is irreversible and billing rules apply on Substrate’s side.

Status flow: creating → pending → active → deleting → deleted.

Regions (for inventory filters): Europe, North America, Asia Pacific, Australia, South America, Middle East, Africa.

---

Troubleshooting

Symptom	What to check
401 Unauthorized	Missing or wrong Authorization: Bearer header.
400 Token too large	Authorization value exceeds the server’s maximum size.
Substrate 401 / “token invalid”	Regenerate or fix the MCP key in Substrate (Resources → MCP Keys).
404 on API	Wrong UUID or resource belongs to another organisation.
Cannot reach /mcp	Use https://mcp-ondemand.substrate.ai/mcp and check TLS / network.
Health fails	Try https://mcp-ondemand.substrate.ai/health; if it fails, the service may be unavailable.

---

Quick reference — endpoints

Host: https://mcp-ondemand.substrate.ai

Method	Path	Auth
GET	https://mcp-ondemand.substrate.ai/health	No
GET	https://mcp-ondemand.substrate.ai/	No
MCP	https://mcp-ondemand.substrate.ai/mcp	Yes (Bearer)

---

Version

The GET /health and GET / responses include the running server version string.