Avo MCP tools reference

Every tool except health_check and list_workspaces operates on a workspace. Pass workspaceId as a parameter; stdio clients can also set the WORKSPACE_ID environment variable.

Discovery & navigation

• health_check — verify the server is up
• list_workspaces — find your workspace IDs
• list_branches — browse branches
• get_sources — find source IDs for a workspace

Reading the plan

• get — get item details by ID or exact name
• search — semantic similarity search

Reading a specific branch

• get_branch_details — full branch details (resolved emails, impacted sources, status)
• get_branch_implementation_guide — what changed on a branch
• get_branch_code_snippets — per-event code diffs for a branch + source

Writing (beta)

• workflow — progress the plan forward (e.g. create a branch)
• save_items — create / update / remove events, properties, event variants on a branch

health_check

Scope: read

Verify the MCP server is running and responsive.

Parameters: None

Returns: A simple OK status.

list_workspaces

Scope: read

List the Avo workspaces the authenticated user has access to.

Parameters: None

Returns: One row per workspace: name, workspace ID, and the user’s role.

Call this first to discover workspace IDs before invoking any workspace-scoped tool.

list_branches

Scope: read

Browse branches in a workspace with filtering and pagination. Results are paginated newest-first.

Parameters:

Returns: Compact per-branch summary — name, status, ID, creator email — plus a nextPageToken when more results are available. Call get_branch_details for full resolved data.

By default Merged and Closed branches are excluded. Pass branchStatuses: ["Merged"] (or any other value) to include them.

Common errors: workspace access denied, invalid pageSize, invalid date format.

get_branch_details

Scope: read

Full details for a specific branch.

Parameters:

Returns:

• Resolved emails for the creator, all reviewers, and all collaborators
• Branch status
• Complete list of impacted source IDs
• Branch description

Use this after list_branches to drill into a specific branch.

Common errors: branch not found, ambiguous branch name, workspace access denied.

get_branch_implementation_guide

Scope: read

High-level implementation guide for a branch — everything an implementer needs to understand what changed.

Parameters:

Returns:

• Summary: counts of new, modified, and deleted events
• New events: name, description, property list, and whether the source uses Avo Codegen or manual implementation
• Modified events: what changed (name, description, properties) with before/after values
• Deleted events: name, description, properties
• Implementation steps: instructions tailored to the source type (Codegen: check avo.json, run avo pull, import, implement, validate; Manual: what to add, change, or remove)

When sourceId is provided, the guide filters to changes affecting only that source.

When to use this vs get_branch_code_snippets: Use this tool to understand the scope of changes. Use get_branch_code_snippets when you need the actual code diffs to write implementation code.

get_branch_code_snippets

Scope: read

Per-event code snippets — unified diffs — for all changed events on a branch, for a specific source.

Parameters:

Returns: Per-event implementation snippets, including:

• Event status: New, Added (to source), Updated, Removed (from source), or Deleted
• Label: [Codegen] or [Pseudocode] per event
• Diff: exact unified diff between main and the branch for [Codegen] events; illustrative before/after for [Pseudocode] events
• Contextual guidance per event (e.g., run avo pull for Codegen, implement manually for pseudocode, remove calls for deleted events)

get_sources

Scope: read

List sources in a workspace. Sources represent the different places in your codebase where tracking fires — for example, “iOS App”, “Web App”, or “Backend Service”.

Parameters:

Returns: A table of sources — name, programming language, platform, filename hint, and source ID. Sources with no language or platform configured are flagged.

Call this to find a sourceId before using get_branch_implementation_guide or get_branch_code_snippets.

get

Scope: read

Universal item-details tool. Look up a single tracking plan item by ID or exact name. Defaults to the main branch.

Parameters:

Returns: Full details for the item, shaped per item type.

Common errors: item not found, ambiguous name (returns multiple matches — narrow by ID), workspace access denied.

search

Scope: read

Semantic similarity search across events, properties, metrics, categories, and property bundles. Uses vector similarity, not keyword matching — a query like "user signed up" will match Account Created or Registration Completed by meaning.

