Provisioning a VPS end-to-end
This guide walks the full flow: pick a plan, register an SSH key, place the
order, wait for provisioning, log in. Every step has a curl example, a
vpsctl example, and a note about the equivalent MCP tool.
0. Prerequisites
You need a Personal Access Token (PAT) with the
servers:provision, orders:write, ssh_keys:write, catalog:read, and
operations:read scopes. Create one at
my.vps-server.host → API tokens
or run vpsctl auth login and paste it in.
export VPSH_API_TOKEN=pat_live_...
1. Browse the catalog
List every product you can order. The response is grouped by category (VPS, dedicated, hosting, ...).
curl https://api.vps-server.host/v1/catalog \
-H "Authorization: Bearer $VPSH_API_TOKEN"
vpsctl catalog list
Pick a product id, then fetch its full detail to see the pricing matrix and configurable-option groups (region, image, RAM tiers, ...):
curl https://api.vps-server.host/v1/catalog/products/24 \
-H "Authorization: Bearer $VPSH_API_TOKEN"
vpsctl catalog get 24
Each configurable_options[] entry has an id (use as group_id) and
a list of options[] each with their own id (use as choice_id). The
role field marks groups that configure region (role: region) or OS
image (role: image) — handy if you want to filter UI dropdowns.
2. Register an SSH key
If you haven't already, upload your public key. We store only the public half.
curl https://api.vps-server.host/v1/ssh-keys \
-H "Authorization: Bearer $VPSH_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "laptop-2026",
"public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIM... me@laptop"
}'
vpsctl ssh-keys create --name laptop-2026 --key-file ~/.ssh/id_ed25519.pub
Note the returned id (looks like key_01HRZQ...). You'll pass it to
the order in the next step.
3. Preview the order
Before charging anything, get the exact total — line items, discount, tax, grand total — for the configuration you want:
curl https://api.vps-server.host/v1/orders:preview \
-H "Authorization: Bearer $VPSH_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"product_id": "24",
"billing_cycle": "monthly",
"region": "coc_42",
"image": "coc_99",
"hostname": "web-01.example.com",
"ssh_keys": ["key_01HRZQ..."]
}'
vpsctl orders preview \
--product-id 24 \
--billing-cycle monthly \
--region coc_42 \
--image coc_99 \
--hostname web-01.example.com \
--ssh-key key_01HRZQ...
The response includes a quote_token. Pass it to create within
5 minutes to lock these numbers even if catalog pricing changes in between.
4. Place the order
Two paths, depending on how complex the order is.
Express path: vpsctl servers create
For the common case ("one VPS, this plan, this region, this image") use
POST /servers. One call places the order, auto-pays from your default
payment method, and starts provisioning.
curl https://api.vps-server.host/v1/servers \
-H "Authorization: Bearer $VPSH_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen | tr A-Z a-z)" \
-H "X-Confirm-Token: cft_..." \
-d '{
"product_id": "24",
"billing_cycle": "monthly",
"region": "coc_42",
"image": "coc_99",
"hostname": "web-01.example.com",
"ssh_keys": ["key_01HRZQ..."],
"payment_method": "credit"
}'
vpsctl servers create \
--product-id 24 \
--billing-cycle monthly \
--region coc_42 \
--image coc_99 \
--hostname web-01.example.com \
--ssh-key key_01HRZQ... \
--payment-method credit
The response includes the new server (in provisioning state) and an
operation. Note the operation_id — that's what you poll.
Full path: vpsctl orders create
For orders with multiple configurable options beyond plan/region/image,
addons, or a promo code, use POST /orders instead:
vpsctl orders create \
--product-id 24 \
--billing-cycle monthly \
--region coc_42 \
--image coc_99 \
--option cog_15=coc_88:4 \
--addon 7 \
--promo SUMMER25 \
--quote-token quo_... \
--payment-method credit \
--auto-accept
--option group_id=choice_id is repeatable; append :N for
quantity-type options. --auto-accept forces synchronous provisioning
when the invoice auto-pays.
5. Wait for provisioning
createServer and createOrder (with auto_accept: true) both return an
operation envelope. Poll it until it reaches a terminal state.
curl https://api.vps-server.host/v1/operations/op_... \
-H "Authorization: Bearer $VPSH_API_TOKEN"
vpsctl operations wait op_... --timeout 5m
wait blocks until status is succeeded, failed, or cancelled, with
exponential-backoff polling (2s → 8s). When it returns succeeded, the
server is ready.
See async operations for the full state machine and webhook alternatives.
6. Get connection details
Re-fetch the server — once provisioned, status is running and the IP
fields are populated:
curl https://api.vps-server.host/v1/servers/srv_... \
-H "Authorization: Bearer $VPSH_API_TOKEN"
vpsctl servers get srv_...
For the root password — note it's audit-logged every time you reveal it:
vpsctl servers password reveal srv_...
7. Set PTR (reverse DNS)
If you'll send email from this server, set its PTR record so the IP resolves back to your hostname:
vpsctl ptr list srv_...
vpsctl ptr set srv_... dnsp_... web-01.example.com
See the PTR guide for the gotchas.
8. First SSH login
ssh -i ~/.ssh/id_ed25519 root@<ipv4>
The SSH key you uploaded in step 2 is in the server's
/root/.ssh/authorized_keys — no password prompt.
MCP equivalents
Every step above maps to an MCP tool, in the same order:
| API call | MCP tool |
|---|---|
GET /catalog | list_catalog |
GET /catalog/products/{id} | get_catalog_product |
POST /ssh-keys | create_ssh_key |
POST /orders:preview | preview_order |
POST /servers | create_server (destructive — asks for confirmation) |
POST /orders | create_order (destructive — asks for confirmation) |
GET /operations/{id} | wait_for_operation |
GET /servers/{id} | get_server |
| Reveal root password | reveal_server_password (audit-logged) |
| Set PTR | set_ptr_record |
Destructive MCP tools either elicit a native confirmation form (Claude
Code ≥2.1.76) or return a ConfirmationRequired error that the assistant
relays to you before retrying with confirm: true. See
step-up auth for how X-Confirm-Token
flows in.
What's next
- Async operations — how to poll, retry, and subscribe.
- Webhooks — get notified when
operation.succeededfires. - Production checklist — what to do before you put real traffic on it.