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

Read (scope: read)

• Browse branches and see who created, reviewed, or collaborated on them
• Get implementation guides and code diffs for a specific source on a branch
• Look up details for any tracking plan item — events, properties, metrics, categories, property bundles, sources, destinations, group types, event variants
• Search the plan semantically by meaning
• Discover available sources in your workspace

Write (scope: write)

• Create a new branch from main
• Create, update, and (for some entities) remove events, properties, and event variants on a branch
• Cross-reference newly created items inside a single batch using temporary IDs

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.)

Recommended agent flows

Explore the plan

list_workspaces → search or get to inspect items by meaning or by ID/name.

Find work on a branch

list_branches → get_branch_details → get_branch_implementation_guide → get_branch_code_snippets (with a sourceId from get_sources).

Add events for a new feature

1. workflow with action: "create_branch" and a branchName → returns branchId.
2. save_items on that branchId with a batch of event / property / event_variant items. Use tempId for forward references so a newly created property can be attached to a newly created event in a single call.
3. Tell the user the branch is ready — the MCP does not merge. Open the branch in the Avo web app (or ask a reviewer) to review and merge it to main.

Fix a property on an existing branch

list_branches → get_branch_details to get branchId → save_items with op: "update" targeting an eventId or propertyId.

Searching for an event

Use search to find events by meaning, not just exact name. A query like "user signed up" will match events named Account Created or Registration Completed.

Tools

See the Tools reference for the full list of tools and their parameters.