Conectarea din Claude Code, Cursor, VS Code și alți clienți

Clienții AI pentru programatori (Claude Code, Cursor, VS Code cu GitHub Copilot și alții) se conectează la serverul MCP BLACKBOX printr-o comandă sau un fișier de configurare, în care indicați adresa serverului și token-ul dvs. API. Token-ul se creează pe pagina „Token-uri de acces (API)” (blackbox.md/account/api-tokens, „Contul meu” → „Token-uri API”). Un exemplu de configurare este publicat și pe blackbox.md/info/mcp, la „Exemplu de configurare”.

Disponibil pentru: orice client autentificat pe blackbox.md care are un token API. Crearea token-ului este gratuită.

Datele de conectare

Sunt aceleași în toți clienții; diferă doar formatul în care le scrieți.

Între Bearer și token se pune un singur spațiu. Token-ul se afișează o singură dată, la creare, în cardul „Token-ul dvs. nou”. Sub el, caseta „Conectarea unui client AI” repetă „URL server” și „Antet de autorizare”, cu token-ul deja completat. Cum creați și revocați token-uri: Token-uri API: creare, copiere și revocare.

Ce poate face asistentul depinde de permisiunile token-ului: Permisiunile token-urilor (scopes). Creați câte un token pentru fiecare client și dispozitiv, cu un nume clar, de exemplu „Claude Code (laptop)”: îl puteți revoca fără să-i afectați pe ceilalți.

Antetele alternative (x-api-key și altele) sunt pentru aplicația Claude, unde Authorization nu poate fi completat: Conectarea în aplicația Claude (connector personalizat). În clienții din acest articol folosiți Authorization: Bearer.

Securitate Nu scrieți token-ul în fișiere care ajung în git: .mcp.json, .cursor/mcp.json sau .vscode/mcp.json din proiect. În ele folosiți o variabilă de mediu sau câmpul de parolă al clientului, ca în exemplele de mai jos. Dacă token-ul a ajuns totuși într-un depozit, revocați-l imediat și creați altul.

Claude Code

1. Creați token-ul și copiați-l.

2. Adăugați serverul din terminal, înlocuind bbx_pat_… cu token-ul dvs.:

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

3. Verificați conexiunea. Serverul blackbox trebuie să apară ca conectat:

   claude mcp list

4. Într-o sesiune Claude Code, comanda de mai jos arată starea serverului și uneltele lui:

   /mcp

Opțiunea --scope (pe scurt -s) stabilește unde se salvează serverul:

Cu user și local, token-ul rămâne în fișierul dvs. de configurare, în afara proiectului.

Pentru un proiect (.mcp.json)

Fișierul .mcp.json se adaugă de obicei în git, așa că token-ul nu se scrie în el. Folosiți variabila de mediu BBX_PAT:

1. Creați în rădăcina proiectului fișierul .mcp.json:

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

   Aceeași intrare o creează și comanda de mai jos. Ghilimelele simple păstrează textul ${BBX_PAT} neschimbat în bash, zsh și PowerShell:

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

2. Setați variabila pe fiecare calculator pe care lucrați cu proiectul. Pe macOS și Linux, adăugați linia în ~/.bashrc sau ~/.zshrc, apoi deschideți un terminal nou:

   export BBX_PAT="bbx_pat_…"

   Pe Windows, rulați comanda în PowerShell, apoi deschideți o fereastră nouă:

   setx BBX_PAT "bbx_pat_…"

3. Porniți Claude Code în proiect. La prima utilizare vă cere să aprobați serverele din .mcp.json: aprobați blackbox. Dacă variabila BBX_PAT nu este setată, Claude Code nu poate citi configurația.

Cursor

Cursor citește serverele MCP din două fișiere:

1. Deschideți sau creați fișierul global ~/.cursor/mcp.json. Îl puteți deschide și din „Cursor Settings”, din secțiunea dedicată MCP.

2. Adăugați configurația (este exemplul de pe blackbox.md/info/mcp):

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

   Dacă fișierul are deja alte servere, adăugați doar blocul "blackbox" în interiorul lui "mcpServers".

3. Salvați fișierul. Dacă serverul nu apare, reporniți Cursor.

4. În secțiunea MCP din „Cursor Settings”, serverul blackbox trebuie să fie activ și să-și afișeze uneltele. Chatul folosește uneltele în modul „Agent”.

Pentru un proiect (.cursor/mcp.json)

În fișierul de proiect nu scrieți token-ul. Cursor înlocuiește ${env:BBX_PAT} cu valoarea variabilei de mediu BBX_PAT:

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

