Connecting an agent

A VizFor Artifact is a marketing design made of one or more frames. An Artifact can be handed to an agent — yours, or a stranger's — over an MCP endpoint, with a key whose blast radius its owner chose.

Get a key

Two kinds exist, and the difference is the point:

• Account-wide, minted on the API keys screen in Settings. Infrastructure the owner's own program holds.
• Artifact-scoped, minted from Connect an agent in the editor. It reaches exactly one Artifact, expires by default, and cannot create a second one.

Both start vf_sk_. Neither can publish, and no key of any kind spends the product's inference budget — the endpoint executes commands; the reasoning is the caller's own, and nothing sent to it reaches a model VizFor operates.

Reach the endpoint

The endpoint speaks MCP over Streamable HTTP, stateless, with JSON responses:

POST https://<deployment>/api/mcp
Authorization: Bearer vf_sk_…
Content-Type: application/json
Accept: application/json, text/event-stream

In Claude Code, one line does it:

claude mcp add --transport http vizfor https://<deployment>/api/mcp \
  --header "Authorization: Bearer vf_sk_…"

If your runtime does not speak MCP, the protocol is ordinary JSON-RPC 2.0 — initialize once, then call tools. There are no sessions to keep: every request stands alone.

Read the guide before the first edit

curl -H "Authorization: Bearer vf_sk_…" https://<deployment>/api/agent-doc

GET /api/agent-doc returns one markdown document, generated from the same registry the endpoint serves and personalised by the key on the request: which Artifact it reaches, that Artifact's Channel, its frame ids, and the owner's stated intent. Without a key it is the general guide. It is written to be read once, at the start of a session, by something that reads quickly.

These pages and that guide answer different questions on purpose. This section describes the language — what a document is, what the Blocks are, what gets refused — and is public and unauthenticated. The guide describes this endpoint, right now: the tools this deployment actually has wired up, and the one Artifact this key can touch.

A first turn that does not waste itself

1. vf_list_designs — unless you were handed a frame id. Ids cannot be guessed.
2. vf_get_doc — the frame's geometry and safe area, its brief, and a flat list of every node with the id you address it by. Keep the version it returns.
3. vf_apply — the edits, as one batch, with baseVersion set to that version and a one-line note in the owner's language. The note is read by a person: it becomes their history entry.
4. vf_check — the destination's rules. A failure is a real failure and names the node, the parameter and often the value that would pass.
5. vf_screenshot and vf_critique, where the deployment has them — because half of what is wrong with a design is not a rule violation.

Four refusals a first session usually meets

• vf_apply is the only way to write. There is no upload-the-document tool.
• The vocabulary is closed, comments included. An undeclared attribute is refused by name.
• baseVersion is not optional politeness. An edit composed against an old reading is refused rather than landing on a document somebody else has changed underneath it.
• A locked node refuses everything but being unlocked, and so does everything inside it. The reading you already have marks them.

Every tool, with its inputs →