Lovision MCP

lovision-mcp

Lovision MCP lets external agents create, understand, edit, preview, export, and hand off real Lovision native designs. Treat it as a governed design workflow interface, not raw canvas CRUD: sessions, target resolution, permissions, capability profiles, Blueprint, quality checks, receipts, and recovery actions are all part of the contract.

The Remote MCP server should be registered as lovision-remote. Its endpoint is:

https://mcp.lovision.ai/

Lovision MCP is Early Access. If OAuth does not start after connecting the server, the user may need Lovision to enable MCP for their account and provide the current authorization method.

First Call: lovision.session.init

On any new conversation or after SESSION_NOT_FOUND, call lovision.session.init before using other Lovision tools.

Pass:

• runtime: use remote-web when connected through lovision-remote / https://mcp.lovision.ai; use desktop-local only when connected through lovision-desktop / Lovision Desktop Local MCP; use internal only for trusted internal environments.
• agentCredential: normally omit this. Remote MCP OAuth clients must rely on the MCP transport Authorization bearer from login/re-auth. Desktop Local MCP normally does not require Oneauth login; only pass a local dev credential when a local bridge explicitly documents one.
• target: any known projectId, documentId, pageId, or mode.

Do not guess targets. If the user did not provide a clear project/document/page, use project tools to resolve the target or ask a short clarification before writing.

Canonical Workflow

For design creation or meaningful edits:

lovision.session.init
  -> target resolution / lovision.projects.open / lovision.document.create
  -> lovision.document.getContext + lovision.capabilities.list
  -> lovision.knowledge.* / fonts / tokens / components / media as needed
  -> lovision.blueprint.validate
  -> lovision.blueprint.apply or capability-gated advanced tools
  -> lovision.quality.check + lovision.preview.capture
  -> targeted repair if needed
  -> lovision.export or lovision.workflow.submit if requested
  -> lovision.session.finishWork

For read-only requests, stop after context, lookup, preview, quality, export, or project listing as appropriate, then call finishWork unless the user explicitly wants the session left open.

Tool Routing

Session and lifecycle:

• lovision.session.init
• lovision.session.status
• lovision.capabilities.list
• lovision.production.status
• lovision.session.finishWork
• lovision.session.abortWork

Project operations:

• Projects: lovision.projects.list, get, create, update, duplicate, move, delete, restore, export, open
• Folders: lovision.folders.list, create, update, delete
• User metadata: lovision.projectFavorites.set, lovision.projectRecents.list
• Sharing: lovision.projectSharing.get, updateLinkAccess, invite, revoke, updateRole

Document, pages, viewport, and lookup:

• lovision.document.create
• lovision.document.getContext
• lovision.lookup
• Pages: lovision.pages.list, switch, create, rename, duplicate, delete, getBackground, setBackground
• Selection and viewport: lovision.selection.set, lovision.viewport.fit, lovision.viewport.focus
• Layout guides: lovision.layoutGuides.getFrame, setFrame, addFrameGuide

Design creation and editing:

• Blueprint: lovision.blueprint.validate, lovision.blueprint.apply
• Streaming design: lovision.design.stream.start, applyChunk, finalize, abort
• Advanced node editing: lovision.nodes.apply
• Text ranges: lovision.textStyles.applyRange
• Components: lovision.components.list, lovision.components.get, lovision.componentSets.create
• Schema lookup: lovision.schema.get

Design system data:

• Fonts: lovision.fonts.summary, list, resolve, warm
• Tokens: lovision.tokens.summary, resolve, propose, commitProposal
• Knowledge: lovision.knowledge.list, lovision.knowledge.get

Assets, media, and local files:

• Media acquisition: lovision.media.acquire
• Binary resources: lovision.binary.create, read, dispose
• Image insertion: lovision.assets.insertImage
• Workflow input resolution: lovision.assets.resolveWorkflowInput
• Local files: lovision.localFiles.requestAccess, listGrants, read, revoke

Quality and delivery:

• lovision.quality.check
• lovision.preview.capture
• lovision.export
• lovision.workflow.submit

