Connecting from Claude Code, Cursor, VS Code and other clients

AI clients for developers (Claude Code, Cursor, VS Code with GitHub Copilot and others) connect to the BLACKBOX MCP server through a command or a configuration file, where you enter the server address and your API token. You create the token on the “Token-uri de acces (API)” (Access tokens (API)) page (blackbox.md/account/api-tokens, “Contul meu” (My account) → “Token-uri API” (API tokens)). A configuration example is also published on blackbox.md/info/mcp, under “Exemplu de configurare” (Configuration example).

Available to: any customer signed in to blackbox.md who has an API token. Creating a token is free.

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

Connection details

They are the same in every client; only the format you write them in differs.

Put a single space between Bearer and the token. The token is shown only once, when you create it, in the “Token-ul dvs. nou” (Your new token) card. Below it, the “Conectarea unui client AI” (Connecting an AI client) box repeats the “URL server” (Server URL) and the “Antet de autorizare” (Authorization header), with your token already filled in. How to create and revoke tokens: API tokens: creating, copying and revoking.

What the assistant can do depends on the token's permissions: Token permissions (scopes). Create a separate token for each client and device, with a clear name, for example “Claude Code (laptop)”: that way you can revoke it without affecting the others.

The alternative headers (x-api-key and others) are for the Claude app, where Authorization cannot be filled in: Connecting in the Claude app (custom connector). In the clients covered in this article, use Authorization: Bearer.

Security Don't write the token in files that end up in git: .mcp.json, .cursor/mcp.json or .vscode/mcp.json in your project. In these files, use an environment variable or the client's own password field, as in the examples below. If the token has ended up in a repository anyway, revoke it immediately and create a new one.

Claude Code

1. Create the token and copy it.

2. Add the server from the terminal, replacing bbx_pat_… with your token:

   claude mcp add --transport http --scope user blackbox https://api.app.blackbox.md/mcp --header "Authorization: Bearer bbx_pat_…"

3. Check the connection. The blackbox server should appear as connected:

   claude mcp list

4. In a Claude Code session, the command below shows the server's status and its tools:

   /mcp

The --scope option (-s for short) sets where the server is saved:

With user and local, the token stays in your own configuration file, outside the project.

For a project (.mcp.json)

The .mcp.json file is usually added to git, so you don't write the token in it. Use the BBX_PAT environment variable:

1. In the project root, create the .mcp.json file:

   {
     "mcpServers": {
       "blackbox": {
         "type": "http",
         "url": "https://api.app.blackbox.md/mcp",
         "headers": {
           "Authorization": "Bearer ${BBX_PAT}"
         }
       }
     }
   }

   The command below creates the same entry. The single quotes keep the text ${BBX_PAT} unchanged in bash, zsh and PowerShell:

   claude mcp add --transport http --scope project blackbox https://api.app.blackbox.md/mcp --header 'Authorization: Bearer ${BBX_PAT}'

2. Set the variable on every computer where you work on the project. On macOS and Linux, add this line to ~/.bashrc or ~/.zshrc, then open a new terminal:

   export BBX_PAT="bbx_pat_…"

   On Windows, run this command in PowerShell, then open a new window:

   setx BBX_PAT "bbx_pat_…"

3. Start Claude Code in the project. The first time, it asks you to approve the servers in .mcp.json: approve blackbox. If the BBX_PAT variable is not set, Claude Code cannot read the configuration.

Cursor

Cursor reads MCP servers from two files:

1. Open or create the global file ~/.cursor/mcp.json. You can also open it from “Cursor Settings”, in the MCP section.

2. Add the configuration (this is the example from blackbox.md/info/mcp):

   {
     "mcpServers": {
       "blackbox": {
         "url": "https://api.app.blackbox.md/mcp",
         "headers": {
           "Authorization": "Bearer bbx_pat_…"
         }
       }
     }
   }

   If the file already contains other servers, add only the "blackbox" block inside "mcpServers".

3. Save the file. If the server doesn't appear, restart Cursor.

4. In the MCP section of “Cursor Settings”, the blackbox server should be enabled and show its tools. The chat uses the tools in “Agent” mode.

