Using MCP from code (AI APIs and HTTP)

You can use the BLACKBOX MCP server (https://api.app.blackbox.md/mcp) not only from apps such as Claude or Cursor, but also from your own scripts and agents. You can let an AI provider's API (Anthropic or OpenAI) connect to the server, or send JSON-RPC requests over HTTP yourself. To check the connection, use MCP Inspector. You create the token on blackbox.md, in “Contul meu” (My account) → “Token-uri API” (API tokens); the page is titled “Token-uri de acces (API)” (Access tokens (API)) and is at blackbox.md/account/api-tokens.

Available to: the blackbox.md account holder who has an API token (bbx_pat_…). What your code can do depends on the token's permissions.

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

Connection details

There is no REST interface for customers: the token works only at /mcp, and the other API addresses reject it. Everything your code can do (servers, SSH keys, balance, orders) goes through the MCP tools: List of MCP tools.

Keep the token in an environment variable, not in your code. The examples below use the BBX_PAT variable. In bash (Linux, macOS, WSL):

export BBX_PAT="bbx_pat_…"

In PowerShell:

$env:BBX_PAT = "bbx_pat_…"

Important When an AI provider's API calls the tools on its own, no one asks for your confirmation before each call. The exception is OpenAI with "require_approval": "always". For such scripts, use a read-only token (the three permissions checked by default when you create a token) or restrict the list of tools, as in the examples below. The token and everything the tools return, including passwords, keys and command output, pass through the AI provider. Details: Token permissions (scopes).

Anthropic Messages API (MCP connector)

Anthropic's API connects to the BLACKBOX server by itself and calls the tools on your behalf. In the request, you send two things:

• in mcp_servers, an entry with "type": "url", url, "name": "blackbox" and authorization_token set to your token;
• in tools, an entry of type mcp_toolset with "mcp_server_name": "blackbox".

The feature is in beta and requires the anthropic-beta header. As of October 9, 2026, its value is mcp-client-2025-11-20; check the current value in the Anthropic documentation.

Example in Python (the anthropic SDK), with only three read-only tools enabled:

import os
import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{
        "type": "url",
        "url": "https://api.app.blackbox.md/mcp",
        "name": "blackbox",
        "authorization_token": os.environ["BBX_PAT"],
    }],
    tools=[{
        "type": "mcp_toolset",
        "mcp_server_name": "blackbox",
        "default_config": {"enabled": False},
        "configs": {
            "whoami": {"enabled": True},
            "list_servers": {"enabled": True},
            "get_server": {"enabled": True},
        },
    }],
    messages=[{"role": "user", "content": "Show me my BLACKBOX servers and their status"}],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

• "default_config": {"enabled": False} disables all tools, and configs enables only the ones it names. Without these two fields, the model gets every tool the token allows.
• Besides text, the response contains mcp_tool_use blocks (which tool the model called and with which parameters) and mcp_tool_result blocks (what the BLACKBOX server answered).
• The model name is only an example; use the model you want.

OpenAI Responses API

In the Responses API, you add the BLACKBOX server as a tool of type mcp, with "server_label": "blackbox", server_url, the token in headers.Authorization and "require_approval": "always", so that each tool call waits for your approval.

import os
from openai import OpenAI

client = OpenAI()

blackbox = {
    "type": "mcp",
    "server_label": "blackbox",
    "server_url": "https://api.app.blackbox.md/mcp",
    "headers": {"Authorization": "Bearer " + os.environ["BBX_PAT"]},
    "require_approval": "always",
}

response = client.responses.create(
    model="gpt-5",
    tools=[blackbox],
    input="Show me my BLACKBOX servers and their status",
)

How to approve a call:

1. Look in response.output for items of type mcp_approval_request. Each one contains the tool name (name) and the parameters (arguments).

2. Check the call.

3. Send a new request with previous_response_id=response.id, the same tools list and, in input, your answer:

   {"type": "mcp_approval_response", "approve": true, "approval_request_id": "mcpr_…"}

4. To reject the call, send "approve": false.

With every request, send the tool definition again, together with the Authorization header: OpenAI does not keep it between requests. With allowed_tools (for example ["whoami", "list_servers", "get_server"]), you limit the tools the model sees. Details in the OpenAI documentation.

