Connecting LLM clients (Claude, ChatGPT)

Connect Claude.ai, ChatGPT, or Claude Desktop to the Vincia contributor surface and ship a designer or developer contribution from chat — no local install required. This guide covers the connection for each client, the universal contribution loop, and two worked use cases (a designer template and a developer connector).

The mental model

Three independent choices frame every session:

Both kits share one CLI and one cloud-draft tool-set. Archetypes are only website or portal.

Every web/desktop client connects to one authenticated endpoint:

https://mcp.vincia.io

After the OAuth sign-in, the client gets the full contributor tool-set — plan, scaffold, the vincia_sandbox_* cloud-draft tools, linters, preview renderers, publish, marketplace search, and the feedback channel.

Prerequisites

Connect each client

Claude.ai (web)

ChatGPT (web)

Claude Desktop

{ "mcpServers": { "vincia": { "command": "vincia", "args": ["mcp", "serve"] } } }

This uses your vincia login token. Restart Claude Desktop after any CLI upgrade so it relaunches and surfaces new tools.

Tip: paste the kit's docs/prompt-for-llm.md (and, once you pick a type, prompt-for-{designer,developer}-llm.md) into the chat or a Project's instructions. That loads the authoring rulebook the platform's importer + validator enforce — skipping it is the most common cause of publish-time rejections.

The universal contribution loop

Ask in plain English; the model calls these tools in order:

1. Guided start — vincia_onboarding_intent / _kit_type / _archetype / _tier orient the session. 2. Plan first — vincia_plan_contribution(kind, description) drafts the contract — capability/methods/scopes for a connector, inputs/outputs for a workflow node, props/slots for a widget. The model shows you the plan and waits for approval. Changing a contract here is free; changing a published version costs a version bump and re-review. 3. Scaffold — vincia_scaffold_contribution(type, name) generates the full starter code and returns every file inline. The model receives the complete manifest, source, tests, and docs in the tool response — no filesystem, no terminal. This is the platform's code-writing capability. 4. Open a cloud draft — vincia_sandbox_open_draft(kind, slug) creates the cloud workspace and takes the lock. 5. Write files — vincia_sandbox_write_file (one call per file) seeds the draft with the scaffolded code. Then iterate: _read_file / _write_file / _list_files / _delete_file. 6. Validate — vincia_lint_manifest (developer) checks the manifest offline. 7. Run — vincia_sandbox_run exercises the code in the real workerd sidecar and returns trace, metrics, and logs. For designers, it materialises a hosted preview_url. 8. Release or publish — vincia_sandbox_release hands the draft to another client or teammate. vincia_sandbox_publish submits to marketplace review. 9. Track — vincia_get_review_status. 10. Report friction — vincia_report_issue / vincia_list_issue_reports.

What sandbox_run does, by kind:

Valid open_draft kinds: plugin, widget-pack, blueprint, workflow-node, solution-pack, theme, connector, design-template.

Worked use case — Designer: a website design-template

Goal: ship a reusable website design-template, "Warm-Earth Wellness Studio".

Local-first equivalent: vincia create design-template warm-earth-wellness → edit in IDE → vincia preview (local server, fills slots) → vincia validate → vincia publish.

Worked use case — Developer: a T1 payment connector

Goal: ship a T1 connector, "Razorpay payment connector".

Local-first equivalent: vincia create connector razorpay-payment --capability payment → vincia dev (boots the T1 devcontainer) → vincia test (vitest + manifest lint) → vincia publish.

Other developer tiers follow the same loop with a different kind: blueprint (app/page templates), workflow-node (automation steps), widget (UI components), solution-pack (bundles). Worked examples for every tier ship in the kit's examples/ folder.

Collaboration across clients

A cloud draft is one server-side workspace visible from any client, serialized by a lock — so two clients can co-edit the same draft turn-by-turn:

Hand the lock back and forth with release. The same works for a teammate on another machine or for your terminal (vincia drafts / vincia sandbox) paired with a chat client on the same draft_id. It is turn-taking, not simultaneous live merge — release before the other side picks up.

Publish, review, iterate, report

Which path should a new contributor pick?