AI integration (MCP): what it is and what it can do
How to connect an AI assistant to your BLACKBOX account, what it can do for you and what it cannot do.
On this page
The AI integration lets you manage your BLACKBOX account from an AI assistant, in plain language: your servers, SSH access, balance, orders and invoices. For this, BLACKBOX runs an MCP server named blackbox at https://api.app.blackbox.md/mcp. The overview is on the blackbox.md/info/mcp page, and you create access tokens in “Contul meu” (My account) → “Token-uri API” (API tokens) (blackbox.md/account/api-tokens).
Available to: the holder of the blackbox.md account. The app.blackbox.md panel has no AI settings: everything is done in your account on blackbox.md and in the AI client.
The blackbox.md website is available in Romanian and Russian; this article quotes the Romanian labels with their English meaning.
What MCP is
Model Context Protocol (MCP) is an open standard that lets an AI assistant connect to external services and use their “tools”. The BLACKBOX MCP server gives the assistant tools for a single blackbox.md account: yours.
- Compatible clients: Claude (the web app and Claude Desktop, through “Custom connector”, plus Claude Code), Cursor, VS Code with GitHub Copilot and any other client that connects to remote MCP servers over HTTP (Streamable HTTP) and lets you add a custom header.
- Authentication: a personal API token in the form
bbx_pat_…, which you create on blackbox.md. The assistant does not need your account password, the root password or your SSH key: the token is enough. - Permissions: when you create the token, you tick what the assistant is allowed to do. Tools the token has no permission for do not even appear in the assistant's list.
- Cost: the integration is free. Tokens and MCP calls are not charged; you pay only for the services you order.
Connecting in 3 steps
1. Create a token
- On blackbox.md, open “Contul meu” (My account) → “Token-uri API” (API tokens) (the “Token-uri de acces (API)” (Access tokens (API)) page).
- In the “Token nou” (New token) card, fill in “Nume token” (Token name), for example “Claude Desktop (laptop)”.
- Under “Permisiuni” (Permissions), the three read permissions are ticked by default. Tick others if you want the assistant to make changes, or click “AI-administrator — acces complet” (AI administrator — full access) to tick all eight.
- Click “Creează token” (Create token).
- The “Token-ul dvs. nou” (Your new token) card appears, with the message “Copiați token-ul acum — nu va mai fi afișat din nou.” (Copy the token now — it will not be shown again.) Click “Copiază” (Copy); the button changes to “Copiat!” (Copied!). Keep the token in a safe place, then click “Gata” (Done).
Details: API tokens: creating, copying and revoking.
2. Add the server to your AI client
The values are the same in all clients:
| Field | Value |
|---|---|
| Name in the configuration | blackbox (recommended) |
| Server URL | https://api.app.blackbox.md/mcp |
| Transport | HTTP (Streamable HTTP) |
| Authorization header | Authorization: Bearer bbx_pat_… |
| In the Claude app (“Custom connector”) | the x-api-key header, with the value bbx_pat_…, without the word Bearer |
In Cursor, you add the server to a JSON file, in the format shown on blackbox.md/info/mcp:
{
"mcpServers": {
"blackbox": {
"url": "https://api.app.blackbox.md/mcp",
"headers": {
"Authorization": "Bearer bbx_pat_..."
}
}
}
}Replace bbx_pat_... with your token and restart the client if it asks you to. Other clients (for example VS Code) use a slightly different format. Steps for each client: Connecting in the Claude app (custom connector) and Connecting from Claude Code, Cursor, VS Code and other clients.
3. Check the connection
Write to the assistant: “Call whoami”. The whoami tool needs no permission. It confirms that the token works and shows which permissions the token has and which are missing (missing_scopes). If a permission you need is missing, create a new token: you cannot add permissions to an existing token.
If the AI client reports the invalid_token error, see MCP limits and error codes.
What the assistant can do
| Area | What it can do | Permission needed |
|---|---|---|
| Plans | lists VPS plans, with their resources and prices | none |
| Servers | lists your servers, with their status, IP address and power state | “Citește lista și statusul serverelor mele” (Read the list and status of my servers) (servers:read) |
| Power | reboots, stops and starts the server | “Controlează alimentarea serverelor (repornire/oprire/pornire)” (Control server power (reboot/stop/start)) (servers:power) |
| Server access | shows or resets the root password; gets direct SSH access with a key that BLACKBOX installs on the server; adds, lists and deletes SSH keys on the server; turns SSH password login on or off | “Vizualizează parolele/accesul serverelor” (View server passwords/access) (servers:credentials) |
| Running commands | runs any command as root, for example installs nginx |
“Rulează orice comandă ca root pe serverele mele” (Run any command as root on my servers) (servers:exec) |
| SSH keys in your account | lists them; adds and deletes them | “Citește lista cheilor mele SSH” (Read the list of my SSH keys) (ssh_keys:read); “Adaugă și șterge cheile mele SSH” (Add and delete my SSH keys) (ssh_keys:write) |
| Balance and billing | reads your balance, transactions, orders and invoices | “Citește soldul, facturile și comenzile” (Read the balance, invoices and orders) (billing:read) |
| Orders and payments | calculates the price and places an order, pays for it from your balance, cancels an order, upgrades a server | “Plasează și modifică comenzi în numele meu” (Place and change orders on my behalf) (orders:write) |
To find a server, the assistant also needs servers:read. The full list of tools, with parameters and limits: List of MCP tools. What each permission allows: Token permissions (scopes).
Warning With
orders:write, the assistant can spend from your balance and cancel orders. Canceling an order with an active server deletes the server immediately, with all its data, with no grace period. Theservers:credentialsandservers:execpermissions giverootaccess to all your servers. Grant them only when you really need them.
What the assistant cannot do
| Action | Where to do it |
|---|---|
| Creating and revoking tokens | blackbox.md, “Token-uri API” (API tokens) |
| Topping up your balance and paying by card | blackbox.md: Topping up your balance |
| Paying invoices | Automatic payment of invoices from your balance or Paying by bank transfer and BLACKBOX bank details |
| Support tickets | blackbox.md, “Ajutor și suport” (Help and support): Opening a support ticket |
| Monitoring, alerts and DNS | the app.blackbox.md panel: The “Monitoring” page, Managing DNS records from the panel |
| Web or VNC console | not available to customers; you connect over SSH, and if you lose access, write to support |
| Reinstalling the operating system | on request, through support: Available operating systems |
| Moving to a smaller plan (downgrade) | not possible in the panel either; order a new server on the plan you want and move your data |
| Renaming the server | the panel: Renaming a server (private name) |
| Scheduled deletion, with 24 hours in which you can cancel it | the panel: Permanently deleting a server |
The assistant also has no access to your profile, your account password or your billing details, and it cannot delete your account.
There is no REST API
bbx_pat_… tokens work only at https://api.app.blackbox.md/mcp. BLACKBOX does not offer customers a REST API: the other addresses of the website and the panel accept only your browser session and reject the token. If you want to automate something from your own code, use MCP as well: Using MCP from code (AI APIs and HTTP).
Example requests
| What you write to the assistant | Permissions needed |
|---|---|
| “Show me my BLACKBOX servers and their status” | servers:read |
| “What is my balance, and which invoices are unpaid?” | billing:read |
| “Install nginx on my server” | servers:read, servers:exec |
| “What VPS plans do you have with 4 vCPU, and how much do they cost?” | none |
| “Restart my server and tell me when it responds again” | servers:read, servers:power |
| “Which SSH keys are installed on my server?” | servers:read, servers:credentials |
| “Upgrade my server to the next plan, but show me the price first” | servers:read, orders:write |
The first three examples are the ones on blackbox.md/info/mcp. More: Example tasks for the AI assistant and the permissions they need.
What data the AI provider sees
Everything the tools return reaches the AI client and the provider that runs the AI model: your server list, IP addresses, balance, invoices, the output of commands run on the server and, if you granted servers:credentials, root passwords and server access keys. Use an AI provider you trust, and grant access permissions only when needed. In the action log, BLACKBOX records only that a command was run, without its text and without its output.
Security The token is a key to your account: anyone who has it can do, from anywhere, everything its permissions allow. Do not put it in chats, screenshots or git repositories. Create a separate token for each client or device, and revoke it with “Revocă” (Revoke) when you no longer need it; access stops immediately. Changing your blackbox.md account password disables all tokens created before the change. More: Token and AI agent security.
Frequently asked questions
Which AI clients work?
Any client that connects to remote MCP servers over HTTP and lets you add a custom header: the Claude app (through “Custom connector”, with the x-api-key header), Claude Code, Cursor, VS Code with GitHub Copilot and others. Apps that only allow connecting through OAuth (signing in with an account, without a header) cannot connect: the BLACKBOX server accepts only the token.
Does it cost anything? No. The integration and the tokens are free. You pay only for the services you order, including those ordered through the assistant.
Can the assistant spend my money?
Only from your balance, and only if the token has the orders:write permission. By default, the tools for orders, cancellations and upgrades show only a preview (the price or the amount to be refunded) and act only after you confirm. An order is paid in a separate step, which succeeds only if the amount specified is exactly the current price. The assistant cannot top up your balance or pay by card. It is instructed to ask for your consent before any spending, but the confirmation window is shown by the AI client, so do not turn on automatic approval for these tools. Details: Orders, payments, cancellations and upgrades via AI.
Do I have to give the assistant my root password or my SSH key? No. The assistant works on the server through the secure BLACKBOX connection and needs only the token. See BLACKBOX keys on your server.
Can I connect several assistants or devices? Yes. Create a separate token for each one, with the right permissions. You can revoke them one at a time without affecting the others.