Skip to content

For developers and AI agents

This page explains how an AI agent or an MCP client connects to VIStudio CMS, what it can do and under which conditions. The platform has two kinds of MCP servers: a public, read-only one on every site, and an administration one on app.vistudio.ro.

When to use

  • The site MCP, for reading: https://www.vistudio.ro/mcp (Streamable HTTP). It is public, read-only and needs no authentication. Use it to read the published content. Every site on the platform has its own server at /mcp. Without MCP, any page can be requested as Markdown, with the Accept: text/markdown header or with ?format=md, and /llms.txt gives an overview.
  • The admin MCP, for administration: https://app.vistudio.ro/mcp. It needs authentication and acts on behalf of a person who has an account and a webmaster or admin role on the site. Use it to create and change pages, sections, menus, forms, SEO, redirects, media, posts and translations.
  • Never send credentials to www.vistudio.ro: sign-in and consent exist only on app.vistudio.ro.

Endpoint and account

  • Endpoint: https://app.vistudio.ro/mcp (Streamable HTTP, stateless, JSON responses). Every request needs an Authorization header.
  • Accounts are created by the platform administrators; agents cannot register themselves. An agent acts for a person who has an account on the site. For a new site, request activation.

Connecting from Claude.ai

  1. Settings → Connectors → Add custom connector.
  2. Name VIStudio CMS, URL https://app.vistudio.ro/mcp. Leave the OAuth Client ID and Client Secret fields empty: client registration is automatic.
  3. Press Connect: the admin opens, you sign in, choose the sites and the permissions, then confirm.
  4. In a new conversation, turn the connector on from the tools menu.

Connecting from Claude Code

  • With OAuth (recommended): claude mcp add --transport http vistudio-admin https://app.vistudio.ro/mcp, then, in Claude Code, /mcp → vistudio-admin → Authenticate.
  • With an API key (see below): claude mcp add --transport http vistudio-admin https://app.vistudio.ro/mcp --header "Authorization: users API-Key <key>".
  • The equivalent in .mcp.json or in other clients with a JSON configuration: {"mcpServers": {"vistudio-admin": {"type": "http", "url": "https://app.vistudio.ro/mcp"}}}.

Connecting from ChatGPT

  1. Settings → Connectors → Advanced → turn on Developer mode (required for custom MCP connectors).
  2. Create: name VIStudio CMS, URL https://app.vistudio.ro/mcp, Authentication: OAuth. Leave Client ID and Client Secret empty.
  3. On first use, ChatGPT sends you to the admin to sign in and give consent.
  4. In a conversation: Tools → choose the connector. In Developer mode, the tools that write ask for your confirmation on every call.

OAuth 2.1

  • Authorization server metadata (RFC 8414): https://app.vistudio.ro/.well-known/oauth-authorization-server; protected resource metadata (RFC 9728): https://app.vistudio.ro/.well-known/oauth-protected-resource.
  • Dynamic client registration (DCR, RFC 7591): https://app.vistudio.ro/oauth/register.
  • Flow: authorization_code with PKCE; the only accepted method is S256.
  • The resource parameter is https://app.vistudio.ro/mcp (RFC 8707); any other resource is rejected with invalid_target.
  • The access token lasts one hour and is renewed with refresh_token; the session expires after 30 days without use.
  • Revoking: in the admin → Sesiuni agent (MCP) (agent sessions), delete the session and access stops at once; a client can revoke its own tokens at https://app.vistudio.ro/oauth/revoke.

Scopes

  • mcp:read (read): your sites, the page tree, pages, posts, media, forms, offices, redirects, SEO, the site plan, reports and preview links.
  • mcp:write (write): drafts of pages and posts, blocks, media, forms, offices, redirects, SEO, translations and the tasks of the site plan.
  • mcp:publish (publish): publishing and unpublishing pages and posts.
  • mcp:admin (administration): settings and menus, the homepage and site texts, languages, form recipients and submissions, redirect imports and agent sessions.

Scopes limit the token, and your role on the site (webmaster or admin) limits it further: some tools need the admin role. At consent you can grant less than you have. Request only the scopes you need; the official list is scopes_supported in the metadata.

API key

For scripts and servers without a browser there is an alternative to OAuth: the API key. The API key is requested from the platform administrator, Imagine Infinity (contact@i8.ro): only they can enable it on your account, you cannot generate it yourself in the admin. It is sent in the Authorization: users API-Key <key> header (or Bearer <key>). The key has all the scopes and all the permissions of your role, on all your sites: use it only in trusted environments. For chat applications, OAuth remains the recommended way.

Limits

  • Admin MCP: at most 120 tool calls per minute for each agent session; above the limit, the tool answers with the rate_limited error.
  • OAuth, per IP: /oauth/token and /oauth/revoke 50 requests per 15 minutes, /oauth/register 10 per 15 minutes, /oauth/authorize 60 per 15 minutes; above the limit, HTTP 429 with temporarily_unavailable.
  • At the entrance to app.vistudio.ro, per IP: 300 requests per minute, and 5 requests per minute for sign-in and for /oauth/token, /oauth/register and /oauth/revoke.
  • The sites, including their MCP: 120 requests per minute per IP.
  • The admin responses do not carry a Retry-After header yet: after hitting a limit, wait and retry later.

Error codes

  • HTTP 401 without a token or with an invalid one; the WWW-Authenticate header points to resource_metadata, where the OAuth flow starts. HTTP 403 (insufficient_scope) when the account no longer has a webmaster or admin role on the consented sites.
  • MCP tool errors have isError: true and the text code: message, with stable codes: unauthorized, forbidden, not_found, invalid, rate_limited, conflict, internal.
  • OAuth errors follow RFC 6749: JSON with error and error_description, for example invalid_request, invalid_grant, invalid_scope, invalid_target, access_denied, invalid_redirect_uri, temporarily_unavailable.

Draft-first and consent

  • When connecting, you sign in to the admin and choose the sites and the permissions. The agent acts on your behalf, with your role, only on the sites you chose.
  • Writes to pages and posts create drafts. Publishing is a separate step, with mcp:publish, after the site owner has seen the preview. A site can turn on direct publishing (agents.directPublish), but it applies only to sessions that also have mcp:publish.
  • Settings, menus, forms, offices and redirects have no drafts: they are live once saved. The same goes for automatic translation (translate_document): it writes the published version of the target languages directly.
  • Deletes need explicit confirmation (confirm: true), any write can be simulated with dry_run, every action appears in the agent log in the admin, and page versions let you go back.

Versions and status

  • The admin MCP is at version 0.x. We announce incompatible changes before making them.
  • The tool list is negotiated when the client connects: after a platform update, reconnect the client. The whoami tool returns build (the admin version) and the list of the server tools.
  • Status: GET https://app.vistudio.ro/api/health returns status and build; every site also has /api/health.

Documents for agents