Working with agents

An agent, such as Claude Code or Codex, drives vibe-sketcher 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-sketcher 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-sketcher server’s REST API, so an agent’s edits and yours go through one revision counter:

• If vibe-sketcher 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-sketcher mcp starts a server of its own in the background, with the files named on its command line open (vibe-sketcher 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.

Select the session and document explicitly

Automatic discovery checks loopback ports 8766 through 8775 and uses the first recognized server. If several sketcher instances are running, or the intended server uses another port, set --server to the address it printed:

vibe-sketcher mcp --server http://127.0.0.1:8766

Call status, inspect the listed documents, and pass the chosen document ID in each tool’s document argument. Omitting it uses the server’s default (or a fallback open document), which need not be the drawing you are looking at in another browser tab. Use the species IDs from show_document for subsequent operations.

An MCP-started server runs inside that MCP process. Save before disconnecting the client if you want to retain its documents. For a browser session that should outlive the agent connection, start vibe-sketcher serve separately and connect with --server.

Files and saving

File paths belong to the machine and working directory running the MCP command. Prefer absolute paths when an agent client may launch the command from another directory. A remote REST server does not make the MCP process’s local paths available on that remote machine.

open_document reads a local file and creates a document by sending its contents to REST; it does not attach that file as a server-side save target. For such documents, give save_document an explicit path. Saving to a path exports a copy and does not establish a backing file for future pathless saves. Without a path, saving works only for a document the server already associates with a file, such as one opened by vibe-sketcher serve FILE.

Use a .vsk destination when QVF support is unavailable. Other suffixes on save_document select QVF, with an unrecognized suffix replaced by .qvf; they do not request an exchange-format export. Use export for SVG, MOL and other formats. Choose a new output directory for inputs to keep previous calculations’ files separate.

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, a peptide, DNA or RNA sequence, HELM, 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. A finished QVF job container opens with its drawing, the result geometry as a new conformer and, as result, the job, its status and the energy.
show_document	Species with SMILES, charge, multiplicity, name and whether each has a 3D structure; reactions, jobs, generic structures and R-group definitions (CXSMILES), warnings.
report	Formula, masses, InChI, elemental analysis, descriptors and the checked name of every species.
highlight_atoms	Mark atoms of a species, numbered as in the report, in a colour-blind-safe palette colour for the canvas and figures.
clear_highlights	Remove every highlight, or those of one species.
list_abbreviations	The abbreviations (Ph, Boc, OTf …) that can be contracted, and those contracted in each species.
contract_abbreviations	Draw such groups as their label on the canvas and in figures, for one species or all; the structure is unchanged.
expand_abbreviations	Draw contracted groups as their atoms again.
add_nanostructure	Generate a nanotube, graphene flake, nanoribbon or fullerene from its parameters as a species with 3D atoms and a NANO- key.
cap_generic	Make a calculable species of a labelled structure (bonded to CNT, Au, …) by replacing each label with H or CH3; show_document lists labelled structures under generics.
depict_nanostructure	Put a picture of a nanostructure species on the canvas: lattice, schematic, end-on or unrolled.
attach_to_nanostructure	Move a labelled structure onto a picture’s anchor (lower-end, upper-end, sidewall), so figures print them as one.
add_half_reaction	Draw an electrode half-reaction with states, coefficients, electrons and a potential.
check_balance	Each reaction’s atom and charge balance, electrons included.
add_tlc_plate	Draw a TLC plate beside the drawing: lanes with labels and spots’ Rf values.
add_apparatus	Draw a laboratory apparatus pictogram (flask, condenser, column, …) from shapes, beside the drawing or at a point, with an optional label.
show_stereo	Each species’ CIP descriptors, undefined stereocentres and double bonds, and enhanced-stereo groups.
label_stereo	Write the descriptors into the drawing as labels, or remove them with clear.
set_amounts	Enter a reaction’s amounts (mmol, mass, volume with density or concentration, or equivalents) for its stoichiometry table.
show_stoichiometry	A reaction’s worked stoichiometry table, as JSON or a CSV, Markdown or LaTeX table.
export_property_table	The species property table (formula, masses, analysis line, descriptors) as CSV, Markdown or LaTeX.
place_property_text	Put a species’ formula, molar mass and analysis (or chosen fields) as text under its structure.
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.
tidy_scheme	The whole reaction scheme laid out as papers draw it, its steps and reactions kept; refused with the reason when it cannot be.
embed_3d	3D structures with the drawn stereochemistry checked.
relax_3d	3D structures relaxed with FIRE on MMFF94 or UFF, constraints (distance, angle, dihedral, fixed atom) held exactly; species without 3D are embedded first.
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.
map_reaction	A reaction’s atom mapping by the fewest bonds changed, for review before a path input; ambiguous pairings are listed, pins correct them.
write_neb_inputs	ORCA NEB-TS, NEB-CI or NEB, or a vibe-qc CI-NEB script, for a reaction, with the mapping it rests on; refused with reasons when the mapping is ambiguous.
export	QVF, SVG, PNG, PDF, MOL, SDF, RXN, SMILES, InChI, HELM, FASTA, KET, .vsk or chemfig (LaTeX) to a file; sequences prints peptides and nucleic acids as their sequences in figures.
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, for the species of reactions (each distinct species once) or for the whole scheme, submitted to vibe-scheduler as one group and recorded on the document; a vibe-qc job as a QVF job container that keeps the sketch with its result (container false: a run script), with fallbacks saying why a script went instead.
show_runs	The document’s runs with their state and group.
import_run_result	Import a local ORCA output or finished QVF file for an explicitly named run, checking input identity and source provenance; an ORCA optimisation’s geometry becomes a structure of the species, and orca-hess checks a Hessian file.
export_spectrum	Return a run’s IR, Raman or UV-Vis line list, or its spectrum broadened with a Gaussian or Lorentzian of a given FWHM, as text with units in the header.
show_nmr	A run’s NMR shieldings per set of equivalent nuclei and its shifts against a reference run at the same level, as JSON or a line list.
place_nmr_labels	Put a run’s shifts as text beside the atoms of its species’ drawn structure.
export_energy_table	Return CSV, Markdown or booktabs LaTeX from an explicit result selection, including coefficients, method and source runs.
campaign_energy_report	Report/export electronic reaction energies from an explicit recipe, campaign and correlated stage; verify accepted artifacts and retain review warnings.
show_reaction_energies	Report a selected group or explicit runs with reaction coefficients; refuse missing, stale or incompatible evidence.
show_groups	The document’s run groups with the runs in each state and whether each has finished.
cancel_run	Cancel a run that has not finished.
cancel_group	Cancel the runs of a group that have not finished.
show_recipes	The staged recipes, each stage per species as vibe-qc would run it, with refusals.
set_recipe	Save the publication baseline recipe for species, reactions or the scheme, or a full recipe object; returns the review.
remove_recipe	Remove a recipe.
compile_campaign	Compile a recipe into a vibe-scheduler campaign in a new directory; a MACE stage needs accept_model_license.
campaign_status	A campaign’s stages: process state and, apart from it, scientific acceptance.
render_campaign_stages	A species’ start and accepted stages in one orientation, from the campaign’s verified artifacts, with vibe-viewer’s images when installed.
retry_campaign_node	Authorise the next attempt of a failed campaign node.
show_in_vibe_view	A species in 3D in vibe-viewer, 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.

save_document and export refuse to overwrite QVF results, unknown payloads or damaged QVF files. Choose a different path for the edited sketch. Importing a calculation result reads its structures but does not preserve its original calculation payloads in the exported sketch.

Named reactions

See the compound, fragment and named-reaction library for the searchable picker, editable examples, explicit unfinished scaffolds, source coverage and matching SDK, CLI, REST and MCP operations.