Folosirea MCP din cod (API-uri AI și HTTP)

Serverul MCP BLACKBOX (https://api.app.blackbox.md/mcp) poate fi folosit nu doar din aplicații precum Claude sau Cursor, ci și din propriile scripturi și agenți. Puteți lăsa API-ul unui furnizor AI (Anthropic sau OpenAI) să se conecteze la server sau puteți trimite singuri cereri JSON-RPC prin HTTP. Conexiunea o verificați cu MCP Inspector. Token-ul îl creați pe blackbox.md, în „Contul meu” → „Token-uri API” (pagina „Token-uri de acces (API)”, blackbox.md/account/api-tokens).

Disponibil pentru: titularul contului blackbox.md care are un token API (bbx_pat_…). Ce poate face codul depinde de permisiunile token-ului.

Datele de conectare

Nu există o interfață REST pentru clienți: token-ul funcționează doar la /mcp, iar celelalte adrese ale API-ului îl refuză. Tot ce poate face codul (servere, chei SSH, sold, comenzi) trece prin uneltele MCP: Lista uneltelor MCP.

Păstrați token-ul într-o variabilă de mediu, nu în cod. Exemplele de mai jos folosesc variabila BBX_PAT. În bash (Linux, macOS, WSL):

export BBX_PAT="bbx_pat_…"

În PowerShell:

$env:BBX_PAT = "bbx_pat_…"

Important Când API-ul unui furnizor AI apelează singur uneltele, nimeni nu vă cere confirmarea înainte de fiecare apel. Excepție face OpenAI cu "require_approval": "always". Pentru astfel de scripturi folosiți un token doar de citire (cele trei permisiuni bifate implicit la creare) sau restrângeți lista de unelte, ca în exemplele de mai jos. Token-ul și tot ce returnează uneltele, inclusiv parole, chei și rezultatul comenzilor, trec prin furnizorul AI. Detalii: Permisiunile token-urilor (scopes).

Anthropic Messages API (connector MCP)

API-ul Anthropic se conectează singur la serverul BLACKBOX și apelează uneltele în locul dvs. În cerere trimiteți două lucruri:

• în mcp_servers, o intrare cu "type": "url", url, "name": "blackbox" și authorization_token egal cu token-ul dvs.;
• în tools, o intrare de tip mcp_toolset cu "mcp_server_name": "blackbox".

Funcția este în beta și cere antetul anthropic-beta. La 9 octombrie 2026 valoarea lui este mcp-client-2025-11-20; verificați valoarea actuală în documentația Anthropic.

Exemplu în Python (SDK-ul anthropic), cu doar trei unelte de citire activate:

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": "Arată-mi serverele mele BLACKBOX și statusul lor"}],
)

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

• "default_config": {"enabled": False} dezactivează toate uneltele, iar configs le activează doar pe cele numite. Fără aceste două câmpuri, modelul primește toate uneltele permise de token.
• Pe lângă text, răspunsul conține blocuri mcp_tool_use (ce unealtă a apelat modelul și cu ce parametri) și mcp_tool_result (ce a răspuns serverul BLACKBOX).
• Numele modelului este doar un exemplu; folosiți modelul dorit.

OpenAI Responses API

În Responses API, serverul BLACKBOX se adaugă ca unealtă de tip mcp, cu "server_label": "blackbox", server_url, token-ul în headers.Authorization și "require_approval": "always", ca fiecare apel de unealtă să aștepte aprobarea dvs.

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="Arată-mi serverele mele BLACKBOX și statusul lor",
)

Cum aprobați un apel:

1. Căutați în response.output elementele de tip mcp_approval_request. Fiecare conține numele uneltei (name) și parametrii (arguments).

2. Verificați apelul.

3. Trimiteți o cerere nouă cu previous_response_id=response.id, aceeași listă tools și, în input, răspunsul dvs.:

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

4. Pentru a refuza apelul, trimiteți "approve": false.

La fiecare cerere trimiteți din nou definiția uneltei, împreună cu antetul Authorization: OpenAI nu îl păstrează între cereri. Cu allowed_tools (de exemplu ["whoami", "list_servers", "get_server"]) limitați uneltele pe care le vede modelul. Detalii în documentația OpenAI.

Direct prin HTTP (JSON-RPC)

Fără SDK, trimiteți cereri POST în format JSON-RPC 2.0 la aceeași adresă, cu următoarele antete:

