Skip to main content
Versuno gives you two ways to work with assets outside the dashboard: the MCP server and the CLI. They share the same .versuno/ folder layout and frontmatter schema, but they’re built for different workflows.

​
The short version

MCP serverCLI
Who drives itYour AI coding agentYou
How you invoke itDescribe what you want in chatType a command in the terminal
Best forIn-context asset loading, agent-assisted editingBulk sync, scripting, CI/CD, version history
Runs inYour IDE (Cursor, VS Code, Claude Code, Windsurf, Zed, Antigravity)Any terminal
Requires Node.jsYes (via npx)Yes (via npm install)
AuthVERSUNO_API_KEY env varversuno login (stores token locally)

​
Use the MCP when

You want the agent to load context it finds itself. Instead of manually hunting for the right prompt or persona, you tell the agent what you’re trying to do and it calls search_assets + get_asset to pull the relevant pieces into the conversation. The agent can also draft edits and push them back with push_asset. You’re mid-conversation and need a quick reference. Asking the agent “load the onboarding context” takes one message. Running versuno pull requires switching to a terminal, running the command, and switching back. You’re working in a single project with one active workspace. The MCP operates in the context of whatever directory the IDE opened. It doesn’t know about other projects unless you open them.

​
Use the CLI when

You want to sync an entire project at once. versuno pull downloads all assets for the active project in one go. The MCP’s pull_asset works one asset at a time. You’re writing scripts or building CI pipelines. The CLI is designed to be scripted. You can run versuno push in a pre-commit hook or a GitHub Actions workflow. The MCP only runs interactively, driven by an agent. You need to see version history or compare diffs. versuno log and versuno diff have no MCP equivalents. If you want to audit what changed between versions, use the CLI. You manage multiple projects or switch teams frequently. versuno switch, versuno projects use, and versuno projects pull are CLI-only. The MCP doesn’t expose project management tools. You want predictable, reviewable output without an LLM in the loop. CLI output is deterministic. The MCP relies on the agent interpreting your intent correctly, which is great for exploratory work but less reliable for automated pipelines.

​
Using them together

They’re not mutually exclusive. A common workflow:
  1. Use the MCP to find and load an asset while working with an agent (search_assets, get_asset).
  2. The agent drafts changes. You review them in your editor.
  3. Use push_asset (MCP) or versuno push (CLI) to ship the new version, whichever is more convenient at that moment.
  4. Use versuno log (CLI) later to review the full version history.
Both tools read and write the same .versuno/ files using the same frontmatter schema, so there’s no lock-in. Switch back and forth freely.