MCP Tools Reference

Complete reference for all tools available through the AEO Goal MCP server.

Last updated August 31, 2026

The AEO Goal MCP server exposes tools that AI assistants (Claude, Cursor, etc.) can call to query and update your AEO data in natural language. This is the complete tool catalog.

Authentication

MCP tools use a separate OAuth flow from personal API keys - you authorize in the browser, there is no static key to paste. The server URL is https://mcp.aeogoal.com/mcp (also shown in your in-app Connectors settings). Follow the MCP Connectors setup guide.

Scopes

You pick which permissions to grant on the consent screen when connecting. Read tools work with platform:read; each write tool needs a broader scope:

Scope Grants Tools
platform:read Read brands, share-of-mind, citations, rankings, competitors, draft status whoami (no scope), all get_* / list_* tools, suggest_tracked_prompts, get_content_job
platform:write Add tracked prompts, keywords, and competitors add_tracked_prompts, add_tracked_keywords, set_brand_competitors
content:write Generate blog / AEO content drafts (saved unpublished - never auto-published) generate_content
reports:read / reports:write Generate & share white-label reports (Enterprise plan) generate_report, create_share_link, manage_report_subscriptions, get_organization_branding

If a tool returns insufficient_scope, reconnect and grant the scope it names.

Protocol details

  • Transport: Streamable HTTP (POST /mcp)
  • Protocol version: 2025-06-18
  • Rate limit: 120 requests / 60 seconds per connection
  • Max request body: 128 KB

Tool catalog

whoami

Returns your account identity. No scope required.

Input: (none)
Output: email, name, user_id, brand_scope (if restricted)

Example prompt: “Who am I connected as?”

list_tracked_brands

Lists all brands accessible to this connection.

Input: (none)
Output: List of brand IDs, names, and domains. Active brand marked with *.

Example prompt: “What brands do I have set up?”

list_products

Lists products configured for a brand.

Input:
  brand_name (string, optional) - defaults to active brand
Output: Product names and descriptions

Example prompt: “What products are configured for Acme Corp?”

get_share_of_mind

Returns your brand’s Share of Model score for a given time window.

Input:
  brand_name (string, optional) - defaults to active brand
  days (integer, optional) - lookback window, 1-365, default 30
  platform (string, optional) - filter to a specific AI engine
Output: SoM %, mention count, total queries, Δ vs prior window, avg position

Example prompts:

  • “What’s my Share of Model for the last 30 days?”
  • “How is my SoM on Perplexity specifically?”
  • “Compare my SoM this month vs last month”

get_citation_rank

Returns citation ranking details - which AI engines cite you and your average position.

Input:
  brand_name (string, optional) - defaults to active brand
  days (integer, optional) - lookback window, default 30
Output: Citations per engine, average position, top cited pages, trend

Example prompts:

  • “Which AI engine cites me most?”
  • “What’s my average citation position on ChatGPT?”

get_keyword_rankings

Returns rank tracking data for your tracked keywords.

Input:
  brand_name (string, optional) - defaults to active brand
  limit (integer, optional) - max keywords to return, default 20
Output: Keyword, current position, position change, ranking URL

Example prompts:

  • “What are my top ranking keywords?”
  • “Which keywords improved the most this week?”

Returns a summary of your backlink profile.

Input:
  brand_name (string, optional) - defaults to active brand
Output: Total backlinks, referring domains, new/lost links, domain rating

Example prompts:

  • “How many backlinks do I have?”
  • “Did I gain or lose links this month?”

compare_vs_competitor

Compares your AI visibility against a specific competitor.

Input:
  competitor_domain (string, required) - e.g. "competitor.com"
  brand_name (string, optional) - defaults to active brand
  days (integer, optional) - lookback window, default 30
Output: Head-to-head SoM, prompts you win, prompts they win, prompts neither wins

Example prompts:

  • “How do I compare against competitor.com?”
  • “Which prompts is HubSpot winning that I’m not?”

list_tracked_prompts

Lists the AI prompts tracked for a brand and their current win/loss status.

Input:
  brand_name (string, optional) - defaults to active brand
  limit (integer, optional) - max prompts to return, default 20
Output: Prompt text, category, win status, last run date, competing brands

Example prompts:

  • “What prompts am I tracking?”
  • “Which prompts am I losing?”
  • “Show me my decision-stage prompts”

Write tools

These change your account and require the scope noted. They are additive and review-first - nothing is deleted, and generated content is saved as an unpublished draft you review before publishing.

suggest_tracked_prompts

AI-suggests prompts to track, grounded in your brand - returns suggestions only, tracks nothing. Scope: platform:read.

Input:
  brand_name (string, optional) - defaults to active brand
  seed (string, optional) - a topic to focus suggestions on