Exemplele sunt scrise pentru bash (Linux, macOS); în Windows rulați-le în WSL.

1. Deschideți sesiunea cu 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. Răspunsul are statusul 200 și antetul mcp-session-id. Corpul vine ca flux de evenimente; rezultatul JSON-RPC este pe linia care începe cu data::

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

   Câmpul instructions conține instrucțiunile serverului pentru asistentul AI. Dacă vă construiți propriul agent, transmiteți-le modelului.

3. Salvați ID-ul sesiunii (valoarea antetului mcp-session-id) în variabila MCP_SID:

   export MCP_SID="ID_SESIUNE"

   Apoi confirmați inițializarea:

   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"}'

   Răspunsul este 202 Accepted, fără conținut.

4. Cu aceleași antete ca la pasul 3, cereți lista uneltelor. Ea conține doar uneltele permise de token, plus whoami și list_vm_plans, care nu cer permisiuni:

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

5. Apelați o unealtă cu tools/call:

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

   Rezultatul este în result.content, ca text JSON. Dacă unealta refuză apelul, statusul HTTP rămâne 200, dar rezultatul are "isError": true, iar textul conține codul erorii (de exemplu missing_scope sau rate_limited).

6. La final, puteți închide sesiunea cu o cerere DELETE la aceeași adresă, cu antetele Authorization și mcp-session-id.

Sesiunea rămâne legată de contul care a deschis-o. Folosiți același token pe toată durata ei și scrieți codul astfel încât să poată redeschide oricând sesiunea cu initialize.

Testarea cu MCP Inspector

MCP Inspector este instrumentul oficial pentru testarea serverelor MCP. Are nevoie de Node.js.

1. Porniți-l:

   npx @modelcontextprotocol/inspector

2. În interfața deschisă în browser alegeți transportul „Streamable HTTP” și introduceți adresa https://api.app.blackbox.md/mcp.

3. Adăugați antetul Authorization cu valoarea Bearer bbx_pat_….

4. Conectați-vă, deschideți lista de unelte și apelați whoami. Răspunsul arată ID-ul contului, permisiunile token-ului și permisiunile care îi lipsesc (missing_scopes).

Inspectorul are și un mod pentru linia de comandă, util în scripturi și verificări automate:

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

Notă API-urile furnizorilor AI și MCP Inspector se schimbă des. Numele câmpurilor, al antetului beta și al opțiunilor din exemple sunt valabile la 9 octombrie 2026; înainte de a le folosi, verificați-le în documentația oficială.

Timpi de răspuns și limite

• O cerere poate dura până la circa 5 minute, de exemplu o comandă lungă rulată cu run_server_command (cel mult 300 de secunde) sau plata unei comenzi cu pay_order. Setați în clientul HTTP sau în SDK un timeout de citire puțin peste 5 minute.
• Dacă pay_order pare să fi expirat, verificați comanda cu list_orders înainte să reîncercați: Comenzi, plăți, anulări și upgrade prin AI.
• Lucrările mai lungi porniți-le pe server în fundal (nohup, systemd-run) și verificați rezultatul ulterior: Rularea comenzilor pe server prin AI.
• Limitele se aplică pe cont, pentru toate token-urile împreună: 120 de apeluri de unelte pe minut, plus limite separate pentru unele unelte. Apelurile făcute cât timp sunteți limitat se numără și ele, așa că așteptați în loc să reîncercați imediat. Detalii: Limite și coduri de eroare MCP.

Întrebări frecvente

Există un API REST pentru BLACKBOX? Nu. Singura interfață programatică pentru clienți este serverul MCP. Un token bbx_pat_… trimis la alte adrese ale API-ului este refuzat.

Pot apela serverul MCP din JavaScript-ul unui site? Nu. Serverul refuză cererile trimise din browser de pe alte site-uri (403 „Invalid Origin header”), iar token-ul ar fi vizibil oricui deschide pagina. Apelați serverul din backend.

Scriptul funcționa, iar acum primește 401. De ce? Token-ul a fost revocat sau ați schimbat parola contului blackbox.md, ceea ce oprește toate token-urile create înainte de schimbare. Creați un token nou: Token-uri API: creare, copiere și revocare.

Funcționează și cu alte SDK-uri sau framework-uri de agenți? Da, cu orice client MCP care acceptă transportul Streamable HTTP și antete personalizate, de exemplu SDK-urile MCP oficiale. Folosiți adresa și antetul din tabelul „Datele de conectare”.