Directly over HTTP (JSON-RPC)

Without an SDK, send POST requests in JSON-RPC 2.0 format to the same address, with the following headers:

The examples are written for bash (Linux, macOS); on Windows, run them in WSL.

1. Open the session with initialize:

   curl -i https://api.app.blackbox.md/mcp \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -H "Authorization: Bearer $BBX_PAT" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"script","version":"1.0"}}}'

2. The response has status 200 and the mcp-session-id header. The body comes as an event stream; the JSON-RPC result is on the line that starts with data::

   event: message
   data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","serverInfo":{"name":"blackbox",…},"instructions":"…",…}}

   The instructions field contains the server's instructions for the AI assistant. If you build your own agent, pass them to the model.

3. Save the session ID (the value of the mcp-session-id header) in the MCP_SID variable:

   export MCP_SID="SESSION_ID"

   Then confirm the initialization:

   curl https://api.app.blackbox.md/mcp \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -H "Authorization: Bearer $BBX_PAT" \
     -H "mcp-session-id: $MCP_SID" \
     -H "MCP-Protocol-Version: 2025-06-18" \
     -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

   The response is 202 Accepted, with no content.

4. With the same headers as in step 3, request the list of tools. It contains only the tools the token allows, plus whoami and list_vm_plans, which require no permissions:

   {"jsonrpc":"2.0","id":2,"method":"tools/list"}

5. Call a tool with tools/call:

   {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"whoami","arguments":{}}}

   The result is in result.content, as JSON text. If the tool rejects the call, the HTTP status is still 200, but the result has "isError": true, and the text contains the error code (for example missing_scope or rate_limited).

6. When you are done, you can close the session with a DELETE request to the same address, with the Authorization and mcp-session-id headers.

The session stays tied to the account that opened it. Use the same token for the whole session, and write your code so that it can reopen the session with initialize at any time.

Testing with MCP Inspector

MCP Inspector is the official tool for testing MCP servers. It requires Node.js.

1. Start it:

   npx @modelcontextprotocol/inspector

2. In the interface that opens in your browser, choose the “Streamable HTTP” transport and enter the address https://api.app.blackbox.md/mcp.

3. Add the Authorization header with the value Bearer bbx_pat_….

4. Connect, open the tool list and call whoami. The response shows the account ID, the token's permissions and the permissions it is missing (missing_scopes).

The Inspector also has a command-line mode, useful in scripts and automated checks:

npx @modelcontextprotocol/inspector --cli https://api.app.blackbox.md/mcp \
  --transport http \
  --header "Authorization: Bearer $BBX_PAT" \
  --method tools/list

Note AI providers' APIs and MCP Inspector change often. The names of the fields, the beta header and the options in the examples are valid as of October 9, 2026; check them in the official documentation before you use them.

Response times and limits

• A request can take up to about 5 minutes, for example a long command run with run_server_command (300 seconds at most) or paying for an order with pay_order. In your HTTP client or SDK, set a read timeout slightly above 5 minutes.
• If pay_order seems to have timed out, check the order with list_orders before you retry: Orders, payments, cancellations and upgrades via AI.
• Start longer jobs on the server in the background (nohup, systemd-run) and check the result later: Running commands on the server through AI.
• Limits apply per account, to all tokens together: 120 tool calls per minute, plus separate limits for some tools. Calls made while you are rate-limited also count, so wait instead of retrying right away. Details: MCP limits and error codes.

Frequently asked questions

Is there a REST API for BLACKBOX? No. The only programmatic interface for customers is the MCP server. A bbx_pat_… token sent to other API addresses is rejected.

Can I call the MCP server from a website's JavaScript? No. The server rejects requests sent from a browser on other sites (403 “Invalid Origin header”), and the token would be visible to anyone who opens the page. Call the server from your backend.

My script used to work, and now it gets 401. Why? The token was revoked, or you changed your blackbox.md account password, which stops all tokens created before the change. Create a new token: API tokens: creating, copying and revoking.

Does it also work with other SDKs or agent frameworks? Yes, with any MCP client that supports the Streamable HTTP transport and custom headers, for example the official MCP SDKs. Use the address and header from the “Connection details” table.