Setați variabila ca la Claude Code (secțiunea de mai sus), apoi reporniți Cursor, ca să o preia.

VS Code (GitHub Copilot, modul agent)

VS Code folosește alt format: cheia servers (nu mcpServers), tipul http și o listă inputs. Prin inputs, VS Code vă cere token-ul la prima pornire și îl păstrează separat, în spațiul său securizat, nu în fișier.

1. Creați în proiect fișierul .vscode/mcp.json:

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

2. Porniți serverul: apăsați „Start” deasupra intrării blackbox din fișier sau folosiți comanda „MCP: List Servers” din paleta de comenzi (Ctrl+Shift+P, pe macOS Cmd+Shift+P).

3. Introduceți token-ul în câmpul care se deschide; caracterele nu se afișează. Dacă VS Code vă întreabă dacă aveți încredere în server, confirmați.

4. Deschideți Chat, alegeți modul „Agent” și verificați că uneltele blackbox apar în lista de unelte.

Fișierul nu conține token-ul, deci îl puteți adăuga în git. Ca serverul să fie disponibil în toate proiectele, puneți aceeași configurație în fișierul de utilizator, pe care îl deschideți cu comanda „MCP: Open User Configuration”.

Alți clienți (Windsurf, Gemini CLI și alții)

Funcționează orice client care acceptă servere MCP la distanță prin HTTP (Streamable HTTP) cu antete personalizate. Folosiți datele din tabelul de la început; de la un client la altul diferă doar numele cheilor, de exemplu:

Clienții care acceptă doar servere locale (stdio) sau doar autentificare OAuth nu se pot conecta direct: BLACKBOX nu folosește OAuth, ci token-ul din antet. Pentru scripturile și aplicațiile dvs.: Folosirea MCP din cod (API-uri AI și HTTP).

Notă Interfețele și formatele clienților se schimbă de la o versiune la alta. Dacă o cheie sau un meniu diferă de ce scrie aici, urmați documentația clientului. Rămân aceleași URL-ul, transportul HTTP și antetul Authorization: Bearer.

Verificați conexiunea cu whoami

După conectare, scrieți asistentului:

Apelează unealta whoami de pe serverul blackbox și arată-mi permisiunile token-ului.

Unealta whoami nu cere nicio permisiune și nu modifică nimic. Răspunsul conține:

Clientul vede doar uneltele permise de token. Dacă o unealtă lipsește, token-ul nu are permisiunea ei. Permisiunile nu se pot modifica ulterior: creați un token nou și înlocuiți-l în configurație.

Important Serverul BLACKBOX marchează uneltele care modifică ceva (repornire, comenzi ca root, plăți), dar confirmarea înainte de execuție o cere clientul, nu serverul. Cât timp token-ul are permisiuni de scriere, nu activați aprobarea automată a tuturor uneltelor (opțiuni de tipul „always allow” sau modurile care rulează uneltele fără întrebare). Detalii: Securitatea token-urilor și a agenților AI.

Dacă nu se conectează

Verificați token-ul fără client

Comanda de mai jos arată răspunsul serverului pentru token-ul dvs. Pe Windows, în PowerShell, scrieți curl.exe în loc de curl.

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

Dacă token-ul este valid, răspunsul este 406 Not Acceptable. Pentru acest test este normal și înseamnă că problema este în configurația clientului. Dacă token-ul nu este acceptat, răspunsul este 401, cu cauza în câmpul error_description.

Răspunsuri și cauze

Lista completă a erorilor și limitelor: Limite și coduri de eroare MCP.

Întrebări frecvente

După schimbarea parolei contului, conexiunea nu mai merge. De ce? Schimbarea parolei contului blackbox.md oprește toate token-urile create înainte de ea. Creați un token nou și înlocuiți-l în configurație; dacă folosiți variabila BBX_PAT, schimbați doar valoarea ei. În Claude Code, ștergeți serverul și adăugați-l din nou cu noul token:

claude mcp remove blackbox

În VS Code, schimbați id-ul din inputs și din ${input:…} (de exemplu, în bbx-token-2): la pornire vi se cere noul token.

Pot folosi fișierul de configurare al Claude Desktop? Fișierul de configurare al Claude Desktop este pentru servere locale. În aplicația Claude adăugați BLACKBOX ca connector: Conectarea în aplicația Claude (connector personalizat).

Există un API REST pe care să-l folosesc cu token-ul? Nu. Token-ul funcționează doar la https://api.app.blackbox.md/mcp, prin protocolul MCP.