Vinyasa MCP: URLs, Client Setup, Tools, and Troubleshooting

These URLs are generated from the domain serving this documentation. Client examples, copied article Markdown and Studio's downloaded reference use that same deployment; no hostname needs to be edited manually.

Use the exact MCP URL, not the website root, editor route, /sse, or documentation URL. The public endpoint requires no API key, account, Authorization header, or OAuth. This is separate from the provider credentials used by built-in AI Copilot.

MCP processes supplied documents. It cannot inspect open Studio, retrieve browser IndexedDB projects, operate the UI, render PNG, or save a file on your computer. An external AI client decides what to send and may forward tool results to its own model provider. Review returned YAML before applying it in Studio.

Open MCP: Add Server in the Command Palette, choose HTTP, and enter /mcp. Name the server vinyasa. Alternatively put this configuration in your workspace's .vscode/mcp.json:

{
  "servers": {
    "vinyasa": {
      "type": "http",
      "url": "/mcp"
    }
  }
}

Start the server through VS Code's MCP controls and review the trust prompt. In agent chat, enable its tools, then ask: "Use Vinyasa list_elements, inspect the button and frame schemas, and read vinyasa://reference." Expect five tools. If your client cannot read resources, Help > Download Syntax Ref in Studio provides the same generated reference.

VS Code uses servers, not another client's mcpServers configuration. See VS Code MCP documentation for client management and approval controls.

For Claude Code, register the endpoint from a terminal:

claude mcp add --transport http vinyasa /mcp
claude mcp list

Open Claude Code's MCP controls to inspect connection status and approve tools. See Claude Code MCP setup.

For a client using mcpServers and url, such as Cursor's remote MCP configuration:

{
  "mcpServers": {
    "vinyasa": {
      "url": "/mcp"
    }
  }
}

This JSON is not universal: use your client's documented Streamable HTTP schema. If a hosted assistant offers a connector form, enter the endpoint as its server URL and select no authentication only when supported. Clients requiring OAuth or legacy SSE are not compatible with this public POST-only endpoint; use a compatible Streamable HTTP client. Do not invent a bearer token.

Vinyasa is a hosted application. Do not install a Vinyasa checkout, run npm, configure a local process, or use stdio to connect to the public service. All client configurations in this guide point to /mcp.

All tools return content with type text. Read content[0].text. Schema tools encode JSON text; document tools encode YAML text. Do not save an entire JSON-RPC response as a .rvv file.

source is a YAML STRING, not a parsed object, file path, URL, or .rvv envelope. For a saved .rvv file, extract state and serialize that object as YAML before passing source. export_project name must contain 1-200 characters after trimming.

Read resources/list and resources/read for the Markdown resource vinyasa://reference. It includes common fields, complete document/project examples, coordinate rules, limits and generated property tables. It is an MCP resource identifier, not HTTPS. user-group is a structural type described in the reference, not a catalog entry returned by get_element_schema.

HTTP success does not imply tool success: if result.isError is true, show the error text and correct the input. Invalid tools/arguments can also return a JSON-RPC error. Never apply partial results. Validation enforces supported fields, dimensions, IDs, page ownership, links, nesting, and generated-object budgets.

Paste bare document YAML into Studio's YAML tab. A complete example:

schemaVersion: 1
elements:
  - type: frame
    id: sign-in-form
    pageId: sign-in
    left: 74
    top: 74
    originX: left
    originY: top
    width: 342
    height: 200
    layout: column
    padding: 16
    gap: 16
    children:
      - type: button
        id: continue-button
        left: 16
        top: 16
        width: 160
        height: 44
        text: Continue
pages:
  - id: sign-in
    name: Sign in
    left: 50
    top: 50
    width: 390
    height: 844
    bgColor: '#ffffff'
settings:
  workspaceBgType: transparent
  workspaceBgColor: '#ffffff'
  showRulers: false
  showConnections: true
  showPageLabels: true

Top-level left/top are workspace coordinates. pageId associates content with a page; it does not add the page's left/top. Children use container-local coordinates; row/column frames compute child positions. Only frame and user-group support children; cards/windows do not. Groups must be nonempty; an empty frame is valid. Use originX/originY for explicit top-left placement.

