Conectarea în aplicația Claude (connector personalizat)

Pașii pentru a adăuga BLACKBOX ca connector personalizat în Claude (web și desktop), cu token-ul API în antetul x-api-key.

În aplicația Claude (claude.ai și Claude Desktop), serverul MCP BLACKBOX se adaugă ca connector personalizat: în Claude, „Customize” → „Connectors” → „Add custom connector”, cu adresa https://api.app.blackbox.md/mcp. Token-ul API îl creați pe blackbox.md, în „Contul meu” → „Token-uri API” (blackbox.md/account/api-tokens), și îl puneți în antetul x-api-key. În acest antet token-ul se scrie fără prefixul Bearer, iar antetul obișnuit Authorization este, în unele versiuni ale dialogului, rezervat pentru OAuth.

Disponibil pentru: titularul contului blackbox.md care și-a creat un token API. În Claude: planurile Free, Pro, Max, Team și Enterprise, dacă dialogul „Add custom connector” are secțiunea „Request headers”. Pe planul Free puteți adăuga un singur connector personalizat.

Notă Interfața Claude se schimbă în timp. Etichetele de mai jos sunt în limba engleză, ca în Claude, și corespund documentației Anthropic din 9 octombrie 2026. Dacă pe ecran vedeți alte denumiri, urmați-le pe acestea: de exemplu, în versiunile mai vechi meniul se numea „Settings” → „Connectors”.

Ce pregătiți

Aveți nevoie de un token API. Pe blackbox.md deschideți „Contul meu” → „Token-uri API”, scrieți un nume în câmpul „Nume token”, bifați permisiunile și apăsați „Creează token”. Copiați token-ul imediat. Pagina vă avertizează: „Copiați token-ul acum — nu va mai fi afișat din nou.” Începeți cu permisiunile doar de citire; altele le adăugați mai târziu, cu un token nou. Detalii: Token-uri API: creare, copiere și revocare și Permisiunile token-urilor (scopes).

Cum adăugați connectorul (planurile Free, Pro și Max)

Deschideți claude.ai sau Claude Desktop și mergeți la „Customize” → „Connectors”.
Apăsați „Add custom connector”. În unele versiuni apăsați întâi „+ Add”, apoi „Add custom connector”.
Scrieți numele, de exemplu BLACKBOX.
În câmpul pentru URL introduceți https://api.app.blackbox.md/mcp. Dacă dialogul are doi pași, apăsați apoi „Continue”.
Nu completați OAuth Client ID și Client Secret (în unele versiuni sunt sub „Advanced settings”). Dacă dialogul vă cere să alegeți „Authentication”, alegeți „No sign-in”.
Deschideți „Request headers” și alegeți din listă numele x-api-key.
Lipiți token-ul ca valoare: doar bbx_pat_…, fără Bearer, fără spații și fără rând nou.
Bifați „Required”.
Apăsați „Add”. Dacă lângă connector apare butonul „Connect”, apăsați-l.

Connectorul apare în lista „Connectors”. Claude păstrează valoarea antetului și nu v-o mai afișează.

Planurile Team și Enterprise

Connectorul îl adaugă proprietarul organizației Claude (rolul „Owner” sau „Primary Owner”): „Organization settings” → „Connectors” → „Add” → „Custom” (tipul „Web”, dacă vi se cere), cu aceleași valori. Membrii îl găsesc în „Customize” → „Connectors”, cu eticheta „Custom”, și apasă „Connect”.

Securitate Antetul din „Request headers” este comun pentru toată organizația Claude. Toți membrii care se conectează lucrează cu același token, adică în contul dvs. blackbox.md, cu toate permisiunile token-ului. Pe un plan Team sau Enterprise dați connectorului un token doar de citire. Pentru acțiuni pe servere sau cu bani, fiecare persoană poate folosi un token propriu într-un client precum Claude Code: Conectarea din Claude Code, Cursor, VS Code și alți clienți.

Verificați conexiunea

Deschideți o conversație nouă, apăsați „+” → „Connectors” și verificați că BLACKBOX este activat.
Scrieți: „Apelează whoami”.
Claude confirmă că token-ul a fost acceptat (authenticated) și arată identificatorul contului dvs. blackbox.md (customer_id), permisiunile token-ului (scopes) și pe cele care lipsesc (missing_scopes). Dacă nu lipsește nimic, răspunsul conține „All scopes granted — every tool is available.”
Puneți o întrebare reală, de exemplu „Arată-mi serverele mele BLACKBOX și statusul lor”.

Uneltele pentru care token-ul nu are permisiune nu apar deloc în lista din Claude. Unui token existent nu i se pot adăuga permisiuni: creați un token nou și adăugați din nou connectorul.

Aprobarea uneltelor în Claude

BLACKBOX marchează separat uneltele care doar citesc (servere, sold, facturi, chei) și pe cele care schimbă ceva. Claude le afișează grupat în „Customize” → „Connectors” → BLACKBOX → „Tool permissions”, cu trei opțiuni: „Always allow”, „Needs approval” și „Blocked”.

Pentru uneltele care doar citesc, „Always allow” este acceptabil.
Pentru uneltele care scriu sau șterg, alegeți „Needs approval”: Claude vă arată apelul și așteaptă acordul dvs.
Uneltele de care nu aveți nevoie puneți-le pe „Blocked” sau, mai sigur, nu dați token-ului permisiunea respectivă.

