Connecting in the Claude app (custom connector)

How to add BLACKBOX as a custom connector in Claude (web and desktop), with the API token in the x-api-key header.

In the Claude app (claude.ai and Claude Desktop), you add the BLACKBOX MCP server as a custom connector: in Claude, “Customize” → “Connectors” → “Add custom connector”, with the address https://api.app.blackbox.md/mcp. You create the API token on blackbox.md, in “Contul meu” (My account) → “Token-uri API” (API tokens) (blackbox.md/account/api-tokens), and put it in the x-api-key header. In this header, you write the token without the Bearer prefix; the usual Authorization header is reserved for OAuth in some versions of the dialog.

Available to: the holder of the blackbox.md account who has created an API token. In Claude: the Free, Pro, Max, Team and Enterprise plans, if the “Add custom connector” dialog has the “Request headers” section. On the Free plan, you can add only one custom connector.

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

Note Claude's interface changes over time. The labels below are quoted as Claude shows them and match Anthropic's documentation as of October 9, 2026. If you see different names on screen, follow those: for example, in older versions the menu was called “Settings” → “Connectors”.

What you need

You need an API token. On blackbox.md, open “Contul meu” (My account) → “Token-uri API” (API tokens), type a name in the “Nume token” (Token name) field, check the permissions and click “Creează token” (Create token). Copy the token right away. The page warns you: “Copiați token-ul acum — nu va mai fi afișat din nou.” (Copy the token now — it will not be shown again.) Start with read-only permissions; you can add others later, with a new token. Details: API tokens: creating, copying and revoking and Token permissions (scopes).

How to add the connector (Free, Pro and Max plans)

Open claude.ai or Claude Desktop and go to “Customize” → “Connectors”.
Click “Add custom connector”. In some versions, first click “+ Add”, then “Add custom connector”.
Enter a name, for example BLACKBOX.
In the URL field, enter https://api.app.blackbox.md/mcp. If the dialog has two steps, then click “Continue”.
Leave the OAuth Client ID and Client Secret empty (in some versions, they are under “Advanced settings”). If the dialog asks you to choose “Authentication”, choose “No sign-in”.
Open “Request headers” and choose the name x-api-key from the list.
Paste the token as the value: only bbx_pat_…, without Bearer, without spaces and without a line break.
Check “Required”.
Click “Add”. If a “Connect” button appears next to the connector, click it.

The connector appears in the “Connectors” list. Claude stores the header value and does not show it to you again.

Team and Enterprise plans

The connector is added by the owner of the Claude organization (the “Owner” or “Primary Owner” role): “Organization settings” → “Connectors” → “Add” → “Custom” (type “Web”, if asked), with the same values. Members find it in “Customize” → “Connectors”, with the “Custom” label, and click “Connect”.

Security The header in “Request headers” is shared by the whole Claude organization. All members who connect work with the same token, that is, in your blackbox.md account, with all of the token's permissions. On a Team or Enterprise plan, give the connector a read-only token. For actions on servers or involving money, each person can use their own token in a client such as Claude Code: Connecting from Claude Code, Cursor, VS Code and other clients.

Check the connection

Open a new conversation, click “+” → “Connectors” and check that BLACKBOX is turned on.
Type: “Call whoami”.
Claude confirms that the token was accepted (authenticated) and shows your blackbox.md account identifier (customer_id), the token's permissions (scopes) and the missing ones (missing_scopes). If nothing is missing, the response contains “All scopes granted — every tool is available.”
Ask a real question, for example “Show me my BLACKBOX servers and their status”.

Tools that the token has no permission for don't appear in Claude's list at all. You cannot add permissions to an existing token: create a new token and add the connector again.

Approving tools in Claude

BLACKBOX marks the tools that only read (servers, balance, invoices, keys) separately from those that change something. Claude shows them grouped in “Customize” → “Connectors” → BLACKBOX → “Tool permissions”, with three options: “Always allow”, “Needs approval” and “Blocked”.

For tools that only read, “Always allow” is acceptable.
For tools that write or delete, choose “Needs approval”: Claude shows you the call and waits for your approval.
Set the tools you don't need to “Blocked” or, more safely, don't give the token the corresponding permission.

