Avo MCP tools reference

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

The MCP maps five canonical tools to agent intents:

Entry point

• list_workspaces — find your workspace IDs

Discover (read)

• search — find items by meaning or by structural filter

Understand (read)

• get — full details for any tracking plan item (or a branch overview / code snippets)

Change (write)

• save_items — create, update, remove, or archive events, properties, event variants, property bundles, and metrics on a branch

Progress (write)

• workflow — create a branch or update its description

Transitional (read — kept while its replacement ships)

• list_branches — browse branches (planned: folded into search(type:"branch"))

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 with type: "branch" and include: ["overview"] 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

Scope: read

Universal item-details tool. Look up a single tracking plan item by ID or exact name, read a branch’s overview and code snippets, or enumerate workspace-level entities. Defaults to the main branch.

Parameters:

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

• type: "event" \| "property" \| "metric" \| "category" \| "propertyBundle" \| "eventVariant" — the item’s full definition.
• type: "source" \| "destination" \| "groupType" — a single entity when id/name is provided, or a workspace-level list when both are omitted.
• type: "branch" — branch facets requested via include. overview returns resolved emails for the creator, reviewers, and collaborators, branch status, impacted source IDs, and description. changes returns the structured diff (new, modified, and deleted events with their properties and descriptions). code_snippets returns per-event code diffs for the source named in sourceId — exact unified diffs for Avo Codegen sources and illustrative pseudocode for manually-instrumented sources.
• type: "workspaceConfig" — the workspace’s event/property naming conventions and casing rules, plus custom field definitions and the list of recognized PII types. Use this before proposing new events or properties so names match the workspace’s audit rules.

Common errors: item not found, ambiguous name (returns multiple matches — narrow by ID), sourceId missing for include: ["code_snippets"], workspace access denied.

search

Scope: read

Find tracking plan items in one of two modes — the mode is selected automatically by which parameters you pass. Combining query with structural filters returns 400. For ID-based lookups use get.

• Semantic search — pass query to find items by meaning across events, properties, metrics, categories, property bundles, and event variants. Uses vector similarity, not keyword matching — "user signed up" matches Account Created or Registration Completed.
• Structured listing — omit query and pass filters to enumerate exact matches with keyset pagination.

Parameters shared across modes:

Semantic mode (pass query):

Semantic search is performed against the main branch only. The semantic index may lag slightly for very recently created or updated items.

Filter mode (omit query, pass any of the filter fields):

Multiple values inside one array are OR’d; values across different filter keys are AND’d.

Returns: Ranked results with rank, name, type, item ID, relevance percentage, and a truncated description (80 characters). Filter-mode responses include a nextPageToken when more results are available.

{
  "results": [
    {
      "rank": 1,
      "name": "Account Created",
      "itemType": "event",
      "itemId": "evt-9f2b…",
      "relevance": 0.91,
      "description": "Sent when a new account is successfully created."
    },
    {
      "rank": 2,
      "name": "Signup Started",
      "itemType": "event",
      "itemId": "evt-3c11…",
      "relevance": 0.87,
      "description": "Sent when the user opens the signup screen."
    }
  ]
}

workflow

Scope: write

Branch-lifecycle write operations. Currently supports two actions:

• create_branch — open a new branch.
• update_branch_description — set the description on an existing open branch.

Parameters:

Returns: For create_branch: the new branch’s branchId, branchName, and a branchUrl that opens it in the Avo web app. For update_branch_description: confirmation with the resolved branchId and the updated description.

Common errors: missing write scope (re-authorize with write), workspace access denied, unsupported action value, both branchId and branchName provided (update_branch_description requires exactly one).

save_items

Scope: write

Batch create, update, remove, and archive events, properties, event variants, property bundles, and metrics 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:

Supported ops by type:

Create-event fields:

Create-property fields:

Create-event_variant fields:

Create-property_bundle fields:

Create-metric fields:

Update-event fields: (require eventId)

Update-event_variant fields: (require baseEventId + variantId)

Update-property fields: (require propertyId)

Update-property_bundle fields: (require propertyBundleId)

Update-metric fields: (require metricId)

Remove-property: (require propertyId)

{ op: "remove", type: "property", propertyId: "..." } archives the property on the branch and cascades removal references on every event that uses 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.

Remove-property_bundle: (require propertyBundleId)

{ op: "remove", type: "property_bundle", propertyBundleId: "..." } archives the bundle on the branch.

Archive-metric: (require metricId)

{ op: "archive", type: "metric", metricId: "..." } archives the metric on the branch.

Per-event property settings (eventConfigs)

eventConfigs is a top-level array on an update-property item (and, restricted to events: { kind: "allEvents" }, on a create-property item). Each entry adjusts how the property behaves on a specific event or across all events:

• setPresence — change presence to alwaysSent, sometimesSent, or neverSent. Can be scoped per source.
• setPinnedValue — pin a value for the property. With events: { kind: "onEvent" } pins per-event; with events: { kind: "allEvents" } pins property-wide.
• restrictAllowedValues — change the property’s allowed value list for an event. Carries a valuesChange delta: addValues (non-empty), removeValues, or clear (no payload).

eventConfigs entries reference pre-existing events — a same-batch create-event item isn’t visible to eventConfigs yet, so create the event in an earlier call (or the same batch, ordered before the property update that references it).

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, remove, or archive 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, propertyBundles, addPropertyBundles, removePropertyBundles, attachToEvents, addSources, removeSources, bundleOverrides; inside overrides[].propertyId / addComponentOverrides[].propertyId; and within nested metric fields (items[].metricId / eventId / baseEventId, cohortConditions[].eventId / propertyId). Source and destination IDs must be real IDs — 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, archivedEntities — each entry has name, entityId, and entityType (event, property, event_variant, property_bundle, or metric).
• 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.

{
  "success": true,
  "createdEntities": [
    { "name": "Checkout Method", "entityId": "prop-9d44…", "entityType": "property" }
  ],
  "updatedEntities": [
    { "name": "Checkout Completed", "entityId": "evt-3f01…", "entityType": "event" }
  ],
  "removedEntities": [],
  "errors": [],
  "warnings": []
}

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.