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.

What you can do

• Design tracking for a new feature from a product brief — Claude reads your audit rules, finds reusable items, and proposes a plan before writing.
• Look up how an event is defined, including its properties, sources, descriptions, and constraints.
• Find events, properties, or metrics by meaning — a query like “user signed up” matches Account Created even when the exact name is unknown.
• Review the structured diff of an Avo branch and pull per-source code snippets ready to drop into your codebase.
• Create a branch and add or update events, properties, and event variants in a single batched write.
• Combine Avo with your data MCP (Amplitude, Mixpanel, BigQuery, etc.) to diagnose tracking gaps from real data.

The read scope covers everything except the last two; writes step up to a write scope on first use.

Capability matrix

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

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

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

Most tools are workspace-scoped (health_check and list_workspaces are the exceptions). 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.)

Example: search and save_items

The two tools a catalog reviewer is most likely to call. Real responses include the full item shape — see the Tools reference for the canonical schema.

Look up signup-related events with semantic search:

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

Create a new property and a new event in a single batched save_items call, using tempId to attach the new property to the new event atomically:

// save_items({
//   branchId: "br-7d2f...",
//   items: [
//     { op: "create", type: "property", tempId: "post_id",
//       name: "Post ID", propertyType: "string", sendAs: "event" },
//     { op: "create", type: "event", name: "Post Shared",
//       properties: ["$tmp:post_id"], sources: ["src-web"] }
//   ]
// })
{
  "success": true,
  "createdEntities": [
    { "name": "Post ID", "entityId": "prop-9d44...", "entityType": "property" },
    { "name": "Post Shared", "entityId": "evt-3f01...", "entityType": "event" }
  ],
  "updatedEntities": [],
  "removedEntities": [],
  "errors": [],
  "warnings": []
}

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 and the prompt only 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 and pass branchId to the follow-up call.

save_items returns a NotYetImplemented error. A small set of operations are not supported yet — removing events, 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.