Skip to main content

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 callMCP tool
GET /cataloglist_catalog
GET /catalog/products/{id}get_catalog_product
POST /ssh-keyscreate_ssh_key
POST /orders:previewpreview_order
POST /serverscreate_server (destructive — asks for confirmation)
POST /orderscreate_order (destructive — asks for confirmation)
GET /operations/{id}wait_for_operation
GET /servers/{id}get_server
Reveal root passwordreveal_server_password (audit-logged)
Set PTRset_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​