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.

Example sessions

The blocks below show what each major flow looks like end-to-end — the user prompt, the tool calls Claude makes, the JSON the server returns, and how Claude wraps up. JSON has been trimmed for readability; real responses include the full item shape documented in the Tools reference.

Find events by meaning

You: What events do we have for signup?

Claude → search({
  query: "signup",
  itemType: "event",
  maxResults: 5
})

Server ← {
  "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..."
    }
  ]
}

Claude → get({
  type: "event",
  id: "evt-9f2b...",
  includePropertyDetails: true
})

Server ← {
  "name": "Account Created",
  "id": "evt-9f2b...",
  "description": "Sent when a new account is successfully created.",
  "sources": ["iOS", "Android", "Web"],
  "properties": [
    {
      "name": "Authentication Method",
      "type": "string",
      "allowedValues": ["Email", "Google", "Apple"]
    },
    { "name": "Referral Source", "type": "string" }
  ]
}

Claude: You have two signup events. The closest match is **Account Created**
— sent when a user successfully creates an account — with properties
Authentication Method (Email, Google, Apple) and Referral Source. There's
also **Signup Started**, fired when the signup screen opens. Want a closer
look at either?

Create a property on a branch

You: Add a Checkout Method property to the Checkout Completed event.

Claude: I'll create a branch, add the property, and attach it to the event.
You'll see a one-time re-auth prompt for write access in your browser.

Claude → workflow({
  action: "create_branch",
  branchName: "add-checkout-method"
})

Server ← {
  "branchId": "br-7d2f...",
  "branchName": "add-checkout-method",
  "branchUrl": "https://www.avo.app/schemas/default/branches/br-7d2f..."
}

Claude → get({ type: "event", name: "Checkout Completed" })

Server ← {
  "name": "Checkout Completed",
  "id": "evt-c2a8...",
  "description": "Sent when the user successfully completes a checkout."
}

Claude → save_items({
  branchId: "br-7d2f...",
  items: [
    {
      op: "create",
      type: "property",
      tempId: "checkout_method",
      name: "Checkout Method",
      propertyType: "string",
      sendAs: "event",
      description: "How the user completed checkout (Apple Pay, Google Pay, Card)"
    },
    {
      op: "update",
      type: "event",
      eventId: "evt-c2a8...",
      addProperties: ["$tmp:checkout_method"]
    }
  ]
})

Server ← {
  "success": true,
  "createdEntities": [
    {
      "name": "Checkout Method",
      "entityId": "prop-44e1...",
      "entityType": "property"
    }
  ],
  "updatedEntities": [
    {
      "name": "Checkout Completed",
      "entityId": "evt-c2a8...",
      "entityType": "event"
    }
  ],
  "removedEntities": [],
  "errors": [],
  "warnings": []
}

Claude: Done. **Checkout Method** (string, event property) is created and
attached to **Checkout Completed** on the branch
[`add-checkout-method`](https://www.avo.app/schemas/default/branches/br-7d2f...).
Open the branch in the Avo app to review and merge to main — merging stays
a human step.

Open a new branch

You: Open a new branch called update-signup-flow.

Claude: You'll see a one-time re-auth prompt for write access in your browser.

Claude → workflow({
  action: "create_branch",
  branchName: "update-signup-flow"
})

Server ← {
  "branchId": "br-1a4c...",
  "branchName": "update-signup-flow",
  "branchUrl": "https://www.avo.app/schemas/default/branches/br-1a4c..."
}

Claude: Branch
[`update-signup-flow`](https://www.avo.app/schemas/default/branches/br-1a4c...)
is ready. What changes do you want to make on it?

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.

Tools

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