Working with agents¶

An agent, such as Claude Code or Codex, drives vibe-sketch through the same API the browser uses. It can do so over REST (see the REST API) or, more conveniently, as tools over the Model Context Protocol (MCP):

vibe-sketch mcp

The command speaks MCP on standard input and output. Register it with your agent’s MCP configuration, giving the full path to the installed command if it is not on the agent’s PATH:

{
  "mcpServers": {
    "vibe-sketch": {"command": "vibe-sketch", "args": ["mcp"]}
  }
}

With Claude Code, claude mcp add vibe-sketch -- vibe-sketch mcp does the same.

One document, two editors¶

The tools work through a vibe-sketch server’s REST API, so an agent’s edits and yours go through one revision counter:

If vibe-sketch serve is already running on this machine, the agent uses it and works on the documents you have open: draw in the browser, ask the agent to embed and write inputs, and watch its edits appear.
Otherwise vibe-sketch mcp starts a server of its own in the background, with the files named on its command line open (vibe-sketch mcp scheme.vsk); the status tool gives its address to open in a browser.
--server URL names the server to use; --new-server always starts one.

Tools¶

Tool	Does
`status`	The app’s address, the open documents and the writers.
`new_document`	A new document, empty or from SMILES (a reaction as `A.B>>C`), a name, InChI, MOL, SDF, RXN, CDXML, KET or XYZ.
`open_document`	A file from disk as a new document: a QVF from any vibe program, `.vsk`, MOL, SDF, RXN, CDXML, KET, SMILES or XYZ.
`show_document`	Species with SMILES, charge, multiplicity, name and whether each has a 3D structure; reactions, jobs, warnings.
`report`	Formula, masses, InChI and the checked name of every species.
`add_structures`	Structures drawn beside what is there, or instead of it.
`set_species`	A compound number, a multiplicity or a name.
`clean_up`	Standard bond lengths and angles, the drawing kept.
`embed_3d`	3D structures with the drawn stereochemistry checked.
`write_inputs`	ORCA, vibe-qc, QCSchema or XYZ inputs for species, embedding what has no 3D structure; to a directory or in the answer, with refused species and their reasons.
`export`	QVF, SVG, PNG, MOL, SDF, RXN, SMILES, InChI, KET or `.vsk` to a file.
`save_document`	To a path as QVF (`.vsk` when the path says so), or back to the file the server opened.
`submit_jobs`	ORCA or vibe-qc calculations for species, submitted to vibe-queue and recorded on the document.
`show_runs`	The document’s runs with their state.
`cancel_run`	Cancel a run that has not finished.
`show_in_vibe_view`	A species in 3D in vibe-view, embedded first when needed.
`list_writers`	The writers, their tasks and fields.

A tool that cannot do what was asked answers with the reason, as the writers do; an agent should read it rather than retry with a guess. Each edit is recorded in the document’s provenance as made by an agent through mcp.