Parameters:

Returns: Ranked results with rank, name, type, item ID, relevance percentage, and a truncated description (80 characters).

Search is performed against the main branch only. There is a brief indexing lag for very recently created or updated items.

workflow

Scope: write

Progress the tracking plan forward. Currently supports one action: creating a branch.

Parameters:

Returns: The new branch’s branchId, branchName, and a branchUrl that opens it in the Avo web app.

Common errors: missing write scope (re-authorize with write), workspace access denied, unsupported action value.

save_items

Scope: write

Batch create, update, and remove events, properties, and event variants on a branch. A single call can mix item types and operations, and can cross-reference new items via temporary IDs.

Top-level parameters:

The request is capped at 100 items per call.

Item shape

Every item shares these fields:

Create-event fields:

Create-property fields:

Create-event_variant fields:

Update-event fields: (require eventId)

Update-event_variant fields: (require baseEventId + variantId)

Update-property fields: (require propertyId)

Remove-property: (require propertyId)

{ op: "remove", type: "property", propertyId: "..." } archives the property on the branch and cascades a RemovePropertyRefV3 action for every event that references it, mirroring the Avo UI. The action is destructive but reversible from the Avo app. If you only have the property name, look up the ID first with get or search so that any name-conflict ambiguity is surfaced before the mutation runs.

Temporary IDs (tempId / $tmp:)

To reference a newly-created item from another item in the same call, declare a tempId on the create item and reference it elsewhere as "$tmp:<name>":

• tempId is create-only — setting it on an update or remove returns an error.
• tempId names must be unique within a single save_items call.
• $tmp: references are resolved in these array fields: properties, addProperties, removeProperties, attachProperties, and inside overrides[].propertyId / addComponentOverrides[].propertyId. Source, destination, and bundle IDs cannot be $tmp: refs — they must be real IDs, since save_items does not create those entity types.
• If a $tmp: ref names a tempId that wasn’t declared on any item, the server returns a validation error.

Example: create a new event with a new property in one call

{
  "branchId": "br-abc123",
  "items": [
    {
      "op": "create",
      "type": "property",
      "tempId": "checkout_method",
      "name": "Checkout Method",
      "propertyType": "string",
      "sendAs": "event",
      "description": "How the user completed checkout"
    },
    {
      "op": "create",
      "type": "event",
      "name": "Checkout Completed",
      "description": "Fired when the user finishes checkout",
      "properties": ["$tmp:checkout_method"],
      "sources": ["src-web", "src-ios"]
    }
  ]
}

The server allocates a real ID for checkout_method, attaches the new property to the new Checkout Completed event, and includes the event in the Web and iOS sources — all atomically.

Example: add allowed values to an existing property

{
  "branchId": "br-abc123",
  "items": [
    {
      "op": "update",
      "type": "property",
      "propertyId": "prop-abc123",
      "addAllowedValues": ["Buy Now", "Subscribe"]
    }
  ]
}

Response

Returns a structured result with:

• createdEntities, updatedEntities, removedEntities — each entry has name, entityId, and entityType (event, property, or event_variant).
• errors — per-item validation or audit errors, each with the item index, name, and a message.
• warnings — non-fatal notices, same shape as errors.
• success — overall boolean.

Common errors:

• Missing write scope — the client must re-authorize with write.
• branchId is required / items is required — malformed request.
• tempId is only valid on create items — don’t set tempId on update or remove.
• Duplicate tempId "<name>" — each tempId must be unique across items in the batch.
• Unknown $tmp: reference — a $tmp: ref names a tempId that wasn’t declared.
• <idField> is required for <op> <entity> items — missing eventId / propertyId / baseEventId / variantId.
• too many items (got N, max 100) — batch is over the 100-item cap.
• NotYetImplemented — one of the unsupported operations above.
• Per-item audit-pipeline validation failures (e.g. illegal name, duplicate property, etc.) — returned inside the errors array rather than failing the whole call.