Nu alegeți „Always allow” pentru aceste unelte:

Unealta	Ce face	Permisiunea
`run_server_command`	rulează orice comandă ca `root` pe server	`servers:exec`
`power_server`	repornește, oprește sau pornește serverul	`servers:power`
`reset_server_password`, `remove_server_ssh_key`, `set_server_password_auth`	schimbă parola root, șterge chei SSH de pe server, activează sau dezactivează login cu parolă	`servers:credentials`
`create_order`, `pay_order`, `resize_server`	creează comenzi, plătește din sold, face upgrade cu plată din sold	`orders:write`
`cancel_order`	anulează o comandă; dacă are un server, acesta este șters imediat, cu toate datele	`orders:write`

Important BLACKBOX nu poate impune confirmarea: ea depinde doar de setările din Claude. Asistentul este instruit să vă ceară acordul înainte să creeze sau să plătească o comandă, să facă upgrade, să anuleze o comandă, să șteargă o cheie SSH de pe server sau să dezactiveze login-ul cu parolă. Comenzile pe server și repornirile cerute de dvs. le execută direct. Cu „Always allow” pe aceste unelte nu mai vedeți nimic înainte de execuție.

Alte antete acceptate

Antet	Valoare
`x-api-key` (recomandat; este în lista standard din Claude)	`bbx_pat_…`
`x-api-token`, `x-auth-token`, `api-key`, `x-access-token`	`bbx_pat_…`
`authorization` (doar dacă dialogul îl permite, la „No sign-in”)	`Bearer bbx_pat_…`, cu cuvântul `Bearer` și un spațiu

BLACKBOX citește antetele alternative doar când lipsește Authorization, în ordinea din tabel, și îl folosește pe primul care conține un token bbx_pat_. O valoare fără token bbx_pat_ este ignorată. Dacă alegeți „Custom header”, Claude acceptă doar numele de antet aprobate de Anthropic, așa că este mai simplu să folosiți x-api-key.

Dacă nu vedeți secțiunea „Request headers”

Potrivit Anthropic, autentificarea prin „Request headers” este în versiune beta și disponibilă doar pentru o parte dintre organizații. Fără ea, Claude nu poate trimite token-ul, iar conectarea eșuează. Variante:

Folosiți Claude Code sau alt client care trimite antetul Authorization: Bearer bbx_pat_…: Conectarea din Claude Code, Cursor, VS Code și alți clienți.
Fișierul de configurare al Claude Desktop (claude_desktop_config.json) este pentru servere locale, care rulează pe calculatorul dvs., așa că exemplul JSON de pe https://blackbox.md/info/mcp nu este pentru el. Utilizatorii avansați pot pune în acest fișier o punte locală, de exemplu mcp-remote (necesită Node.js), care transmite cererile către https://api.app.blackbox.md/mcp împreună cu antetul token-ului.

Erori la conectare

Ce vedeți	Cauza	Ce faceți
„Couldn't register with BlackBox's sign-in service”	Token-ul nu a ajuns la BLACKBOX, iar Claude a încercat autentificarea OAuth, pe care BLACKBOX nu o folosește.	Verificați numele antetului (`x-api-key`) și valoarea: începe cu `bbx_pat_`, fără `Bearer`, fără spații. Verificați și „Required”, „No sign-in” și câmpurile OAuth goale.
Connectorul a funcționat, apoi nu se mai conectează	Token-ul a fost revocat sau a fost creat înainte de ultima schimbare a parolei contului blackbox.md.	Creați un token nou și adăugați din nou connectorul.
O unealtă lipsește sau răspunsul conține `missing_scope`	Token-ul nu are permisiunea necesară.	Creați un token nou cu permisiunea respectivă și adăugați din nou connectorul.
`rate_limited`	Prea multe apeluri într-un timp scurt.	Așteptați câteva minute, apoi reîncercați. Apelurile respinse se numără și ele în limită. Detalii: Limite și coduri de eroare MCP.

Claude nu permite modificarea antetelor unui connector salvat. Ca să corectați antetul sau să schimbați token-ul, ștergeți connectorul („Remove” în „Customize” → „Connectors”; pe Team și Enterprise, proprietarul îl șterge în „Organization settings” → „Connectors”) și adăugați-l din nou. Pe Team și Enterprise membrii apasă apoi din nou „Connect”.

Întrebări frecvente

Funcționează connectorul și în Claude Desktop? Da. Connectorii personalizați funcționează în claude.ai și în Claude Desktop, iar pașii sunt aceiași: „Customize” → „Connectors”.

Cum schimb token-ul folosit de connector? Creați un token nou, ștergeți connectorul și adăugați-l din nou cu token-ul nou. Apoi revocați token-ul vechi pe pagina „Token-uri API”, cu „Revocă”.

Claude îmi recomandă presetarea „AI agent — full access”. Unde o găsesc? Pe pagina „Token-uri API” butonul se numește „AI-administrator — acces complet”. El bifează toate permisiunile, inclusiv comenzi ca root pe servere și plăți din sold.

Ce date ajung la Anthropic? Tot ce returnează uneltele BLACKBOX ajunge la Claude și la furnizorul lui, Anthropic. Cu permisiunea „Vizualizează parolele/accesul serverelor” (servers:credentials), aici intră și parole și chei ale serverelor. Mai multe: Securitatea token-urilor și a agenților AI.