Output: A list of suggested prompt texts (pass the ones you want to add_tracked_prompts)

Example prompt: “Suggest 10 prompts I should track for Acme, then add the good ones.”

add_tracked_prompts

Bulk-adds prompts to tracking. Idempotent - an already-tracked prompt is re-activated, not duplicated. Scope: platform:write.

Input:
  prompts (array, required) - strings, or objects {text, funnel_stage?, persona?, platforms?}
  brand_name (string, optional) - defaults to active brand
  source (string, optional) - provenance tag stored on each new prompt
Output: Per-prompt result (created / re-activated), stopping with a message if the plan cap is hit

Example prompt: “Track these 5 prompts for Acme.”

add_tracked_keywords

Bulk-adds SERP keywords to rank tracking. Idempotent on the SERP identity. Requires rank tracking enabled. Scope: platform:write.

Input:
  keywords (array, required) - strings, or objects {keyword, device?, location?}
  brand_name (string, optional) - defaults to active brand
  device (string, optional) - "desktop" (default) or "mobile"
  location (string, optional) - 2-letter code or name, default "us"
Output: Per-keyword result (added / already tracked)

Example prompt: “Start tracking ‘ai seo tool’ and ‘aeo platform’ for Acme.”

set_brand_competitors

Replaces a brand’s tracked competitor list (also drives competitor detection in citations). Scope: platform:write.

Input:
  competitors (array, required) - names, or objects {name, website}
  brand_name (string, optional) - defaults to active brand
Output: The persisted competitor list (clamped to your plan's competitor cap)

Example prompt: “Set Acme’s competitors to Otterly.ai and AthenaHQ.”

generate_content

Generates AEO/blog drafts from your data and queues them asynchronously. Drafts are saved unpublished - review at /app/blogs. Scope: content:write (requires an active paid plan).

Input (provide at least one of titles / from_prompt_ids / from_keyword_gaps):
  titles (array, optional) - explicit article titles to draft
  from_prompt_ids (array, optional) - tracked-prompt ids to turn into drafts
  from_keyword_gaps (boolean, optional) - auto-draft for prompts where competitors are cited but you're not
  reference_urls (array, optional) - up to 5 HTTP(S) URLs used as grounding evidence
  aeo_instructions (string, optional) - extra guidance applied to every draft
  brand_name (string, optional) - defaults to active brand
Output: { status: "queued", brand, count, blog_ids } - poll with get_content_job

Example prompt: “Draft articles for my top 3 citation gaps for Acme.”

get_content_job

Polls the status of drafts created by generate_content. Only your own drafts are visible. Scope: platform:read.

Input:
  blog_ids (array, required) - the ids returned by generate_content
Output: Per-draft status (queued | generating | completed | failed), quality score, and a review URL

Example prompt: “Are my drafts ready yet?”

Report tools (Enterprise / white-label plan)

generate_report

Renders a report as a PDF (inline for small reports, otherwise a signed download URL). Scope: reports:read.

Input:
  report_type (string, required) - citation_tracking | volatility_alerts | ranking_summary | competitor_intel
  brand_id (integer, optional) · date_range (string, optional, e.g. "30d") · format ("pdf")
Output: PDF (base64 or a 1-hour signed download URL)

Mints a public, tokenized link to a report for clients (no login required). Scope: reports:write.

manage_report_subscriptions

List / create / update / delete scheduled report subscriptions via a single action argument. Scope: reports:write.

get_organization_branding

Returns your organization’s white-label branding (logo, colors, sender). Scope: platform:read + white-label plan.

Handling errors

Error Cause
insufficient_scope Your OAuth grant lacks the scope the tool needs (e.g. platform:write / content:write). Reconnect and grant it.
brand not accessible The brand_name doesn’t exist or is outside your connection’s brand scope
no tracked brands available No brands set up yet - add one in the app
plan-limit / traditional_seo messages You hit a plan cap (tracked prompts, keywords, competitors, content docs) or a feature isn’t enabled - the message says which; upgrade or enable it

Frequently asked questions

How do MCP tools authenticate?

MCP tools use a separate OAuth flow from personal API keys, so you authorize in the browser and there is no static key to paste. The server URL is https://mcp.aeogoal.com/mcp.

What is the difference between read and write scopes?

Read tools work with platform:read, while each write tool needs a broader scope such as platform:write for adding prompts, keywords, and competitors, or content:write for generating drafts. Report tools require reports:read or reports:write on the Enterprise plan.

Will generated content be published automatically?

No. Write tools are additive and review-first, so generated content is saved as an unpublished draft you review at /app/blogs before publishing, and nothing is deleted.

What is the MCP rate limit?

The endpoint allows 120 requests per 60 seconds per connection, with a maximum request body of 128 KB. Transport is Streamable HTTP on protocol version 2025-06-18.