Conectori AI (MCP), în curând

Punct de acces#

Serverul se află la https://api.console.citronos.com/mcp. Ca și în cazul /graphql, calea nu conține /v1. Folosește versiunea de protocol 2025-11-25 prin streamable HTTP și nu păstrează stare: fiecare POST primește un răspuns JSON, nu există sesiuni, iar GET și DELETE răspund cu 405.

După lansare se vor putea conecta Claude (claude.ai, Claude Desktop și Claude Code), ChatGPT, Cursor, VS Code și orice alt client MCP. Clienții care acceptă OAuth se autentifică singuri; ceilalți folosesc un token personal.

Conectarea unui client#

Claude Code#

Adăugați serverul, apoi rulați /mcp în Claude Code și alegeți Authenticate. Se deschide un browser pe ecranul de consimțământ Citron. Pentru a evita OAuth, transmiteți în schimb un token personal ca antet.

claude mcp add --transport http citron https://api.console.citronos.com/mcp
# then, inside Claude Code: /mcp → citron → Authenticate

claude mcp add --transport http citron https://api.console.citronos.com/mcp \
  --header "Authorization: Bearer cmcp_pat_…"

Claude Desktop și claude.ai#

Deschideți Settings → Connectors → Add custom connector, introduceți https://api.console.citronos.com/mcp ca URL și alegeți Connect, apoi aprobați conexiunea în Citron. Pentru a-l rula local cu un token personal, adăugați următoarele în claude_desktop_config.json:

{
  "mcpServers": {
    "citron": {
      "command": "citron-mcp",
      "args": ["--base-url", "https://api.console.citronos.com"],
      "env": { "CITRON_MCP_TOKEN": "cmcp_pat_…" }
    }
  }
}

Cursor#

Adăugați serverul în ~/.cursor/mcp.json. Omiteți headers pentru a vă autentifica prin OAuth în loc de token.

{
  "mcpServers": {
    "citron": {
      "url": "https://api.console.citronos.com/mcp",
      "headers": { "Authorization": "Bearer cmcp_pat_…" }
    }
  }
}

ChatGPT#

Deschideți Settings → Apps & Connectors → Advanced settings, activați Developer mode, apoi alegeți Create connector. Introduceți https://api.console.citronos.com/mcp ca URL al serverului MCP și alegeți OAuth pentru autentificare.

Clienți care rulează doar servere locale#

Un mic server stdio local, citron-mcp, redirecționează fiecare apel către punctul de acces la distanță. Nu este încă pe npm, așa că cereți-ne fișierul pachetului și nu instalați niciodată un pachet cu acest nume din altă parte. Primește un token personal prin --token sau în CITRON_MCP_TOKEN, iar URL-ul de bază prin --base-url sau în CITRON_BASE_URL. Necesită Node 20 sau o versiune mai nouă.

# Node 20+. Not on npm yet: install the package file we send you
npm install -g ./citron-mcp-0.1.0.tgz

citron-mcp --base-url https://api.console.citronos.com --token cmcp_pat_…

# or with environment variables
CITRON_BASE_URL=https://api.console.citronos.com CITRON_MCP_TOKEN=cmcp_pat_… citron-mcp

Autentificare#

Există două tipuri de credențiale. OAuth este recomandat pentru clienții care îl acceptă. Tokenurile personale funcționează în toate celelalte cazuri.

OAuth 2.1#

Clientul descoperă totul singur. O cerere fără token primește 401 cu un antet WWW-Authenticate care indică metadatele resursei protejate.

POST /mcp HTTP/1.1
Host: api.console.citronos.com
Content-Type: application/json

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.console.citronos.com/.well-known/oauth-protected-resource/mcp"

• Cod de autorizare cu PKCE. Este acceptată doar metoda S256.
• Clienții înregistrați sunt publici în mod implicit. Sunt acceptate și client_secret_post și client_secret_basic.
• Un document de metadate al clientului (un URL https folosit ca client_id) funcționează în locul înregistrării.
• Trimiteți indicatorul de resursă (RFC 8707) resource=https://api.console.citronos.com/mcp.
• URI-urile de redirecționare trebuie să fie https. HTTP simplu este permis doar pe localhost, 127.0.0.1 sau [::1], pe orice port. Sunt permise și scheme de aplicație precum cursor://….
• Domeniile de acces (scopes) sunt mcp:read și mcp:write. Scrierea include citirea.
• Tokenurile de acces (cmcp_oat_…) sunt valabile 1 oră. Tokenurile de reîmprospătare (cmcp_ort_…) sunt valabile 30 de zile și se rotesc la fiecare utilizare.
• Un cod de autorizare folosit de două ori revocă tot ce a emis.

