Clienți

Gateway-ul publică configurații gata de lipit pentru uneltele pe care oamenii le folosesc efectiv. Nimic de pe aceste endpoint-uri nu e secret — cheia ta e mereu un placeholder pe care îl completezi local — așa că sunt publice și deschise CORS.

Ghidurile pas cu pas pentru fiecare unealtă — Cursor, Claude Code, GitHub Copilot, Cline, Continue și Zed — sunt în Integrări.

VS Code (Copilot Chat, Custom Endpoint)Copiază linkul secțiunii

Provider-ul de modele de limbaj Custom Endpoint din VS Code primește un obiect JSON care descrie modelele de adăugat în picker. Gateway-ul îl servește gata construit:

GET https://ai.codai.ro/vscode/chatLanguageModels.json

curl.exe -s https://ai.codai.ro/vscode/chatLanguageModels.json | Set-Clipboard

Picker-ul primește trei intrări, fiecare o identitate fixă de model:

Configurația servită setează header-e care țin gateway-ul un transport transparent: X-Codai-Disable-Subagents: 1, X-Codai-No-Recall: 1, X-Codai-Compact: off, plus X-Codai-Thinking: 1 cu buget per alias și X-Codai-Cache: 1. Copilot deține orchestrarea și transcript-ul; gateway-ul nu rulează niciodată o a doua buclă de agent în spatele lui.

Două endpoint-uri însoțitoare publică o bază curată de setări: GET /vscode/settings.json (setări de utilizator VS Code) și GET /vscode/.copilot/settings.json (Copilot CLI ~/.copilot/settings.json).

GitHub Copilot CLI (BYOK)Copiază linkul secțiunii

Copilot CLI rulează în modul bring-your-own-key când COPILOT_PROVIDER_BASE_URL este setat — autentificarea GitHub nu e necesară. codai este un provider drop-in.

$env:COPILOT_PROVIDER_API_KEY = 'codai_xxxxxxxx'
Invoke-RestMethod https://ai.codai.ro/copilot/env.ps1 | Out-File env.ps1
. .\env.ps1   # dot-source: setează variabilele și lansează copilot

GET /copilot/config returnează aceleași valori ca JSON, inclusiv alias-urile alternative pe care le poți folosi ca wire model (codai-fast, codai-deep, codai-agent, codai-max, codai-explorer, codai-vision) și flag-urile de capabilități (streaming, tool calling, vision și prompt caching sunt pornite; memoria găzduită de GitHub și delegarea remote rămân rutate prin GitHub și nu sunt disponibile în modul BYOK).

Memorie persistentă pentru sesiunile BYOKCopiază linkul secțiunii

Modul BYOK pierde memoria GitHub. Adaugi în schimb serverul MCP codai:

mkdir -p ~/.codai
curl -fsSL -o ~/.codai/mcp-codai.mjs https://ai.codai.ro/copilot/mcp-bridge.mjs
curl -s https://ai.codai.ro/copilot/mcp.json   # lipești `mcpServers` în ~/.copilot/mcp-config.json

Snippet-ul înregistrează un bridge local stdio, nu un server http: CLI-ul nu expandează placeholder-ele ${ENV} în header-ele http, așa că un server remote cu un header Authorization cu template trimite placeholder-ul literal și blochează handshake-ul de 60 s. Bridge-ul citește CODAI_API_KEY sau COPILOT_PROVIDER_API_KEY din mediu și trimite JSON-RPC către /mcp. Înlocuiești ~ din args cu directorul tău home absolut — CLI-ul nu îl expandează. Id-ul serverului este codai (înainte era codai-memory; URL-ul bridge-ului rămâne același). Setezi CODAI_MCP_TOOLSETS (de exemplu cards,web sau all) ca să adaugi grupuri de unelte la setul implicit.

Cursor, Continue, Cline, Zed și alte unelte OpenAI-compatibileCopiază linkul secțiunii

Orice client cu o opțiune de provider OpenAI-compatibil funcționează. Setezi:

Dacă unealta te lasă să setezi header-e custom, X-Codai-Effort: high sau max este cel care merită adăugat. Dacă oferă o listă de modele, o poate citi din GET /v1/models cu cheia ta.

Setările exacte, căile de fișiere și limitele cunoscute pentru fiecare unealtă sunt în Integrări.

Claude Code și unelte native AnthropicCopiază linkul secțiunii

Setezi base URL-ul Anthropic la rădăcină și cheia la cheia ta codai:

export ANTHROPIC_BASE_URL='https://ai.codai.ro'
export ANTHROPIC_API_KEY='codai_xxxxxxxx'
export ANTHROPIC_MODEL='codai'

POST /v1/messages acceptă atât Authorization: Bearer, cât și x-api-key, așa că header-ul implicit al SDK-ului funcționează neschimbat.

Server MCPCopiază linkul secțiunii

Gateway-ul este el însuși un server MCP remote (Streamable HTTP, spec 2025-11-25, compatibil pe fir cu 2025-06-18):

POST https://ai.codai.ro/mcp

Implicit tools/list întoarce setul core: memory_search, memory_store, memory_list, memory_graph, memory_forget, chat, list_models, account_get și usage_get (circa 9 KB de definiții în loc de 90 KB). Celelalte grupuri de mai jos se activează per conexiune, așa că un client plătește context doar pentru ce folosește:

