> ## Documentation Index
> Fetch the complete documentation index at: https://docs.versuno.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP vs CLI

> Choosing between the Versuno MCP server and the Versuno CLI.

Versuno is built to reach the tools you already work in. Your prompts come down into your IDE and your terminal through two clients: the [MCP server](/mcp/overview) and the [CLI](/cli/overview). Both read and write the same `.versuno/` folder layout and frontmatter schema, so you can move between them freely. They're built for different workflows.

<Note>
  The MCP server works with both your prompts (assets) and public [brains](/brains/overview). The CLI works with your prompts only. Brains are also available directly through the [public API](/api-guide).
</Note>

## The short version

|                   | [MCP server](/mcp/overview)                                         | [CLI](/cli/overview)                         |
| ----------------- | ------------------------------------------------------------------- | -------------------------------------------- |
| Who drives it     | Your AI coding agent                                                | You                                          |
| How you invoke it | Describe what you want in chat                                      | Type a command in the terminal               |
| Best for          | In-context asset loading, agent-assisted editing                    | Bulk sync, scripting, CI/CD, version history |
| Runs in           | Your IDE (Cursor, VS Code, Claude Code, Windsurf, Zed, Antigravity) | Any terminal                                 |
| Requires Node.js  | Yes (via npx)                                                       | Yes (via npm install)                        |
| Auth              | `VERSUNO_API_KEY` env var                                           | `versuno 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 prompts 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 prompts 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 prompts 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 prompts log` and `versuno prompts 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 prompts projects use`, and `versuno prompts 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 prompts push` (CLI) to ship the new version, whichever is more convenient at that moment.
4. Use `versuno prompts log` (CLI) later to review the full version history.

Both tools read and write the same `.versuno/` files using the same [frontmatter schema](/mcp/frontmatter), so there's no lock-in. Switch back and forth freely.