Flova Docs

Flova MCP for Studio

Connect agent clients to Studio dashboards through the Flova MCP server.

Flova MCP lets supported agent clients read and edit Flova workspace resources through the Model Context Protocol. Studio tools can list dashboards, read dashboard context, inspect nodes and authoring capabilities, dry-run semantic edits, apply approved edits, save drafts, validate, visually inspect, publish, and archive dashboards.

The hosted endpoint is:

https://mcp.flova.ir/mcp

MCP uses OAuth through Flova Auth. The client opens a browser when it needs access. Sign in, choose the Flova workspace, approve access, and start a fresh agent session when the client asks you to.

Add Flova MCP

These examples register the server with the name flova.

codex mcp add flova --url https://mcp.flova.ir/mcp
codex mcp list

Codex opens Flova Auth during add when needed. Use codex mcp login flova if the OAuth session expires.

Verify and edit safely

Ask the agent to list Flova workspace resources or read the Studio dashboard authoring guide. A connected client exposes only tools allowed by OAuth scopes and the workspace role.

For dashboard changes:

  1. Read dashboard context.
  2. Inspect the page or nodes that will change.
  3. Prepare one small semantic edit batch.
  4. Run the dashboard edit dry run.
  5. Apply the exact successful batch with a new operation ID and preview fingerprint.
  6. Save or validate the draft.
  7. Review the dashboard in Studio before publishing.

For a normal edit, the corresponding tool sequence is:

  1. dashboard_authoring_context
  2. dashboard_nodes_inspect for the affected pages or widgets
  3. dashboard_edit_dry_run with 1 to 12 semantic edits
  4. dashboard_edit_semantic with the exact successful batch, a new operationId, and the returned previewFingerprint
  5. dashboard_visual_inspect at the requested breakpoints
  6. dashboard_validate
  7. dashboard_publish with confirm: true only after explicit human approval

If a dry run fails, follow its returned nextTool and repair guidance, change the edit, and do not resend the same failureFingerprint. If the dashboard has a history conflict, read fresh context before inspecting again. If responsive geometry fails, inspect the affected Grid or Stack and split the content into a smaller responsive parent when needed.

A history conflict means the dashboard changed after the agent read it. Read a fresh context and inspect the affected areas. A responsive geometry error means a Grid or Stack cannot fit the requested content at one or more breakpoints.

AreaExamples
Console authoringTemplates, datastreams, mappings, automations, and versions
Studio authoringDashboards, pages, widgets, bindings, styles, validation, and publishing
FlovaQLCatalog, validation, query execution, and saved-query management
DevicesDevice lists and runtime state
Firmware planningCurrent template and datastream context

MCP does not expose direct device commands, provisioning, flashing, OTA publishing, or activation-code creation. Elevated or destructive operations require confirmation. MCP calls count against the organization plan quota.

The MCP quota is shared by the workspace and resets every 30 days:

PlanMCP calls
Free250
Starter500
Pro2,500
Business10,000

The Console billing page shows the current period's MCP usage. When the quota is exhausted, MCP returns mcp_quota_exhausted with the billing URL.

Return to Assistant for the relationship between external MCP clients and the in-editor Assistant.