Alegi grupurile cu ?toolsets=cards,web în URL-ul serverului sau cu header-ul X-MCP-Toolsets; all le listează pe toate. O unealtă din afara selecției poate fi apelat în continuare după nume — selecția doar scurtează lista. Uneltele de listare întorc o pagină compactă (de exemplu 20 de rânduri, fără câmpuri interne) dacă nu trimiți limit; detaliile complete vin din unealta *_get corespunzătoare. Expune și prompt-uri (comenzi slash), resurse (codai://models, codai://memory/recent) și completare de argumente de prompt.

Unelte Resolve: resolve_submit (trimiți un issue GitHub, primești o ofertă de preț), resolve_get (urmărești job-ul), resolve_accept (pornește fix-ul — debitează prețul ofertat din portofel, rambursat integral dacă nu rezultă un fix verificat; cere confirm_spend: true, iar un 402 întoarce topup_url) și resolve_attestation (dovada publică de execuție). Necesită o cheie API; token-urile OAuth sunt refuzate.

Unelte Transcrieri: list_transcripts, get_transcript, search_transcripts, ask_transcripts (răspuns din toate înregistrările tale, cu citări), export_transcript (md / txt / srt / vtt / json), accept_transcript_prompt (transformă un prompt sugerat pentru agent într-un prompt în așteptare) și transcript_share_create (un link public doar pentru citire, cu expirare opțională). Ștergerea, revocarea linkurilor, reluarea și editarea unei înregistrări nu sunt expuse. Doar cu cheie API.

Unelte Setări: settings_get (setările la nivel de cont, cu valorile implicite și version) și settings_update (îmbină modificările; trimite version ca să nu suprascrii o schimbare făcută între timp pe alt dispozitiv), plus os_gate_policy, doar pentru citire (dacă organizațiile tale permit excepții de la poarta de protecție a sistemului). Doar cu cheie API. themes_list listează temele de culori curatoriate (Teme); doar citire, fără cheie API.

Unelte Planificator: schedules_list, schedules_runs, schedules_preview (cron sau cuvinte → următoarele rulări), schedules_create, schedules_set_enabled, schedules_run_now, schedules_decide (aprobă / sari o rulare care te așteaptă), heartbeats_list, heartbeats_create (răspunsul conține URL-ul secret de ping, afișat o singură dată) și heartbeats_set_paused. Ștergerea unei programări sau a unui monitor heartbeat și aprobarea unei comenzi terminal pentru o gazdă nu sunt unelte: le face un om. Doar cu cheie API.

Unelte Sesiuni: sessions_list, sessions_get (membri, prezență și lease), sessions_events, sessions_rename, sessions_archive (arhivează sau restaurează) și sessions_dispatch (trimite un mesaj sau deschide sesiunea pe unul dintre dispozitivele tale). Unelte Notificări: notifications_list, notifications_mark_read și notifications_dismiss. Unelte Declanșatoare: triggers_list, triggers_update (redenumire, activare sau dezactivare, politică), triggers_test și triggers_events; crearea sau ștergerea unui declanșator și secretul lui de semnare rămân la tine (desktop, telefon sau API). Ștergerea unei sesiuni nu este o unealtă: o face un om. Aceleași comenzi există în CLI ca codaid sessions, codaid notifications și codaid triggers. Doar cu cheie API.

Linia de comandă pentru memorie și liste: codaid memory list|search|add|rm|clear (rm șterge o singură amintire după id, clear le șterge pe toate; ambele cer confirmare, în afară de --yes) și codaid lists list|show|add|export (add fără listă trimite în Inbox). Ștergerea unei liste nu este o comandă. Agentul găzduit de codaid run primește uneltele lists_list, list_items și list_add, fără ștergere. Hub-ul are pagina Memorie (răsfoire, căutare, adăugare, uitarea unei amintiri); desktopul și telefonul arată cheile tale API (doar editarea etichetelor; cheile se creează și se revocă din hub) și sarcinile verificate (doar citire).

Serverul MCP are și unelte de sandbox: sandbox_create (backend v2 implicit sau v1, TTL, egress none, un preset pypi/npm sau o listă de domenii permise), sandbox_list, sandbox_exec (o linie bash sau cod Python/bash; returnează codul de ieșire, stdout, stderr și chitanța), sandbox_files (list, read până la 256 KiB, write până la 1 MiB sau artifacts cu sha256 și URL-uri semnate de descărcare) și sandbox_kill, plus uneltele v2 sandbox_run_code, sandbox_pause, sandbox_resume, sandbox_fork și sandbox_preview. Rulează cu cheia ta, deci nivelul de unelte l3_sandbox, limitele (3 simultan per cheie, 5 sandbox-uri v2 pornite și 10 pe pauză per utilizator, 7.200 de secunde de execuție pe zi) și contorizarea se aplică exact ca în API-ul REST. Doar cu cheie API.

Serverul MCP are și unelte de Vault (manager de credențiale): vault_list (credențialele expuse agenților: handle {{vault:<slug>}}, titlu, hosturi legate, numele variabilei de mediu, sensibilitate — niciodată o valoare), vault_request_use (o decizie de politică pentru o utilizare: t1/t2 permis, t3/t4 întoarce un approval_id pe care îl aprobi pe desktop, telefon, ceas sau în hub, deny cu motive), vault_http (un apel https în care handle-ul dintr-un antet sau din corp este înlocuit pe server, doar pentru elemente marcate utilizabile în cloud și doar către hosturile lor; răspunsul este redactat), vault_approval_status, vault_add_secret (când lipsește o credențială: primești un link de unică folosință către o pagină codai unde introduci valoarea; clienții care declară capabilities.elicitation.url îl primesc ca elicitare URL -32042, ceilalți ca rezultat obișnuit), vault_add_status (în așteptare, finalizată cu handle-ul {{vault:<slug>}}, anulată sau expirată) și vault_policy_simulate (doar citire: reevaluează utilizările trecute ale agenților tăi sub reguli propuse și arată ce niveluri s-ar schimba; permisiunile nu sunt reevaluate). Agenții nu primesc niciodată valori secrete, iar afișarea sau aprobarea rămân la tine. Doar cu cheie API. codaid vault mcp este un server stdio local cu vault_list, vault_run (rulează o comandă cu handle-urile injectate de brokerul local, cu ieșirea redactată), vault_add_secret, vault_add_status și vault_policy_simulate.

Serverul MCP are și unelte de cont, doar citire: account_get (plan, credite, numărul de sarcini), usage_get (cost și cereri, cu days și group_by opționale), devices_list și hosts_list (token-urile push nu sunt returnate niciodată) și tasks_list, tasks_get, tasks_stats. Confirmarea unei sarcini înseamnă facturare, deci rămâne în hub, pe desktop și pe telefon. Nu există unealtă MCP pentru cheile API. CLI-ul are aceleași vederi: codaid account, codaid usage [--days N], codaid keys list|tag (doar etichete; cheile se creează și se revocă din hub), codaid devices list|hosts, codaid tasks list|show|stats (fără confirmare) și codaid chat "<prompt>", care afișează în flux răspunsul de la codai. Desktopul are paginile Prezentare generală și Utilizare, cu aceleași date ca hub-ul.

Alte unelte MCP: prompts_list și prompts_get (biblioteca ta de prompturi, doar citire; lansarea unui prompt rămâne în aplicații), profile_get, profile_update (doar numele de utilizator) și feedback_submit (vot pozitiv sau negativ pentru unul dintre răspunsurile tale), orgs_list și org_members_list (doar citire), plus studio_renders_list și studio_assets_list (doar citire, fără URL-uri semnate de descărcare; generarea este în toolset-ul studio de mai jos). CLI-ul are aceleași comenzi: codaid prompts list|show, codaid transcripts list|show|search, codaid profile show|set --username, codaid feedback --up|--down, codaid projects list, codaid team list|members <org-id>, codaid referrals și codaid studio renders|assets. Desktopul adaugă paginile Securitate (doar vizualizare; passkey-urile, autentificarea în doi pași și sesiunile se deschid în hub), Proiecte și Echipă; telefonul adaugă ecranele Prezentare generală, Proiecte cloud și Echipă; hub-ul are o pagină Chat cu agentul, care afișează în flux răspunsurile de la codai și le facturează contului tău.

Resolve este acum pe toate suprafețele: desktopul și telefonul îți listează job-urile, arată oferta de preț și dovada, trimit issue-uri noi și acceptă o ofertă după o confirmare care arată prețul și sursa plății (dacă portofelul nu ajunge, pagina de alimentare se deschide în browser; nimic nu se plătește în aplicații). Telefonul primește o notificare când un job primește ofertă sau se termină; desktopul afișează una pentru job-urile pe care le urmărești. codaid resolve list, unealta MCP resolve_list și resolve.list() / resolve.iterate() din ambele SDK-uri îți listează job-urile. SDK-urile primesc și billing (plan, portofel, setările de alimentare automată, facturi și un watcher de sold scăzut; doar citire, plata rămâne în browser) și referrals (linkul tău, statistici și invitații, plus folosirea unui cod și consimțământul pentru recomandări).

Unelte Carduri: cards_weather, cards_places (facturat la prețul de listă Google, 200 pe zi), cards_fx, cards_unfurl, cards_product, cards_route (facturat ca Google Routes), cards_track și cards_efactura. Fiecare întoarce { block, provenance } ca structuredContent — un bloc de card gata de afișat — și varianta lui markdown ca text. Doar cu cheie API.

Unelte web: web_search (căutare verificată cu filtre de domeniu, dată de publicare și prospețime; rezultate ca [S1]..[Sn]), web_fetch (o pagină ca markdown curat, cu focus opțional) și deep_research (un job asincron care întoarce un raport cu citări; dacă nu e gata în ~50 s, unealta întoarce id-ul jobului, iar îl apelezi din nou cu job_id ca să-l preiei). Aceleași nume, scheme și redare ca agenții de pe desktop, telefon, VS Code și headless, din packages/agent-core/spec/tools-web.json. Regulile tale se aplică la fel ca pe /v1/tools/* (web_search și deep_research trec prin gate ca web_search, web_fetch ca browser_fetch). Contorizate ca endpoint-urile REST: 3 $ la 1.000 de căutări rapide, 8 $ la 1.000 aprofundate, 0,50 $ la 1.000 de fetch-uri, 0,20 $ per job de cercetare; primele 1.000 de apeluri pe lună sunt gratuite, iar apelurile din cadrul unei ture de agent codai nu se taxează niciodată.

Unelte Studio (?toolsets=studio): Claude, ChatGPT, Cursor sau VS Code creează și editează creative, rulează producții, documente, operații media și muzică cu aceleași unelte ca agenții codai de pe desktop, telefon și VS Code — aceleași nume, descrieri și scheme, din packages/agent-core/spec/tools-studio.json:

• Creative (gratuit): creative_list, creative_create, creative_outline, creative_get, creative_find, creative_edit (operații pe id-uri de noduri, față de base_seq), creative_lint, creative_lint_fix, creative_versions, creative_revert, creative_templates, creative_save_template, creative_brand_kit_save, creative_restyle, creative_locale_fork, creative_share, creative_review, creative_review_comment, creative_remix, creative_export_lottie, creative_from_document, creative_build, creative_batch, creative_batch_status.
• Cu plată (poarta de plată: întâi ofertă și blocarea sumei în portofel, 402 insufficient_funds când portofelul nu ajunge, fără nicio taxare): studio_image, studio_music, studio_video, studio_render, studio_document, studio_document_preview, studio_document_video, creative_frame, creative_render, creative_variants, creative_brand_extract, creative_captions, creative_adapt, creative_localize, creative_produce (brief → video, imagine, prezentare, document, foaie de calcul, melodie, carusel sau afiș gata), creative_export_fcpxml, studio_media_op, music_create, music_edit. studio_media_ops și studio_sfx listează operațiile și efectele sonore gratuite.
• Job-uri: un apel așteaptă cel mult circa 45 s. Un render, video, preview, export, cadru, o operație media sau o melodie care durează mai mult întoarce status: "pending" cu next_call; apelezi studio_job_status cu acele argumente ca să preiei rezultatul (tot el pune pe creativ melodia terminată de music_create / music_edit). Producțiile și loturile se urmăresc cu creative_produce (production_id) și creative_batch_status.

Rezultatele conțin id-uri de asset și URL-uri semnate de descărcare (valabile o oră); nimic nu se salvează pe calculatorul tău. Ștergerea creativelor, șabloanelor sau kiturilor de brand nu este o unealtă. Doar cu cheie API (Authorization: Bearer codai_…); deocamdată aceste unelte refuză token-urile OAuth.

{
  "servers": {
    "codai": {
      "type": "http",
      "url": "https://ai.codai.ro/mcp?toolsets=studio",
      "headers": { "Authorization": "Bearer ${input:codai-key}" }
    }
  }
}

Două moduri de autentificare:

• Cheie API — Authorization: Bearer codai_…. Îl folosești din scripturi sau prin bridge-ul stdio de mai sus.
• OAuth 2.1 — clienții care îl suportă (VS Code, Claude Desktop, Claude Code, conectori ChatGPT) nu au nevoie deloc de cheie. Îi îndrepți către URL; o cerere neautentificată returnează 401 cu o provocare WWW-Authenticate: Bearer resource_metadata=…, iar GET /.well-known/oauth-protected-resource/mcp îi trimite la auth.codai.ro pentru onboarding automat.

{
  "servers": {
    "codai": { "type": "http", "url": "https://ai.codai.ro/mcp?toolsets=cards,web" }
  }
}

Trimiți Accept: text/event-stream și un apel de tool chat face stream notifications/progress cât timp rulează, apoi rezultatul JSON-RPC. Fiecare cerere MCP trece prin același rate limiter ca /v1, iar apelurile de tool care ajung la un upstream scriu o înregistrare de usage.

Pe care să-l folosești?Copiază linkul secțiunii

• Trăiești în VS Code → configurația Custom Endpoint. Buton de effort, trei roluri, cheie în keychain.
• Trăiești în terminal → Copilot CLI BYOK plus bridge-ul de memorie.
• Folosești alt editor → provider-ul lui OpenAI-compatibil cu base URL-ul /v1.
• Legi un framework de agenți → SDK-urile, sau SDK-ul OpenAI/Anthropic pe base URL-ul potrivit.