List of MCP tools

All 25 tools of the BLACKBOX MCP server: the permission each one requires, its parameters, what it returns and its limits.

The blackbox MCP server (https://api.app.blackbox.md/mcp) gives your AI assistant 25 tools. The assistant picks the right tool on its own once you describe the task; you decide which tools it may use through the token's permissions. You create the token on blackbox.md, under “Contul meu” (My account) → “Token-uri API” (API tokens), at blackbox.md/account/api-tokens.

Available to: the blackbox.md account holder, through an AI assistant connected with an API token. The tools work only with the data of the account that created the token.

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

How to read the tables

Permission: the code of the permission the token must have; “—” means no permission is needed. To see which checkbox on the “Token-uri de acces (API)” (Access tokens (API)) page matches each code, read Token permissions (scopes).
Parameters: the data the assistant sends to the tool. You don't type them yourself, but it helps to recognize them when your AI client asks you to approve a call.
Limit: how many calls are allowed for the whole account, across all its tokens combined. These limits are counted separately from those of the app.blackbox.md panel. In addition, all tools except whoami and list_vm_plans share a combined limit of 120 calls per minute.
Amounts: …_mdl fields are in whole MDL, and …_bani fields are in bani, hundredths of a leu (1 MDL = 100 bani).

Common behavior

Situation	Tool response	What to do
The token doesn't have the required permission	The tool doesn't appear in the assistant's list; a direct call gets `missing_scope: this token does not have '…'`, with the permission name.	Create a new token with the missing permission: you can't add permissions to an existing token.
The ID doesn't exist or belongs to another account	`not_found`, deliberately the same response in both cases	Ask the assistant to take the ID from `list_servers`, `list_orders` or `list_ssh_keys`.
The ID has the wrong format	`invalid_server_id`, `invalid_order_id` or `invalid_key_id`	Same as above.
Too many calls	`rate_limited`	Wait: calls made while the limit is exceeded also count.
Unexpected error at BLACKBOX	`internal_error`	Retry once at most. If it happens again, write to support with the tool name and the time.
During an upgrade or the cancellation of an order with a server, the infrastructure service is temporarily unavailable	an error reporting this unavailability	Retry in a few minutes.

Besides the servers you ordered, list_servers may also show company servers that BLACKBOX has given you access to. When can_manage is false, the server is read-only (in the panel it has the “Managed” badge), and the control tools don't work on it. If BLACKBOX has granted you management rights, the capabilities field shows the allowed actions; upgrades are not available for these servers.

All error codes, with explanations: MCP limits and error codes.

Discovery and reading

Tool	Permission	Parameters	What it does / returns	Limit
`whoami`	—	—	Confirms the account: the account ID (`customer_id`), the token's permissions (`scopes`), the missing permissions (`missing_scopes`) and a hint in English (`hint`). It does not return your email or name.	—
`list_vm_plans`	—	—	The 21 VPS plans: `slug`, name (for example “Standard M”), family, vCPU, RAM (GB), disk (GB), monthly price in MDL (`price_mdl`) and `recommended` for the recommended plan.	—
`list_servers`	`servers:read`	—	Your servers: `id` (used by all server tools), name, IP, plan, creation date, SSH login method (`auth_method`: `key`, `password` or empty), private name (`label`), `can_manage` and `capabilities`.	60 per minute
`get_server`	`servers:read`	`server_id`	The same server, plus the SSH port, whether saved credentials exist (`has_credentials`) and the actual `power_state`: `running`, `shutdown`, `paused`, `crashed`, `suspended`, `nostate`, or empty if it can't be read.	60 per minute
`get_balance`	`billing:read`	—	The balance in bani (`balance_bani`), the currency `MDL`, and whether automatic payment from the balance is on (`autopay_enabled`).	60 per minute
`list_transactions`	`billing:read`	`limit` (1–100, default 20), `offset`	Balance movements, newest first: the amount and the balance after the operation (in bani), the type (`topup`, `order_payment`, `invoice_payment`, `adjustment`, `refund`), the description, the linked order or invoice and the date; plus the total count.	30 per minute
`list_orders`	`billing:read`	`limit`, `offset`	Orders: the `BBX-…` number (`reference`), status, plan, total in MDL, date, description, add-on services with their status, server creation state (`provisioning_state`), IP, `server_id`, and whether the order can be canceled (`cancellable`).	30 per minute
`list_invoices`	`billing:read`	`limit`, `offset`	Invoices: number, status, currency, total, description, issue date, due date and payment date.	30 per minute

Plans, with specifications and prices: VPS plans: how to choose. You set the private name in the panel: Renaming a server (private name).

list_servers does not include the order number. To find out which order a server came from, ask the assistant to call list_orders and look for the order whose server_id equals the server's id.

Statuses in responses

The tools return codes in English. The table shows their label on blackbox.md or, where the site has no label, what they mean:

Field	Codes	On blackbox.md
Order status (`list_orders`)	`new`, `in_progress`, `done`, `cancelled`	“Nou” (New), “În lucru” (In progress), “Finalizat” (Completed), “Anulat” (Canceled)
Add-on service status (`list_orders`)	`pending`, `active`, `attention`, `cancelled`	“În curs de activare” (Activating), “Activ” (Active), “Contactați suportul” (Contact support), “Anulat” (Canceled)
Invoice status (`list_invoices`)	`sent`, `overdue`, `paid`, `cancelled`	“Trimisă” (Sent), “Restantă” (Overdue), “Achitată” (Paid), “Anulată” (Canceled)
Server creation (`provisioning_state`)	`provisioning`, `active`, `failed`, `terminated`	no label on the site: the server is being created, is ready, creation failed, the server has been deleted

Server control

Tool	Permission	Parameters	What it does / returns	Limit
`reveal_server_credentials`	`servers:credentials`	`server_id`	The saved root username and password, with the date they were saved, like the “Reveal credentials” button in the panel. The password is not read from the server.	20 per minute
`reset_server_password`	`servers:credentials`	`server_id`	Generates a new root password, applies it on the server and returns it, like the “Reset password” button. The old password stops working from that moment.	3 in 5 minutes
`power_server`	`servers:power`	`server_id`, `action`: `reboot`, `stop` or `start`	Reboots, stops or starts the server. It replies immediately with `status: accepted`, and the action continues in the background; check the result with `get_server` (`power_state`).	6 per minute
`run_server_command`	`servers:exec`	`server_id`, `command` (1–8,192 characters), `timeout_seconds` (1–300, default 60)	Runs the command as `root`, without an interactive terminal and without your password or key. Returns `exit_code`, `stdout` and `stderr` (up to 64,000 characters each), `duration_ms` and `timed_out`.	30 per minute
`get_server_ssh_access`	`servers:credentials`	`server_id`, `regenerate` (default `false`)	Installs the AI agent key for `root` (comment `blackbox-agent-…`) and returns the host, the port, the user `root`, the private and public keys, the fingerprint and a ready-to-use `ssh -i …` command. Every call returns the same key; `regenerate: true` creates a new one and deletes the old one.	10 in 5 minutes
`get_server_resize_options`	`servers:read`	`server_id`	The plans in the same family you can upgrade to (no resource decreases), the new monthly price, the amount you would pay now for the rest of the month, and your balance. It changes nothing.	only the combined limit
`resize_server`	`orders:write`	`server_id`, `target_flavor` (an option from `get_server_resize_options`), `confirm` (default `false`)	Without confirmation: a preview with the price and `confirm_required: true`, with no changes. With `confirm: true`: pays the difference from your balance and restarts the server on the new plan (a few minutes of downtime; the IP and data stay). Returns `job_id` and `state: queued`.	3 in 10 minutes, previews included

power_server. The reboot is a normal one, not a forced one; after reboot, the server usually responds again within 30–60 seconds. On some company servers that you have management rights for, only a reboot is possible (the other actions return no_instance_id). See also Rebooting, stopping and starting a server.
reset_server_password. On a “Key-only” server, the password changes, but SSH password login stays disabled: Resetting the root password.
run_server_command. A timeout is not an error: you get timed_out: true, and the process may keep running on the server. Details: Running commands on the server through AI.
get_server_ssh_access. There is one agent key per server, shared by all your tokens: SSH access and SSH keys through the AI assistant.
Upgrade. Only to a larger plan, never the other way around. “VPS hosting” plans and dedicated servers return not_upgradeable_plan (upgrade through support). If your balance is not enough, insufficient_balance already appears at the preview. See Server upgrade: moving to a larger plan.

Security reveal_server_credentials, reset_server_password and get_server_ssh_access return passwords and private keys in plain text. They reach the AI client and the AI model provider. Grant servers:credentials only when you need it, and ask the assistant not to display secrets in the conversation.

SSH keys

Keys saved in your account, on the “Chei SSH” (SSH keys) page (SSH keys in your account (blackbox.md)), and keys installed on a server, in /root/.ssh/authorized_keys (Adding and removing SSH keys on the server), are managed with different tools. Deleting a key in one place does not remove it from the other.

Tool	Permission	Parameters	What it does / returns	Limit
`list_ssh_keys`	`ssh_keys:read`	—	The keys saved in your account: `id`, name, type, fingerprint, number of bits, comment, date added and date last used; plus their count and the limit of 20.	30 per minute
`add_ssh_key`	`ssh_keys:write`	`name` (1–80 characters, on one line), `public_key` (a single line of an OpenSSH public key)	Saves the key in your account without installing it on any server. Accepted types: `ssh-ed25519`, `ssh-rsa` (at least 2048 bits), `ecdsa-sha2-nistp256/384/521` and `sk-…` hardware keys. At most 20 keys per account.	10 per hour
`delete_ssh_key`	`ssh_keys:write`	`key_id`	Deletes the key from your account. It does not remove the key from the servers where it is installed.	20 per hour
`add_server_ssh_key`	`servers:credentials`	`server_id` and exactly one of `key_id` (a saved key) or `public_key` (a pasted key)	Adds the key for `root` on the server. Returns `added` or `already_present` (the key was already there; nothing changes).	10 in 5 minutes
`list_server_ssh_keys`	`servers:credentials`	`server_id`	The keys installed for `root`: type, fingerprint, comment, which one is the management key (`is_management`) and which one is the agent key (`is_agent`), whether it can be deleted (`removable`), how many lines were skipped, and whether password login is enabled.	30 per minute
`remove_server_ssh_key`	`servers:credentials`	`server_id` and exactly one of `key_id`, `fingerprint` (from `list_server_ssh_keys`) or `public_key`	Removes the key from the server. Returns `removed` or `not_present`.	10 in 5 minutes
`set_server_password_auth`	`servers:credentials`	`server_id`, `enabled` (`true` or `false`)	Enables or disables SSH password login, like the “Enable password login” and “Disable password login” buttons. It checks the SSH configuration before reloading and returns the effective state (`effective`: `yes` or `no`).	5 in 5 minutes

Protections against losing access:

remove_server_ssh_key refuses to remove the management key (management_key_protected) and the last key on a “Key-only” server (last_key_on_key_only_server).
set_server_password_auth refuses to disable password login if none of your keys is on the server (no_customer_key_installed).

Money: orders, payments and cancellations

All three tools require orders:write. Payments and refunds go only through your balance: the assistant can't top up your balance or pay by card.

Tool	Permission	Parameters	What it does / returns	Limit
`create_order`	`orders:write`	`source` (`static-plan`), `plan_slug`, `config`, `confirm` (default `false`)	Without confirmation: a quote (`quote`, with the total in MDL and `provisionable`), without creating anything. With `confirm: true` and the same parameters: an order with the status `new` and a `BBX-…` number, unpaid. BLACKBOX always calculates the price. The same confirmation repeated within 5 minutes returns the same order.	20 per hour, quotes included
`pay_order`	`orders:write`	`order_id`, `confirm_total_mdl` (the current total, in MDL)	Pays an order with the status `new` from your balance. If the amount differs from the current total: `price_changed`, and nothing is paid. Replies with the status `in_progress`, the transaction ID and the remaining balance (in bani). Servers on `vm-…` plans then start being created automatically.	10 per minute
`cancel_order`	`orders:write`	`order_id`, `confirm` (default `false`)	Without confirmation: a preview with the refund amount (`refund_mdl`), the refund policy, and whether the server will be deleted (`server_terminated_on_cancel`). With `confirm: true`: cancels the order, and the refund goes to your balance.	5 in 5 minutes, previews included

The refund rules are the same as on the website: Order cancellation and refunds. Steps and protections: Orders, payments, cancellations and upgrades via AI.

Irreversible With confirm: true, cancel_order immediately deletes the order's server and all the data on it, without the 24-hour grace period of the “Terminate” button in the panel. Read the preview before you confirm.

Parameters for `create_order`

The assistant builds the parameters itself; you can explicitly tell it the plan, the operating system and the keys. Example for the recommended plan, with Ubuntu 24.04 and a key saved in your account:

{
  "source": "static-plan",
  "plan_slug": "vm-iops1-m",
  "config": {
    "kind": "static-plan",
    "plan_id": "vm-iops1-m",
    "os": "ubuntu-24",
    "ssh": { "key_ids": ["KEY_ID"] }
  },
  "confirm": false
}

The possible values for plan_slug (the same value also goes in config.plan_id) are listed below. VPS plans have the form vm-FAMILY-SIZE:

Family	Plans
Basic	`vm-basic1-xs`, `vm-basic1-s`, `vm-basic1-m`, `vm-basic1-l`, `vm-basic1-xl`
CPU	`vm-cores30-s`, `vm-cores30-m`, `vm-cores30-l`, `vm-cores30-xl`, `vm-cores30-xxl`
Standard	`vm-iops1-s`, `vm-iops1-m` (recommended), `vm-iops1-l`, `vm-iops1-xl`
High-Frequency	`vm-hfq1-xs`, `vm-hfq1-s`, `vm-hfq1-m`
High-Frequency Compute	`vm-hfq50-xs`, `vm-hfq50-s`, `vm-hfq50-m`, `vm-hfq50-l`
Dedicated servers	`dedicated-light`, `dedicated-premium`, `dedicated-storage`, prepared manually by our team: Dedicated servers
VPS hosting	`vps-hosting-1`, `vps-hosting-2`, `vps-hosting-3`: “VPS hosting” plans with a control panel

The fields in config:

Field	Values
`kind`	`static-plan`, the same as `source`
`plan_id`	the same plan as in `plan_slug`
`os`	`ubuntu-24`, `ubuntu-22`, `ubuntu-20`, `debian-12`, `debian-11`, `centos-9`, `almalinux-9`. Without `os`, Ubuntu 22.04 LTS is installed, not the newest version; for Ubuntu 24.04, specify `ubuntu-24`. A system that is not on the list gets `unsupported_os`. See Available operating systems.
`ssh`	`key_ids` (IDs from `list_ssh_keys`), `public_keys` (pasted keys) and `password_auth`; at most 10 keys. With keys and without `password_auth`, the server is created “key-only”; `"password_auth": true` keeps password login. See The SSH key at order time and “key-only” servers.
`extras`	`["monitoring"]` adds the Monitoring service, 98 MDL/month: Add-on services for your server. It is the only value you put here.

Warning Put only monitoring in extras. The MCP server also accepts other add-on service codes and adds them to the total and to the server's monthly price, but they are not activated automatically: in “Contul meu” (My account) → “Comenzi” (Orders) they stay “În curs de activare” (Activating). Don't ask the assistant to add other add-on services to the order; for those, write to support. Before you confirm, check total_mdl in the quote: it must be the plan price, plus 98 MDL if you asked for monitoring. The quote has a single line in line_items, with the total, so the add-on services don't appear separately.

The custom configurator (source: configurator) and the old plans vps-2, vps-3 and vps-4 have been replaced by the fixed plans: they return configurator_retired and plan_retired, respectively. For an old plan, the error may suggest a similar vm-… plan. If the quote shows provisionable: false, the plan is temporarily unavailable, and the confirmation returns plan_unavailable.

Frequently asked questions

The assistant says it doesn't have a certain tool. Why? The token doesn't have the required permission, so the tool is hidden. Ask the assistant to call whoami: the missing_scopes field shows what is missing. Then create a new token with that permission. In the hint text, the preset appears as “AI agent — full access”; on the page, the button is called “AI-administrator — acces complet” (AI administrator — full access).

Why is status active even though the server is stopped? status only shows that the server is active in your account. To see whether the server is running or stopped, check the power_state field in get_server.

Can I call the tools without an AI assistant? Yes, from any MCP client or from code, but only through the MCP address: bbx_pat_… tokens don't work anywhere else. See Using MCP from code (AI APIs and HTTP).

What does 57800 in balance_bani mean? The amount is in bani: 57,800 bani means 578.00 MDL.