Example tasks for the AI assistant and the permissions they need

Ready-to-use requests for servers, SSH keys, orders and your balance, with the tools used and the permissions the token must have.

Here you will find ready-to-use requests for the AI assistant connected to your account through MCP (https://api.app.blackbox.md/mcp). For each task, you can see the tools the assistant calls and the permissions the token needs. You choose the permissions when you create the token, in “Contul meu” (My account) → “Token-uri API” (API tokens) (blackbox.md/account/api-tokens).

Available to: the holder of the blackbox.md account, with an AI assistant connected through an API token (Connecting in the Claude app (custom connector) or Connecting from Claude Code, Cursor, VS Code and other clients).

The blackbox.md website is available in Romanian and Russian; this article quotes the Romanian labels with their English meaning.

Start with “Call whoami”

At the start of every session, write to the assistant: “Call whoami”. The whoami tool needs no permission.
The assistant confirms that the token works and shows you which permissions it has (scopes) and which ones are missing (missing_scopes). If nothing is missing, the tool replies “All scopes granted — every tool is available.”
If a permission your task needs is missing, create a new token with that permission and replace the old one in the AI client. You cannot add permissions to an existing token. See Token permissions (scopes).

Tools the token has no permission for do not even appear in the assistant's list. That is why the assistant sometimes simply says it “doesn't have” the right tool.

The examples on blackbox.md/info/mcp

The blackbox.md/info/mcp page publishes three example requests. In English, they read:

Show me my BLACKBOX servers and their status
What is my balance, and which invoices are unpaid?
Install nginx on my server

You will also find them in the tables below, with the permissions they need.

The permissions in the tables

Code	Checkbox in the “Token nou” (New token) form	Ticked by default
`servers:read`	“Citește lista și statusul serverelor mele” (Read the list and status of my servers)	yes
`billing:read`	“Citește soldul, facturile și comenzile” (Read the balance, invoices and orders)	yes
`ssh_keys:read`	“Citește lista cheilor mele SSH” (Read the list of my SSH keys)	yes
`servers:power`	“Controlează alimentarea serverelor (repornire/oprire/pornire)” (Control server power (reboot/stop/start))	no
`servers:credentials`	“Vizualizează parolele/accesul serverelor” (View server passwords/access)	no
`servers:exec`	“Rulează orice comandă ca root pe serverele mele” (Run any command as root on my servers)	no
`orders:write`	“Plasează și modifică comenzi în numele meu” (Place and change orders on my behalf)	no

The “AI-administrator — acces complet” (AI administrator — full access) button ticks all the permissions, including “Adaugă și șterge cheile mele SSH” (Add and delete my SSH keys) (ssh_keys:write).

Ready-to-use tasks

Write the task in your own words: the requests below are only templates. If you have several servers, name the server (its name in the panel or its IP address). The assistant finds it on its own with list_servers, which is why tasks on a server also need servers:read.

Reading

Task	What you write	Tools	Permissions
Your servers and their status	“Show me my BLACKBOX servers and their status”	`list_servers`, `get_server`	`servers:read`
Balance and unpaid invoices	“What is my balance, and which invoices are unpaid?”	`get_balance`, `list_invoices`	`billing:read`
Latest transactions	“Show me the last 10 transactions on my balance”	`list_transactions`	`billing:read`
Plans and prices	“What VPS plans do you have with 4 vCPU, and how much do they cost?”	`list_vm_plans`	none

Servers and access

Task	What you write	Tools	Permissions
Restart with a check	“Restart my server and tell me when it responds again”	`power_server`, then `get_server`	`servers:power`, `servers:read`
Disk space	“Show me how much disk space is used on my server and the 20 largest directories”	`run_server_command`	`servers:exec`, `servers:read`
Installing nginx	“Install nginx on my server”	`run_server_command`	`servers:exec`, `servers:read`
Only the laptop key, no password	“On my server, keep only the ‘Laptop’ SSH key from my account and turn off password login. Show me first what you will do, and wait for my confirmation.”	`list_ssh_keys`, `add_server_ssh_key`, then `set_server_password_auth`; for the other keys, `list_server_ssh_keys` and `remove_server_ssh_key`	`servers:credentials`, `servers:read`, `ssh_keys:read`
Deleting an old key	“Which SSH keys are installed on my server? Delete the one named old-laptop.”	`list_server_ssh_keys`, then `remove_server_ssh_key`	`servers:credentials`, `servers:read`
SSH command for rsync	“Give me an SSH command so I can copy files to my server with rsync”	`get_server_ssh_access`	`servers:credentials`, `servers:read`

Restart: power_server only accepts the request. The assistant then checks with get_server that power_state is running. SSH and your services may need another 30–60 seconds.
Keys: on the server, a key is recognized by the comment at the end of its line (for example old-laptop). Keys saved on the “Chei SSH” (SSH keys) page are found by the assistant by name, with list_ssh_keys. “Management key (blackbox.md)” always stays on the server and cannot be deleted.
rsync: the assistant receives a dedicated SSH key, which BLACKBOX installs on the server, and a ready-to-use ssh command. Details: SSH access and SSH keys through the AI assistant.

Money and orders

Task	What you write	Tools	Permissions
Quote for a new server	“Prepare a quote for a Standard M server with Ubuntu 24.04 and my SSH key, then wait for my confirmation”	`list_vm_plans`, `list_ssh_keys`, `create_order` without confirmation	`orders:write`, `ssh_keys:read`
Paying for an order	“Pay for order BBX-2026-000123 from my balance”	`list_orders`, then `pay_order`	`orders:write`, `billing:read`
How much a cancellation refunds	“How much would I get back if I cancel order BBX-2026-000123? Don't cancel anything yet.”	`list_orders`, then `cancel_order` without confirmation	`orders:write`, `billing:read`
Upgrade after checking the price	“Upgrade my server to the next plan, but show me the price first”	`get_server_resize_options`, then `resize_server` without confirmation	`servers:read`, `orders:write`

Quote: without confirmation, create_order only calculates the total and creates nothing. Once you agree, the assistant repeats the call with confirm=true, and the order appears in “Comenzi” (Orders) with the status “Nou” (New). Money is taken only at pay_order.
Payment and cancellation: the assistant finds the order by its number with list_orders, which also gives it the current total that pay_order requires.
Upgrade: only to a larger plan in the same family, paid from your balance. When you confirm, the server restarts, and the downtime lasts a few minutes.

All the details: Orders, payments, cancellations and upgrades via AI.

Money and irreversible actions: ask for a preview first

The instructions BLACKBOX gives the assistant set when it asks for your consent and when it acts directly. They are instructions, not a technical lock, so ask for the pause in your message as well.

Situation	What the assistant does
Money: placing the order (`create_order` with `confirm=true`), payment (`pay_order`), upgrade (`resize_server` with `confirm=true`)	asks for your confirmation
Data and access: canceling the order (`cancel_order` with `confirm=true`), deleting a key from the server, turning off password login, replacing the assistant's SSH access key	asks for your confirmation
Everything else: reading data, commands on the server, installing software, a restart you asked for	acts directly and tells you the result

How to work safely:

Ask for the quote or the preview first, and add “wait for my confirmation” to your request.
Read what the assistant shows you: the total in MDL, the plan and the operating system; for a cancellation, the amount returned to your balance and whether a server will be deleted; for keys, which keys stay on the server.
Confirm explicitly, in a separate message.
When the AI client asks you to approve the call, check that the parameters are the ones you confirmed.

Requests that stop the assistant before the important step:

Prepare a quote and wait for my confirmation before placing or paying for the order.
Show me only the cancellation preview, without confirming anything.
Tell me which keys you will delete and what stays on the server, then wait for my confirmation.
Show me the command you want to run and wait for my confirmation.

Important The approval window is shown by the AI client, not by BLACKBOX. Do not choose the option to always allow tools without asking, especially for create_order, pay_order, cancel_order, resize_server, remove_server_ssh_key, set_server_password_auth and run_server_command. Before you turn off password login, check in a new terminal that you can connect with your own key: customers have no web or VNC console (Enabling and disabling SSH password login).

Irreversible If an order has a server, confirming its cancellation deletes the server immediately, with all its data, with no grace period. Always ask for the preview first: Orders, payments, cancellations and upgrades via AI.

Long tasks

The assistant waits at most 300 seconds for a single command on the server (60 by default). When the time runs out, the result comes back with timed_out: true, and the command may keep running on the server. For long jobs (a system update, a backup, a build), explicitly ask for them to start in the background, with nohup or systemd-run:

Start a system update on my server in the background with nohup, with the output in /root/upgrade.log, and don't wait for it to finish.

Later:

Check whether the update on my server has finished and show me the last 30 lines of /root/upgrade.log.

After timed_out: true, do not ask for the same command to be repeated: ask for a check first. Details: Running commands on the server through AI.

What the assistant cannot do

Task	Where to do it
Support tickets	blackbox.md, “Contul meu” (My account) → “Ajutor și suport” (Help and support): Opening a support ticket
Topping up your balance	blackbox.md: Topping up your balance
Paying invoices	Automatic payment of invoices from your balance or Paying by bank transfer and BLACKBOX bank details
DNS records	the app.blackbox.md panel: Managing DNS records from the panel
Monitoring and alerts	the panel: The “Monitoring” page
Renaming the server	the panel: Renaming a server (private name)
Reinstalling the operating system	on request, through support: Available operating systems

The full list: AI integration (MCP): what it is and what it can do.

Frequently asked questions

The assistant says it doesn't have the right tool, or it gets missing_scope. What do I do? The token lacks the permission it needs; the error names it. Create a new token with that permission and replace the old one in the AI client: API tokens: creating, copying and revoking.

Do I have to give the assistant the server's id? No. Refer to the server by its name or IP address; the assistant takes the id from list_servers. For this, the token needs servers:read.

Can I use a single token for all the examples? Yes, with “AI-administrator — acces complet” (AI administrator — full access). It is safer to use a read-only token day to day and to create a full-access token only when you need it: Token and AI agent security.

The assistant gets rate_limited. Why? You went over a tool's limit. Previews count too: create_order accepts 20 calls per hour, cancel_order 5 in 5 minutes, resize_server 3 in 10 minutes. Wait, and do not repeat the call in a loop: MCP limits and error codes.