MCP Server

AVC includes a built-in Model Context Protocol server. Any agent that speaks MCP can call AVC’s commands as tools — no separate process to manage, no HTTP layer to configure.

Start the server

avc mcp serve                    # default: the "standard" tier, pretty output
avc mcp serve --tools core       # minimal 4-tool set
avc mcp serve --tools full       # every tool
avc mcp serve --compact          # compact JSON for token-sensitive contexts

The server runs over stdio: it reads JSON-RPC 2.0 messages on stdin and writes responses on stdout. Agent frameworks spawn it as a subprocess.

When the server is pointed at a directory with no .avc/ project, tools/list returns an empty set — agents never see tools they can’t use.

Tool tiers

Tools are exposed in three tiers (--tools core|standard|full) so agents with small context windows aren’t handed everything at once. standard is the default.

Tool	Tier	Maps to
`avc_snapshot`	core	`avc snapshot` — accepts `session_id` / `task`
`avc_list`	core	`avc list`
`avc_diff`	core	`avc diff`
`avc_restore`	core	`avc restore`
`avc_status`	standard	`avc status`
`avc_undo`	standard	`avc undo`
`avc_branch_create`	standard	`avc branch create` — `from_branch` to stack
`avc_branch_list`	standard	`avc branch list`
`avc_branch_switch`	standard	`avc branch switch`
`avc_branch_diff`	standard	`avc branch diff` — `against` for cross-branch, `stat` for a compact summary
`avc_merge`	standard	`avc merge`
`avc_merge_abort`	standard	`avc merge --abort`
`avc_info`	full	`avc info`
`avc_delete`	full	`avc delete`
`avc_branch_rename`	full	`avc branch rename`
`avc_branch_abandon`	full	`avc branch abandon`
`avc_branch_prune_merged`	full	`avc branch prune --merged`
`avc_merge_preview`	full	`avc merge --preview`
`avc_merge_train`	full	`avc merge --train` — merge a fleet in sequence
`avc_run_in_workspace`	full	Run a shell command inside a branch workspace; reports `files_created` (gated — see below)
`avc_bisect`	full	`avc bisect` (gated — see below)
`avc_restore_file`	full	`avc restore-file` — workspace-aware
`avc_annotate`	full	`avc annotate`
`avc_tag_snapshot` / `avc_untag_snapshot`	full	`avc snapshot tag`
`avc_list_conflicts` / `avc_resolve_conflict`	full	Inspect and resolve merge conflicts

Each tool’s JSON Schema is published via tools/list so the agent can discover them programmatically.

Agent-friendly behaviors

avc_branch_diff never overflows the result limit. A full diff of a large branch can be several MB — too big for a single tool result. When that happens the tool automatically falls back to a per-file summary (and truncates it if the branch changed a huge number of files), always noting what it did. Pass stat: true to request that compact summary directly.
avc_run_in_workspace reports what a command created. The response includes files_created / files_created_count: files the command wrote that are not yet ignored and would enter the next snapshot. If they are build or test artifacts, add their directory to the workspace .avcignore before calling avc_snapshot — ignoring them afterward won’t remove them (ignoring never untracks a file that’s already tracked).
avc_snapshot reports new_files and carried_files so an unexpected spike in tracked files — like a flood of test output — is visible immediately.

The `[run] enabled` gate

avc_run_in_workspace and avc_bisect execute commands, so they are refused unless a human sets [run] enabled = true in .avc/config.toml. Agents cannot enable it themselves — the gate exists precisely to stop autonomous command execution. (The CLI avc run is a human-invoked command and is not gated; see avc run.)

Similarly, avc_merge and avc_merge_train have no protected-paths override — only a human running avc merge --allow-protected can lift the [protect] gate.

Don’t configure it by hand

Use the one-shot setup instead:

avc init --skills claude-code,cursor,windsurf,generic

This writes the right config files for each framework into your project. See the per-framework guides:

Manual integration

For custom agents not covered by --skills, here’s the minimal config snippet:

{
  "mcpServers": {
    "avc": {
      "command": "avc",
      "args": ["mcp", "serve", "--tools", "standard"]
    }
  }
}

Drop that into whatever MCP config file your framework uses. Most frameworks (Claude Desktop, Cline, etc.) follow this convention. For frameworks with a per-project config, prefer the project-local file so the AVC server stays scoped to the project.

When the agent should use each tool

AVC ships agent skill files (e.g., .claude/skills/avc-snapshot/SKILL.md) that document when to call which tool. These are written by avc init --skills and serve as instructions to the agent — “always snapshot before risky changes”, “use branches for non-trivial refactors”, etc.

If you write your own agent, you can copy the skill files as a starting point for your prompt engineering.