Avo MCP

Avo MCP gives AI coding assistants direct access to your Avo tracking plan. Claude, ChatGPT, Cursor, Codex, Claude Code, and other MCP-compatible clients can read the plan, explore branches, and write changes on a branch — without copy-pasting specs into the chat. (MCP stands for Model Context Protocol.)

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.

Use cases

Getting started. Every tool except list_workspaces is workspace-scoped. Call list_workspaces first to find your workspaceId, then pass that ID to subsequent tool calls. (Stdio clients can also set the WORKSPACE_ID environment variable so it’s picked up automatically.)

The three use cases below cover the most common flows. Many more are possible through the same tools.

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.

Other example flows

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.

Limits

save_items accepts at most 100 items per call.
search semantic mode caps at 20 results per call (default 10). Filter mode caps at 500 results (default 10).
list_branches returns up to 50 results per page (default 25). Use pageToken to paginate.
Tokens carry the user’s identity; workspace access is verified at every call against your Avo workspace membership, so a token alone is not sufficient if you lose workspace access.

FAQ

Does the Avo MCP merge branches to main?

No. The MCP creates branches and writes items on them, but merging always remains a human step in the Avo web app. Merges to main are deliberate, reviewable changes to your tracking plan, not background automation.

What data does Avo collect through the MCP?

The MCP reads and writes tracking-plan content — events, properties, event variants, metrics, categories, and property bundles — already stored in your Avo workspace. It does not collect your codebase, your prompts, or any data your MCP client sends to its model. Standard operational telemetry — request IDs, error counts — is retained for reliability. See the Avo Privacy Policy for full details.

Do I need to be a workspace admin to use the Avo MCP?

For most tools, no — any workspace member can read the plan and write to branches via the MCP. Two exceptions: enabling semantic search requires an admin to turn on Avo Intelligence Smart Search in Workspace Settings, and adding the connector inside Claude Desktop requires admin permissions in your Claude organization.

Can multiple team members use the Avo MCP simultaneously?

Yes. Each user authenticates with their own Avo identity via OAuth, so concurrent sessions and writes are independent and audited per user in the Avo web app.

Which MCP clients are supported?

Any client that supports HTTP transport and the browser-based OAuth 2.0 authorization flow. Tested clients include Claude Code, Claude Desktop, Cursor, and Codex. Clients that cannot open a browser — CI runners, headless containers — cannot complete the OAuth flow.

Setup

🔒

First-call behavior. Your client must support HTTP transport and the browser-based OAuth 2.0 authorization flow. The first tool invocation opens a browser, you sign in with Avo, the client caches the token, and subsequent calls use it automatically. CI runners and headless containers cannot complete this flow.

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"
    }
  }
}

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.

Troubleshooting

Authentication and workspace access issues live here. For tool-specific issues — search returning nothing, ambiguous branch names, NotYetImplemented errors — see Troubleshooting in the Tools reference.

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.

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.

Privacy summary

What is collected. The MCP reads and writes tracking-plan content already stored in your Avo workspace. It does not collect your codebase, prompts, or data your MCP client sends to its model.
How it’s used. Tool calls update your tracking plan or return its current state. Operational telemetry (request IDs, error counts) is collected for reliability and abuse prevention.
Storage and retention. Tracking-plan content lives in your Avo workspace under the existing retention policy. OAuth tokens and operational logs follow the schedule in the Avo Privacy Policy.
Third-party sharing. Avo does not forward tracking-plan content to AI providers. The MCP returns data to your client; your client decides what to send onward to its model.

Full data-handling details are in the Avo Privacy Policy.

Import Tracking Plan Tools reference