--- title: "Pentru dezvoltatori și agenți AI" description: "Cum conectezi un agent AI la MCP-ul de administrare VIStudio: endpoint, OAuth cu PKCE, scope-uri, cheia API, limite, coduri de eroare și draft-first." canonical: https://www.vistudio.ro/developers --- # Pentru dezvoltatori și agenți AI > Cum conectezi un agent AI la MCP-ul de administrare VIStudio: endpoint, OAuth cu PKCE, scope-uri, cheia API, limite, coduri de eroare și draft-first. Sursă: https://www.vistudio.ro/developers Această pagină descrie cum se conectează un agent AI sau un client MCP la VIStudio CMS, ce poate face și în ce condiții. Platforma are două feluri de servere MCP: unul public, doar pentru citire, pe fiecare site, și unul de administrare, pe app.vistudio.ro. ## Când îl folosești (When to use) - **MCP-ul site-ului, pentru citire:** `https://www.vistudio.ro/mcp` (Streamable HTTP). E public, doar pentru citire și nu cere autentificare. Îl folosești ca să citești conținutul publicat. Fiecare site de pe platformă are propriul server la adresa `/mcp`. Fără MCP, orice pagină se poate cere în Markdown, cu antetul `Accept: text/markdown` sau cu `?format=md`, iar `/llms.txt` dă o privire de ansamblu. - **MCP-ul de administrare, pentru administrare:** `https://app.vistudio.ro/mcp`. Cere autentificare și lucrează în numele unei persoane care are cont și rol de webmaster sau admin pe site. Îl folosești ca să creezi și să modifici pagini, secțiuni, meniuri, formulare, SEO, redirecturi, media, articole și traduceri. - Nu trimite niciodată credențiale către www.vistudio.ro: autentificarea și consimțământul există doar pe app.vistudio.ro. ## Endpoint și cont - Endpoint: `https://app.vistudio.ro/mcp` (Streamable HTTP, fără sesiune, răspunsuri JSON). Fiecare cerere are nevoie de antetul `Authorization`. - Conturile le creează administratorii platformei; agenții nu se pot înregistra singuri. Un agent lucrează pentru o persoană care are cont pe site. Pentru un site nou, [cere activarea](https://www.vistudio.ro/activare). ## Conectarea din Claude.ai 1. Settings → Connectors → Add custom connector. 2. Nume `VIStudio CMS`, URL `https://app.vistudio.ro/mcp`. Lasă goale câmpurile OAuth Client ID și Client Secret: înregistrarea clientului e automată. 3. Apeși Connect: se deschide adminul, te autentifici, alegi site-urile și permisiunile, apoi confirmi. 4. Într-o conversație nouă, activezi conectorul din meniul de unelte. ## Conectarea din Claude Code - Cu OAuth (recomandat): `claude mcp add --transport http vistudio-admin https://app.vistudio.ro/mcp`, apoi, în Claude Code, `/mcp` → vistudio-admin → Authenticate. - Cu o cheie API (vezi mai jos): `claude mcp add --transport http vistudio-admin https://app.vistudio.ro/mcp --header "Authorization: users API-Key "`. - Echivalentul în `.mcp.json` sau în alți clienți cu configurație JSON: `{"mcpServers": {"vistudio-admin": {"type": "http", "url": "https://app.vistudio.ro/mcp"}}}`. ## Conectarea din ChatGPT 1. Settings → Connectors → Advanced → pornești Developer mode (necesar pentru conectorii MCP proprii). 2. Create: nume `VIStudio CMS`, URL `https://app.vistudio.ro/mcp`, Authentication: OAuth. Lași goale Client ID și Client Secret. 3. La prima folosire, ChatGPT te trimite în admin pentru autentificare și consimțământ. 4. În conversație: Tools → alegi conectorul. În Developer mode, uneltele care scriu cer confirmarea ta la fiecare apel. ## OAuth 2.1 - Metadatele serverului de autorizare (RFC 8414): `https://app.vistudio.ro/.well-known/oauth-authorization-server`; ale resursei protejate (RFC 9728): `https://app.vistudio.ro/.well-known/oauth-protected-resource`. - Înregistrarea dinamică a clientului (DCR, RFC 7591): `https://app.vistudio.ro/oauth/register`. - Fluxul: `authorization_code` cu PKCE; singura metodă acceptată este `S256`. - Parametrul `resource` este `https://app.vistudio.ro/mcp` (RFC 8707); orice altă resursă e refuzată cu `invalid_target`. - Tokenul de acces durează o oră și se reînnoiește cu `refresh_token`; sesiunea expiră după 30 de zile fără folosire. - Revocarea: în admin → Sesiuni agent (MCP) ștergi sesiunea, iar accesul se oprește imediat; clientul își poate revoca tokenurile la `https://app.vistudio.ro/oauth/revoke`. ## Scope-uri - `mcp:read` (citire): site-urile tale, arborele de pagini, paginile, articolele, media, formularele, birourile, redirecturile, SEO, planul site-ului, rapoartele și linkurile de previzualizare. - `mcp:write` (scriere): drafturi de pagini și articole, blocuri, media, formulare, birouri, redirecturi, SEO, traduceri și task-urile din planul site-ului. - `mcp:publish` (publicare): publicarea și retragerea paginilor și articolelor. - `mcp:admin` (administrare): setările și meniurile, pagina de start și textele site-ului, limbile, destinatarii și trimiterile formularelor, importul de redirecturi și sesiunile agenților. Scope-urile limitează tokenul, iar rolul tău pe site (webmaster sau admin) limitează în plus: unele unelte cer rolul de admin. La consimțământ poți acorda mai puțin decât ai. Cere doar scope-urile de care ai nevoie; lista oficială este `scopes_supported` din metadate. ## Cheia API Pentru scripturi și servere fără browser există o alternativă la OAuth: cheia API. **Cheia API se cere administratorului platformei**, Imagine Infinity ([contact@i8.ro](mailto:contact@i8.ro)): doar el o poate activa pe contul tău, nu o poți genera singur din admin. Se trimite în antetul `Authorization: users API-Key ` (sau `Bearer `). Cheia are toate scope-urile și toate permisiunile rolului tău, pe toate site-urile tale: folosește-o doar în medii de încredere. Pentru aplicațiile de chat, OAuth rămâne varianta recomandată. ## Limite - MCP-ul de administrare: cel mult 120 de apeluri de unelte pe minut pentru fiecare sesiune de agent; peste limită, unealta răspunde cu eroarea `rate_limited`. - OAuth, per IP: `/oauth/token` și `/oauth/revoke` 50 de cereri la 15 minute, `/oauth/register` 10 la 15 minute, `/oauth/authorize` 60 la 15 minute; peste limită, HTTP 429 cu `temporarily_unavailable`. - La intrarea în app.vistudio.ro, per IP: 300 de cereri pe minut, iar pentru autentificare și pentru `/oauth/token`, `/oauth/register` și `/oauth/revoke`, 5 cereri pe minut. - Site-urile, inclusiv MCP-ul lor: 120 de cereri pe minut per IP. - Răspunsurile adminului nu au încă antetul `Retry-After`: după o limită depășită, așteaptă și reîncearcă mai târziu. ## Coduri de eroare - HTTP 401 fără token sau cu un token invalid; antetul `WWW-Authenticate` indică `resource_metadata`, de unde pornește fluxul OAuth. HTTP 403 (`insufficient_scope`) când contul nu mai are rol de webmaster sau admin pe site-urile alese. - Erorile uneltelor MCP au `isError: true` și textul `cod: mesaj`, cu coduri stabile: `unauthorized`, `forbidden`, `not_found`, `invalid`, `rate_limited`, `conflict`, `internal`. - Erorile OAuth urmează RFC 6749: JSON cu `error` și `error_description`, de exemplu `invalid_request`, `invalid_grant`, `invalid_scope`, `invalid_target`, `access_denied`, `invalid_redirect_uri`, `temporarily_unavailable`. ## Draft-first și consimțământul - La conectare te autentifici în admin și alegi site-urile și permisiunile. Agentul lucrează în numele tău, cu rolul tău, doar pe site-urile alese. - Scrierile pe pagini și articole produc drafturi. Publicarea e un pas separat, cu `mcp:publish`, după ce proprietarul site-ului vede previzualizarea. Un site poate porni publicarea directă (`agents.directPublish`), dar ea se aplică doar sesiunilor care au și `mcp:publish`. - Setările, meniurile, formularele, birourile și redirecturile nu au drafturi: sunt live după salvare. La fel și traducerea automată (`translate_document`): scrie direct versiunea publicată a limbilor țintă. - Ștergerile cer confirmare explicită (`confirm: true`), orice scriere se poate simula cu `dry_run`, fiecare acțiune apare în jurnalul agenților din admin, iar versiunile paginilor permit revenirea. ## Versiuni și stare - MCP-ul de administrare este în versiunea 0.x. Anunțăm schimbările incompatibile înainte să le facem. - Lista uneltelor se negociază la conectare: după o actualizare a platformei, reconectează clientul. Unealta `whoami` întoarce `build` (versiunea adminului) și lista uneltelor serverului. - Starea: `GET https://app.vistudio.ro/api/health` întoarce `status` și `build`; fiecare site are și el `/api/health`. ## Documente pentru agenți - [auth.md](https://www.vistudio.ro/auth.md): regulile de acces ale site-ului pentru agenți și clienți MCP. - Cardul MCP-ului de administrare: [server-card.json](https://app.vistudio.ro/.well-known/mcp/server-card.json); al MCP-ului site-ului: [server-card.json](https://www.vistudio.ro/.well-known/mcp/server-card.json). - Skill-urile adminului (`connect-agent`, `administer-site`): [agent-skills/index.json](https://app.vistudio.ro/.well-known/agent-skills/index.json); ale site-ului: [agent-skills/index.json](https://www.vistudio.ro/.well-known/agent-skills/index.json). - Descoperirea adminului: [mcp.json](https://app.vistudio.ro/.well-known/mcp.json); ghidul de conectare, în română: [app.vistudio.ro/mcp/guide](https://app.vistudio.ro/mcp/guide).