Skip to main content

​
Prezentare generală

Twenty expune un server MCP astfel încât asistenții AI — Claude Desktop, Claude Code, Cursor, ChatGPT și alții — să poată citi și scrie datele tale din CRM prin limbaj natural. Folosește URL-ul spațiului de lucru (URL-ul pe care îl folosești pentru a accesa Twenty) drept punct final MCP. Pe Twenty Cloud, URL-ul spațiului tău de lucru poate fi https://{mycompany}.twenty.com sau un domeniu personalizat. Serverul este disponibil la:

​
Metode de autentificare

Ai două moduri de a-ți autentifica clientul MCP: OAuth (recomandat) sau Cheie API.

​
Opțiunea A — OAuth (Recomandat)

Cu OAuth, clientul tău MCP deschide o fereastră de browser pentru a te autentifica. Nicio informație secretă nu este stocată în fișierele de configurare, iar tokenurile se reîmprospătează automat.
OAuth necesită un client MCP care suportă specificația MCP Authorization. Claude Desktop, Claude Code, Cursor și ChatGPT o suportă.
Adaugă asta în configurația clientului tău MCP, înlocuind {your-workspace-url} cu gazda spațiului tău de lucru (de ex. mycompany.twenty.com):
Atât — nu este necesară nicio cheie API. Când clientul se conectează pentru prima dată, acesta va:
  1. Va descoperi metadatele OAuth ale Twenty prin /.well-known/oauth-protected-resource și /.well-known/oauth-authorization-server
  2. Se va înregistra ca un client OAuth prin înregistrare dinamică a clientului (RFC 7591)
  3. Îți va deschide browserul pentru a autoriza accesul
  4. Va primi tokenurile și se va conecta la serverul MCP
Conexiunile ulterioare reutilizează tokenurile stocate și le reîmprospătează automat.

​
Opțiunea B — Cheie API

Dacă clientul tău MCP nu suportă OAuth sau preferi acreditări statice, furnizează o cheie API în antetul Authorization:
Cheia ta API oferă acces la datele spațiului de lucru. Ține-o în afara controlului versiunilor și a dotfiles partajate.
Pentru a crea o cheie API, mergi la Settings → Developers → API → + Create key. Vezi API-uri pentru detalii.

​
Pornire rapidă

​
1. Copiază configurația

Mergi la Settings → AI → MCP în Twenty. Alege metoda de autentificare (OAuth sau Cheie API), copiază fragmentul JSON (va folosi deja URL-ul spațiului tău de lucru) și lipește-l în fișierul de configurare al clientului tău MCP.

​
2. Conectează-te

Repornește clientul tău MCP (sau reîncarcă configurația). Dacă folosești OAuth, vei fi redirecționat către Twenty pentru a autoriza accesul. Dacă folosești o cheie API, conexiunea este imediată.

​
3. Începe să-l folosești

Roagă-ți asistentul AI să interacționeze cu CRM-ul tău:
  • “Arată-mi cele 5 companii create cel mai recent”
  • “Creează o persoană nouă numită Jane Doe la Acme Corp”
  • “Găsește toate oportunitățile deschise cu o valoare mai mare de $10k”

​
Instrumente disponibile

După conectare, serverul MCP expune instrumente care oglindesc API-ul Twenty. Fluxul de lucru recomandat este:
  1. learn_tools — obține schema de intrare pentru instrumente specifice
  2. execute_tool — rulează un instrument
Nu este nevoie să reții numele instrumentelor. Întreabă-ți asistentul AI ce poate face și va apela learn_tools automat. Numele operațiunilor de înregistrare respectă o gramatică, astfel încât un asistent le poate construi fără un apel de descoperire: find_many_companies, find_one_person, update_one_opportunity. Dacă un nume este greșit, learn_tools îl raportează în notFound împreună cu numele care se potrivesc cel mai bine. Pentru orice altceva, get_tool_catalog parcurge instrumentele rămase, câte o categorie odată. Este o soluție de rezervă: un apel nefiltrat returnează sute de operațiuni, iar majoritatea asistenților vor trunchia răspunsul. /mcp?mode=direct enumeră fiecare instrument direct și necesită un client care încarcă instrumente la cerere.

​
Permisiuni

Conexiunile MCP moștenesc permisiunile utilizatorului autentificat (OAuth) sau rolul atribuit cheii API. Pentru a restricționa ce poate face serverul MCP:
  • OAuth: Se aplică rolul utilizatorului din spațiul de lucru.
  • Cheie API: Atribuie un rol cheii API în Settings → Members → Roles. Vezi Permisiuni.

​
Configurație pentru auto-găzduire

Pentru instanțele auto-găzduite, înlocuiește {your-workspace-url} cu URL-ul serverului tău. Asigură-te că SERVER_URL din mediul tău corespunde URL-ului public al instanței tale Twenty — acesta este folosit pentru a genera metadatele de descoperire OAuth.
Punctul final MCP, punctele finale OAuth și metadatele de descoperire derivă toate din această valoare.

​
Depanare

Erori “Unauthorized” sau 401
  • OAuth: reautorizează ștergând tokenurile stocate din clientul tău MCP și reconectează-te.
  • Cheie API: verifică dacă cheia este validă și nu a expirat. Regenereaz-o dacă este necesar.
Fluxul OAuth nu deschide un browser
  • Asigură-te că clientul tău MCP suportă MCP Authorization. Dacă nu, revino la metoda cu Cheie API.
Timeout de conexiune
  • Confirmă că URL-ul punctului final MCP este accesibil de pe calculatorul tău. Pentru instanțele auto-găzduite, verifică faptul că serverul rulează și că SERVER_URL este setat corect.