Utilizatorul aprobă conexiunea pe un ecran de consimțământ din consola Citron (/admin/connect/mcp), fiind conectat cu sesiunea sa obișnuită. Acolo alege spațiul de lucru și Read only sau Read & write.

Tokenuri personale#

1. Creați tokenulÎn consolă, deschideți Settings → Developers → AI connectors și alegeți New token.
2. Alegeți numele, accesul și expirareaAccesul este Read only sau Read & write. Tokenul expiră după 7, 30 sau 90 de zile, după 1 an sau niciodată.
3. Copiați-l o singură datăTokenul (cmcp_pat_…) este afișat o singură dată. Citron stochează doar hash-ul său SHA-256. Trimiteți-l ca Authorization: Bearer cmcp_pat_….

Lista tokenurilor arată când a fost folosit ultima dată fiecare dintre ele. Puteți revoca oricare token în orice moment.

În numele cui acționează conexiunea#

Ambele tipuri de credențiale acționează în numele membrului care le-a creat sau aprobat, doar în acel spațiu de lucru. Folosesc permisiunile curente ale membrului: schimbarea rolului său sau eliminarea sa din echipă are efect imediat. Nivelul de acces al tokenului limitează ceea ce membrul ar putea face altfel.

Politicile pentru înregistrări (reguli pentru câmpuri și înregistrări), restricțiile de acces la colecții și modulele activate se aplică exact ca în consolă.

Instrumente#

Instrumentele sunt aceleași cu cele ale asistentului AI din consolă. Acoperă mesajele primite și solicitările, formularele, rezervările, colecțiile și înregistrările de conținut, fișierele media, CRM-ul, automatizările, tablourile de bord și multe altele. Ceea ce vede un client depinde de permisiunile membrului, de modulele spațiului de lucru și de accesul tokenului.

• Instrumentele de citire (căutare, citire, rezumare, rularea unei interogări de tablou de bord) funcționează cu orice token.
• Instrumentele de scriere sunt listate și rulează doar cu un token Read & write. Prin MCP, o scriere se aplică imediat, fără pas de confirmare în consolă. Trece prin aceleași metode de serviciu ca în consolă, este înregistrată în jurnalul de audit și returnează un actionId. Când modificarea poate fi anulată, instrumentul undo_change o anulează.
• Instrumentele distructive (ștergere, arhivare, revocare) necesită în plus argumentul confirm: true. Fără el, apelul returnează CONFIRMATION_REQUIRED și nu se întâmplă nimic. AI-ul ar trebui să îl transmită doar după ce utilizatorul și-a dat acordul.
• Modificările de securitate (roluri, membri, chei API, SSO, domenii) necesită o autentificare recentă, așa că nu sunt niciodată disponibile prin MCP și returnează UNAVAILABLE_OVER_MCP. Instrumentele care doar navighează în consolă nu sunt listate.
• Rezultatele instrumentelor marchează datele din înregistrări ca nesigure. Se aplică regulile asistentului privind minimizarea datelor: fără adrese de e-mail sau numere de telefon, iar nume și text din mesaje doar când spațiul de lucru permite AI-ului să citească conținutul din mesaje primite și CRM (Settings → AI).
• Instrumentele au adnotările readOnlyHint și destructiveHint.

Erorile instrumentelor#

Un instrument care eșuează returnează un rezultat cu isError: true. Textul său începe cu unul dintre aceste coduri.

{
  "content": [{ "type": "text", "text": "CONFIRMATION_REQUIRED: …" }],
  "isError": true
}

Resurse#

Prompturi#

Erori HTTP și limite de cereri#

Punctele de acces OAuth returnează erorile în stilul RFC, { "error", "error_description" }. Erorile API-ului public sunt descrise în erori și limite de cereri.

Audit și revocarea accesului#

Fiecare apel de instrument scrie un rând mcp.tool.call în jurnalul de audit: instrumentul, dacă a reușit sau codul de eroare, id-ul tokenului, clientul OAuth, nivelul de acces și numele argumentelor. Valorile argumentelor nu sunt niciodată înregistrate.

Crearea și revocarea tokenurilor, precum și aprobările OAuth, sunt de asemenea auditate, ca mcp.token.create, mcp.token.revoke, mcp.oauth.approve, mcp.oauth.deny și mcp.oauth.grant.

Revocați oricând un token sau o aplicație conectată din Settings → Developers → AI connectors. Revocarea unei aplicații OAuth încheie și tokenul său de reîmprospătare.