Hard Rules

1. Use Host Facade backed writes. Never invent payloads that depend on engine stores, Liveblocks internals, React state, renderer internals, raw patches, or extraFields.data.config.
2. Prefer Blueprint for complex design work. Use lovision.blueprint.validate and lovision.blueprint.apply for structured creation and patching.
3. Use canonical public payload fields. Text should use text.content, text.layout.mode, text.baseStyle, and text.styleRanges. Shapes/vectors/images should use fields such as shape, shapeParams, cornerRadius, vectorPath, and imageRef.
4. Respect capability profile. Discovery is not authorization. Trust session.init, document.getContext, and capabilities.list over guesses. Invocation-time enforcement is expected.
5. Write safely. Include expectedVersion and idempotencyKey when a write tool accepts them.
6. Verify user-visible changes. After meaningful writes, run quality.check and preview.capture; patch actionable findings when practical.
7. Do not roll back committed mutations because delivery failed. Preview, export, workflow, or asset-staging failures should produce a safe stopping point and resume action.
8. Preserve media provenance. Use Lovision-generated or product media first, licensed fallback second, explicit placeholder last. Keep unresolved media findings visible.
9. Resolve fonts and tokens before relying on them. Use lovision.fonts.* and lovision.tokens.*.
10. Do not read arbitrary local paths. Desktop Local MCP file access must go through lovision.localFiles.* grants. Remote MCP cannot read local files.
11. Finish non-trivial sessions. Use lovision.session.finishWork with changed nodes, artifacts, unresolved findings, and resume action. Use abortWork only for cancellation or unrecoverable setup failure.

Capability And Error Handling

Maturity tiers:

• unknown
• claimed
• verified
• trusted-internal

Runtime values:

• remote-web
• desktop-local
• internal

Common structured errors:

• PERMISSION_DENIED: explain the missing permission or ask the user to re-authorize.
• CAPABILITY_NOT_AVAILABLE: pick a supported fallback or report the limitation.
• REQUIRES_AGENT_MATURITY: do not retry blindly; explain that this agent/client is not trusted enough for that tool.
• APPROVAL_REQUIRED: surface the approval request and wait for the user/client.
• RATE_LIMITED or QUOTA_EXCEEDED: stop at a safe point and include a resume action.
• SESSION_NOT_FOUND: call lovision.session.init again.

Media Ladder

When the design needs media:

1. Use Lovision generation or an existing Lovision product asset.
2. Use a licensed external fallback only if generation/product asset is unavailable or unsuitable.
3. Use an explicit placeholder only as a last resort, and include a quality finding or handoff note.

Supported binary image MIME types currently include image/png, image/jpeg, image/webp, and image/svg+xml. lovision.binary.create is capped at 10 MB.

Setup Notes

Remote MCP config:

{
  "mcpServers": {
    "lovision-remote": {
      "type": "streamable-http",
      "url": "https://mcp.lovision.ai/"
    }
  }
}

Claude Code manual setup:

claude mcp add --transport http lovision-remote https://mcp.lovision.ai/

Codex manual setup:

codex mcp add lovision-remote --url https://mcp.lovision.ai/
codex mcp login lovision-remote

Desktop Local MCP should be a separate server, typically named lovision-desktop. It uses the loopback URL and bearer secret shown in Lovision Desktop Settings > MCP. Do not hand-write a Desktop config without the copied Authorization header.

Claude / Cursor Desktop Local MCP config shape:

{
  "mcpServers": {
    "lovision-desktop": {
      "type": "http",
      "url": "http://127.0.0.1:3846/mcp",
      "headers": {
        "Authorization": "Bearer <copied-from-lovision-desktop>"
      }
    }
  }
}

Codex Desktop Local MCP config shape:

[mcp_servers.lovision-desktop]
type = "http"
url = "http://127.0.0.1:3846/mcp"

[mcp_servers.lovision-desktop.http_headers]
Authorization = "Bearer <copied-from-lovision-desktop>"

Always copy the actual Desktop config because the port and secret are local to the user's machine.