For a project (.cursor/mcp.json)

Don't write the token in the project file. Cursor replaces ${env:BBX_PAT} with the value of the BBX_PAT environment variable:

{
  "mcpServers": {
    "blackbox": {
      "url": "https://api.app.blackbox.md/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BBX_PAT}"
      }
    }
  }
}

Set the variable as for Claude Code (in the section above), then restart Cursor so that it picks up the variable.

VS Code (GitHub Copilot, agent mode)

VS Code uses a different format: the servers key (not mcpServers), the http type and an inputs list. Through inputs, VS Code asks you for the token on first start and stores it separately, in its own secure storage, not in the file.

1. In your project, create the .vscode/mcp.json file:

   {
     "servers": {
       "blackbox": {
         "type": "http",
         "url": "https://api.app.blackbox.md/mcp",
         "headers": {
           "Authorization": "Bearer ${input:bbx-token}"
         }
       }
     },
     "inputs": [
       {
         "type": "promptString",
         "id": "bbx-token",
         "description": "BLACKBOX API token",
         "password": true
       }
     ]
   }

2. Start the server: click “Start” above the blackbox entry in the file, or run the “MCP: List Servers” command from the Command Palette (Ctrl+Shift+P, or Cmd+Shift+P on macOS).

3. Enter the token in the field that opens; the characters are hidden. If VS Code asks whether you trust the server, confirm.

4. Open Chat, choose “Agent” mode and check that the blackbox tools appear in the tool list.

The file doesn't contain the token, so you can add it to git. To make the server available in all your projects, put the same configuration in your user configuration file, which you open with the “MCP: Open User Configuration” command.

Other clients (Windsurf, Gemini CLI and others)

Any client that supports remote MCP servers over HTTP (Streamable HTTP) with custom headers works. Use the details from the table at the top of this article; only the key names differ from one client to another, for example:

Clients that support only local servers (stdio) or only OAuth sign-in cannot connect directly: BLACKBOX doesn't use OAuth, but the token in the header. For your own scripts and applications, see Using MCP from code (AI APIs and HTTP).

Note Client interfaces and formats change from one version to the next. If a key or a menu differs from what is described here, follow the client's documentation. The URL, the HTTP transport and the Authorization: Bearer header stay the same.

Check the connection with whoami

Once connected, write this to the assistant:

Call the whoami tool on the blackbox server and show me the token's permissions.

The whoami tool requires no permission and changes nothing. The response contains:

The client sees only the tools the token allows. If a tool is missing, the token doesn't have the permission for it. Permissions cannot be changed afterward: create a new token and replace the old one in the configuration.

Important The BLACKBOX server marks the tools that change something (reboot, commands as root, payments), but it is the client, not the server, that asks you to confirm before a tool runs. As long as the token has write permissions, don't turn on automatic approval for all tools (options such as “always allow” or modes that run tools without asking). Details: Token and AI agent security.

If it doesn't connect

Check the token without a client

The command below shows the server's response for your token. On Windows, in PowerShell, type curl.exe instead of curl.

curl -i https://api.app.blackbox.md/mcp -H "Authorization: Bearer bbx_pat_…"

If the token is valid, the response is 406 Not Acceptable. For this test, that is normal, and it means the problem is in the client's configuration. If the token is not accepted, the response is 401, with the cause in the error_description field.

Responses and causes

The full list of errors and limits: MCP limits and error codes.

Frequently asked questions

The connection stopped working after I changed my account password. Why? Changing your blackbox.md account password stops all tokens created before the change. Create a new token and replace the old one in the configuration; if you use the BBX_PAT variable, change only its value. In Claude Code, remove the server and add it again with the new token:

claude mcp remove blackbox

In VS Code, change the id in inputs and in ${input:…} (for example, to bbx-token-2): on start, you are asked for the new token.

Can I use the Claude Desktop configuration file? The Claude Desktop configuration file is for local servers. In the Claude app, add BLACKBOX as a connector: Connecting in the Claude app (custom connector).

Is there a REST API I can use with the token? No. The token works only at https://api.app.blackbox.md/mcp, through the MCP protocol.