Compact input may omit schemaVersion, pages, settings, IDs and coordinates, but elements is required. Validation supplies defaults; retain its normalized output so IDs/default pages remain stable. Supplied settings must include all its fields. Explicit pages require every page field above. Page IDs and element IDs share one uniqueness namespace.

Pass the latest normalized YAML as source. This is an example edits value, not a whole tool call:

{
  "operations": [
    {
      "op": "update",
      "id": "continue-button",
      "properties": {
        "text": "Sign in"
      }
    },
    {
      "op": "add",
      "parentId": "sign-in-form",
      "element": {
        "type": "button",
        "id": "cancel-button",
        "left": 0,
        "top": 0,
        "text": "Cancel"
      }
    },
    {
      "op": "remove",
      "id": "cancel-button"
    }
  ]
}

The tool arguments are {"source":"","edits":{"operations":[...]}}. Operations run in order and the entire batch fails atomically on invalid input. A batch has 1-200 operations. Update merges properties without changing untouched values; id, type, children and prototype keys cannot be updated. Remove targets an element ID. Add omits parentId for a root element or names an existing frame/user-group for a child. Descendants inherit page ownership. Do not remove the last group child unless you also remove that group in the batch.

For page metadata, settings, identity/type or replacing a children tree, edit full document YAML and validate_document. edit_document is not a page-operation or reparenting API.

1. Read the reference, list_elements, and get_element_schema for required types.
2. Provide source YAML explicitly, or build a complete document with synthetic content and stable IDs.
3. Call validate_document and retain its normalized YAML.
4. Call edit_document using that source, not a stale initial draft.
5. Inspect result.isError and review the returned document.
6. Open /editor, then YAML and AI > YAML; paste bare YAML, validate and Apply to canvas.
7. For file import instead, call export_project with validated source and a name. Save only its returned YAML text as a .rvv file and use File > Import File.

The .rvv envelope has id, name, lastModified, state (the document) and viewState (scrollLeft, scrollTop, zoom). Bare document YAML is not a .rvv envelope. Help > Download Syntax Ref contains complete examples of both formats. After applying in Studio, File > Export As > PNG exports full document bounds including pages, not only the active viewport. MCP itself does not render images.

Example request: "Use Vinyasa MCP. Read the reference and inspect frame/button/input schemas. Create a 390 by 844 sign-in page with a vertical form, explicit IDs and 16-pixel gaps. Validate it. Return normalized bare YAML and a separate export_project .rvv result. Do not claim to have applied anything to my browser."

This is stateless Streamable HTTP with JSON responses. Requests use POST, Content-Type: application/json and Accept: application/json, text/event-stream. An MCP SDK performs initialize and notifications/initialized before discovery/calls; no persistent session ID is issued. An address bar performs GET, so 405 there is expected. No legacy /sse stream is implemented.

This PowerShell request checks discovery without sending project data:

Invoke-RestMethod -Uri '/mcp' -Method Post -ContentType 'application/json' -Headers @{ Accept = 'application/json, text/event-stream' } -Body '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Expect a JSON-RPC result with five tools. This probe does not replace the initialize handshake in a real client. JSON request bodies are capped at 2500000 bytes including JSON escaping; YAML source is separately limited to 2000000 characters. Document limits include 5000 elements, 100 pages, depth 24 and a 50000 generated-object budget. A payload under the byte limit can still exceed rendering complexity.

Cross-origin browser requests are rejected; there is no CORS proxy. Built-in Copilot does not call MCP; it talks directly to its AI provider. Use native MCP client transport rather than a web page fetching this URL.

Do not resolve errors by disabling validation, inventing properties, or silently changing transports/providers. Canvas content stays unchanged until an explicit apply/import.

Connect your MCP client to /mcp. No Vinyasa installation or server setup is required.

Documents supplied to MCP tools are processed by the hosted service. Your MCP client and any connected AI provider may also receive or retain content according to their settings and policies. Send only the content needed for the task, preferably using synthetic data. Never include provider API keys, passwords, access tokens or confidential customer records inside document source.

Review tool results before importing a project or applying YAML. MCP does not remotely control your open canvas, and a successful response does not automatically change your browser project. Keep an editable backup before replacing an existing document.

Read the privacy guidance before sharing document content with a service or assistant.