Avo MCP

The Avo MCP (Model Context Protocol) server exposes your Avo tracking plan to AI coding assistants. Tools like Claude, ChatGPT, Cursor, Codex, Claude Code, and other MCP-compatible clients can read your tracking plan, explore branches, and write changes on a branch — without you copy-pasting specs into the chat.

Transport: Streamable HTTP at https://mcp.avo.app/mcp
Authentication: OAuth 2.0 + PKCE, scoped to your Avo identity
Writes: always happen on a branch (never directly on main). Merging to main stays a human step in the Avo app.

🚧

The Avo MCP is in general beta. Both the read and write tools are enabled for every workspace — no need to request access. We’re still refining them, so let us know at support@avo.app if you hit anything unexpected.

🔒

Writes require the write scope and always happen on a branch. The MCP server will never merge a branch into main — that remains a human step in the Avo web app.

What you can do

Search the tracking plan

Ask Claude what’s already instrumented — “what events do we have for signup?” or “is there anything that captures checkout completion?”. The MCP runs a semantic search across events, properties, and metrics, returns ranked matches, then pulls the full definition of the ones that look right.

Design tracking for a new feature

Share a PRD, Figma designs, or just a feature description. Claude reads your workspace’s audit rules, hunts for items you can reuse, and proposes a plan — events, properties, metrics — for you to review before any write happens. On approval, it creates a branch and writes everything in a single batched call, using temporary IDs to attach a brand-new property to a brand-new event in the same write. The MCP never merges to main — you finalize the branch in the Avo web app.

Review and implement an Avo branch

Point Claude at a branch and it returns a structured diff: new, modified, and removed events with their properties and descriptions. Pick a source and ask for per-event code snippets to drop into your codebase. The diff is exact for Avo Codegen sources and illustrative pseudocode for manually-instrumented sources.

You can also:

Look up any event, property, or metric by exact name or ID
Combine Avo with your data MCP (Amplitude, Mixpanel, BigQuery, etc.) to diagnose tracking gaps from real data
Make small edits to a branch — fill in allowed values, rename properties, add categories
Browse and filter open branches by status, creator, or reviewer

Capability matrix

The MCP exposes five tools mapped to agent intents:

Intent	Tool	Scope
Entry point — find your workspace IDs	`list_workspaces`	`read`
Discover — find items by meaning or by structural filter	`search`	`read`
Understand — full details for an event, property, branch, source, etc.	`get`	`read`
Change — create, update, remove, or archive items on a branch	`save_items`	`write`
Progress — create a branch or update its description	`workflow`	`write`

Branch read flows are covered by get and search. One transitional tool — list_branches — remains available while its replacement in search(type:"branch") ships. See the Tools reference for full parameters, return shapes, and examples per tool.

Setup

Claude Code (CLI)

claude mcp add avo --transport http https://mcp.avo.app/mcp

Claude Desktop app

Open Claude Desktop → Customize → Connectors
Click Add custom connector
Name: Avo, Remote MCP server URL: https://mcp.avo.app/mcp

🔒

Adding connectors in Claude Desktop requires admin permissions in your organization.

Cursor

Add the following to your mcp.json (or ~/.cursor/mcp.json for global config):

{
  "mcpServers": {
    "Avo": {
      "url": "https://mcp.avo.app/mcp"
    }
  }
}

Other MCP clients

{
  "mcpServers": {
    "Avo": {
      "url": "https://mcp.avo.app/mcp"
    }
  }
}

Your client must support HTTP transport and the browser-based OAuth authorization flow. The first tool invocation opens a browser, you sign in with your Avo credentials, the client receives a token, and the token is cached for subsequent calls. Clients that cannot complete the OAuth flow will not work with the Avo MCP.

Authentication

The MCP server uses OAuth 2.0 with PKCE.

Protected resource metadata: served at https://mcp.avo.app/.well-known/oauth-protected-resource per RFC 9728. The authorization server is https://api.avo.app — clients discover its endpoints via https://api.avo.app/.well-known/oauth-authorization-server.
Dynamic client registration: POST https://api.avo.app/oauth/register per RFC 7591. Most MCP clients register themselves automatically on first connect.
Scopes: read and write. Clients request read by default. When you invoke a write tool, your client will step up and request the write scope (a second browser prompt). Tokens carry the user identity; workspace access is verified at call time against your Avo workspace membership.
Token signing: RS256 keys backed by Google Cloud KMS (HSM) in production.

If a tool that requires write is called with a token that only has read, the server returns an error prompting the client to re-authorize with write.

Getting started

Every tool except list_workspaces is workspace-scoped. The typical first-use sequence:

1. Discover your workspaces

Call list_workspaces to find your workspaceId.

2. Use any tool

Pass workspaceId to every workspace-scoped tool. (Stdio clients can also set the WORKSPACE_ID environment variable so it’s picked up automatically.)

Tools

See the Tools reference for the full list of tools, parameter shapes, and response schemas.

Troubleshooting

A second browser prompt appears the first time you write. Write tools require the write scope, which is a step-up consent on top of read. Your client opens the OAuth flow again; the prompt appears once per session.

search returns nothing for a clearly relevant query. Semantic search requires Avo Intelligence Smart Search to be enabled. Workspace admins can turn it on in Workspace Settings. Without it, fall back to get with an exact name.

The wrong branch is returned by name. branchName resolves to a best match and prioritizes open branches, so an ambiguous name can pick the wrong one. Resolve the name to a branchId with list_branches first and pass branchId to the follow-up call.

save_items returns a NotYetImplemented error. A small set of operations are not supported yet — removing event variants and changing a property’s sendAs. See the save_items reference for the full list.

Authentication never completes. The first tool call opens a browser to sign in. MCP clients that cannot open a browser (CI runners, headless containers) cannot complete the OAuth flow.

workspace access denied. The MCP enforces the same membership rules as the Avo web app. Confirm you’re a member of the workspace at avo.app — and that you’re signing in with the same identity — before retrying.

Support and privacy

For bug reports, feature requests, or help connecting an MCP client, email support@avo.app.

How Avo collects, uses, and retains data is covered in the Avo Privacy Policy.

Import Tracking Plan Tools reference