Don't choose “Always allow” for these tools:

Tool	What it does	Permission
`run_server_command`	runs any command as `root` on the server	`servers:exec`
`power_server`	reboots, stops or starts the server	`servers:power`
`reset_server_password`, `remove_server_ssh_key`, `set_server_password_auth`	changes the root password, deletes SSH keys from the server, turns password login on or off	`servers:credentials`
`create_order`, `pay_order`, `resize_server`	creates orders, pays from your balance, upgrades with payment from your balance	`orders:write`
`cancel_order`	cancels an order; if the order has a server, the server is deleted immediately, with all its data	`orders:write`

Important BLACKBOX cannot enforce confirmation: it depends only on your settings in Claude. The assistant is instructed to ask for your approval before it creates or pays for an order, upgrades a server, cancels an order, deletes an SSH key from the server or turns off password login. It runs the server commands and reboots you ask for directly. With “Always allow” on these tools, you see nothing before they run.

Other accepted headers

Header	Value
`x-api-key` (recommended; it is in Claude's standard list)	`bbx_pat_…`
`x-api-token`, `x-auth-token`, `api-key`, `x-access-token`	`bbx_pat_…`
`authorization` (only if the dialog allows it, with “No sign-in”)	`Bearer bbx_pat_…`, with the word `Bearer` and a space

BLACKBOX reads the alternative headers only when Authorization is missing, in the order shown in the table, and uses the first one that contains a bbx_pat_ token. A value without a bbx_pat_ token is ignored. If you choose “Custom header”, Claude accepts only header names approved by Anthropic, so it is simpler to use x-api-key.

If you don't see the “Request headers” section

According to Anthropic, authentication through “Request headers” is in beta and available only to some organizations. Without it, Claude cannot send the token, and the connection fails. Your options:

Use Claude Code or another client that sends the Authorization: Bearer bbx_pat_… header: Connecting from Claude Code, Cursor, VS Code and other clients.
The Claude Desktop configuration file (claude_desktop_config.json) is for local servers, which run on your computer, so the JSON example on https://blackbox.md/info/mcp is not meant for it. Advanced users can add a local bridge to this file, for example mcp-remote (requires Node.js), which forwards requests to https://api.app.blackbox.md/mcp together with the token header.

Connection errors

What you see	Cause	What to do
“Couldn't register with BlackBox's sign-in service”	The token didn't reach BLACKBOX, and Claude tried OAuth sign-in, which BLACKBOX doesn't use.	Check the header name (`x-api-key`) and the value: it starts with `bbx_pat_`, without `Bearer`, without spaces. Also check “Required”, “No sign-in” and that the OAuth fields are empty.
The connector worked, then stopped connecting	The token was revoked or was created before the last password change on your blackbox.md account.	Create a new token and add the connector again.
A tool is missing or the response contains `missing_scope`	The token doesn't have the required permission.	Create a new token with that permission and add the connector again.
`rate_limited`	Too many calls in a short time.	Wait a few minutes, then try again. Rejected calls also count toward the limit. Details: MCP limits and error codes.

Claude doesn't let you change the headers of a saved connector. To fix the header or change the token, delete the connector (“Remove” in “Customize” → “Connectors”; on Team and Enterprise, the owner deletes it in “Organization settings” → “Connectors”) and add it again. On Team and Enterprise, members then click “Connect” again.

Frequently asked questions

Does the connector also work in Claude Desktop? Yes. Custom connectors work in claude.ai and in Claude Desktop, and the steps are the same: “Customize” → “Connectors”.

How do I change the token the connector uses? Create a new token, delete the connector and add it again with the new token. Then revoke the old token on the “Token-uri API” (API tokens) page, with “Revocă” (Revoke).

Claude recommends the “AI agent — full access” preset. Where do I find it? On the “Token-uri API” page, the button is called “AI-administrator — acces complet” (AI administrator — full access). It checks all permissions, including commands as root on servers and payments from your balance.

What data reaches Anthropic? Everything the BLACKBOX tools return reaches Claude and its provider, Anthropic. With the “Vizualizează parolele/accesul serverelor” (View server passwords/access) permission (servers:credentials), this includes server passwords and keys. More: Token and AI agent security.