Brandofy MCP tools reference

Connect any Model Context Protocol client (ChatGPT, Claude, Cursor, Codex, custom agents) to Brandofy. All tools run as the signed-in Brandofy user under row-level security.

Connect

Server URL: https://brandofy.ai/mcp

Transport: Streamable HTTP

Auth:

OAuth 2.1

Your client will open a Brandofy sign-in window, then ask you to approve access on the consent page at/.lovable/oauth/consent. Dynamic client registration is enabled so most MCP clients connect with no manual setup.

Tools

list_brands

Read-only

List your brands

List the Brandofy brands owned by the signed-in user (id, name, domain).

Inputs

No inputs.

Example call

{}

Example response

{
  "brands": [
    {
      "id": "b-uuid",
      "name": "Acme",
      "website": "https://acme.com"
    }
  ]
}

latest_audit

Read-only

Latest audit for a brand

Return the most recent completed AEO audit for a given brand (AEO score, share of voice, mentions, top competitor).

Inputs

Field	Type	Required	Notes
brandId	uuid	yes

Example call

{
  "brandId": "b-uuid"
}

Example response

{
  "audit": {
    "id": "a-uuid",
    "aeo_score": 62,
    "share_of_voice": 18,
    "total_mentions": 7
  }
}

list_prompt_rankings

Read-only

AEO prompt rankings

List AEO prompt-level rankings for a brand: for each prompt (across the requested AI platforms), whether the brand was mentioned, its position, sentiment, and which competitors appeared. Defaults to the most recent completed audit.

Inputs

Field	Type	Required	Notes
brandId	uuid	yes
auditId	uuid	no	Optional. Defaults to the most recent completed audit for this brand.
platform	chatgpt \| gemini \| perplexity \| google_ai_overview \| google_ai_mode	no	Filter to one AI platform.
mentionedOnly	boolean	no	If true, return only prompts where the brand was mentioned.
limit	integer	no

Example call

{
  "brandId": "b-uuid",
  "platform": "chatgpt",
  "mentionedOnly": true,
  "limit": 20
}

Example response

{
  "auditId": "a-uuid",
  "brandId": "b-uuid",
  "summary": {
    "total": 20,
    "mentioned": 12
  },
  "rankings": [
    {
      "text": "best noise cancelling headphones",
      "platform": "chatgpt",
      "brand_mentioned": true,
      "position": 2,
      "sentiment": "positive"
    }
  ]
}

start_audit

Write

Start a new AEO audit

Kick off a fresh AEO audit for a brand across ChatGPT, Gemini, Perplexity, and Google AI surfaces. Returns immediately with an auditId (status='pending'). Poll get_audit_status until status='done' (typically 1-3 minutes), then read scores with latest_audit and rankings with list_prompt_rankings. Subject to a 10-audit-per-calendar-month cap per account.

Inputs

Field	Type	Required	Notes
brandId	uuid	yes
prompts	array	no	Optional custom prompt set. Omit to let Brandofy auto-generate prompts for this brand.

Example call

{
  "brandId": "b-uuid"
}

Example response

{
  "auditId": "a-uuid",
  "brandId": "b-uuid",
  "status": "pending",
  "pollWith": "get_audit_status",
  "estimatedSeconds": 90
}

get_audit_status

Read-only

Poll audit status

Return the current status of an audit started with start_audit (pending, running, done, or failed) plus a 0-100 progress hint. When status='done', read scores via latest_audit.

Inputs

Field	Type	Required	Notes
auditId	uuid	yes

Example call

{
  "auditId": "a-uuid"
}

Example response

{
  "auditId": "a-uuid",
  "status": "done",
  "progressPct": 100,
  "scores": {
    "aeoScore": 62,
    "shareOfVoicePct": 18,
    "totalMentions": 7
  }
}

Errors

Every tool returns errors as structured JSON instructuredContent.errorwith a stable code plus a short human message. No stack traces, DB errors, or IDs from other users are ever leaked.

Code	Meaning
unauthenticated	OAuth session missing or expired. Reconnect the MCP client.
invalid_input	The input failed validation. Check the field named in the message.
brand_not_found	The brandId isn't accessible to the signed-in user.
audit_not_found	No audit with that id, or none completed yet for the brand.
plan_limit	Monthly audit cap reached, or plan doesn't allow this action.
worker_unavailable	Audit background worker could not accept the request. Retry.
server_error	Unexpected server error. Retry; contact support if it persists.

The machine-readable manifest lives at/mcp(Streamable HTTP endpoint) with tool discovery at/.mcp/list-toolsand OAuth metadata at/.well-known/oauth-protected-resource.