Sari la conținut

Pentru dezvoltatori și agenți AI

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.

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 <cheie>".
  • 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): 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 <cheie> (sau Bearer <cheie>). 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