GEOly

English | 简体中文

GEOly MCP Server

The official remote MCP server for GEOly — AI brand visibility (GEO) for your agent. GEOly tracks how brands are mentioned and cited across AI engines (ChatGPT, Perplexity, Google AI Mode, Google AI Overview, Gemini, Copilot), and this server puts that data — visibility KPIs, competitor share, citation sources, market intelligence, and site audits — directly into Claude, Cursor, Codex, VS Code, or any MCP client.

Hosted, streamable HTTP, OAuth in the browser. One URL, nothing to run locally:

https://app.geoly.ai/api/mcp/v1

/api/mcp/v1 is the versioned address of GEOly MCP v1. The unversioned https://app.geoly.ai/api/mcp serves exactly the same thing and stays available — existing configs need no change.

What your agent can do

• Pull the same KPIs you see in the app — AIGVR score, mention rate, citation rate per AI platform (get_brand_overview), daily trends, and SQL-free controlled aggregation over daily datasets (query_analytics).
• Find blind spots. Which buyer queries never mention your brand (get_prompt_list with view="mention_rates")? Which domains does AI cite when it names a competitor but not you (get_citation_overview with section="table", gap_only=true)?
• Compare brands head-to-head — 2–4 brands side by side on visibility, footprint, citations, and category ranking across AI engines (get_public_brand with brand_ids).
• Map category whitespace — every topic in a category classified into strengths (covered / leading / close / defend) and opportunities (prioritize / gap / watch) for your brand (get_category_whitespace).
• Track momentum. Who is gaining or losing Share of Mention in AI answers, period over period (get_category_brand_momentum)?
• See AI-search demand — what people actually ask AI in your product space, which brands win those answers, and which demand territories each brand owns (get_public_search_queries).
• Watch the AI shelf. Which products AI recommends most across every category, who is climbing week over week (list_public_shopping_products with view="boards"), and any single product's full AI profile (get_public_shopping_product_detail).
• Score competition difficulty — a 0–100 "keyword difficulty for the AI era" per topic (get_public_topic with view="difficulty").
• Profile AI perception. How do AI models describe a brand? Canonical aspects, polarity, and verbatim evidence (get_public_brand with view="perception").
• Audit AI readiness — GEO site audits covering accessibility, structured data, content structure, and technical checks (get_audit_detail).

Try asking

Once connected, ask your agent things like:

• "How visible was my brand in AI answers over the last 30 days, and on which platform am I weakest?"
• "Which buyer questions never mention us? Rank them by how often competitors show up instead."
• "Compare Anker vs Soundcore visibility in the portable-audio category."
• "Where's the whitespace in my category — which topics should we prioritize?"
• "Which domains do AI engines cite most in my industry, and are we on any of them?"
• "Which products are climbing the AI shopping shelf this week — and in which topics does reddit.com steer AI toward my competitor?"
• "Run down my latest GEO site audit and list the critical issues."

Quick start

Prerequisite: a GEOly account with a workspace and a monitored brand (sign up and finish brand onboarding first — a brand-new workspace has no data to query yet).

Then: add the URL, make one tool call, sign in when the browser opens. That's the whole setup.

Claude Code

claude mcp add --transport http geoly https://app.geoly.ai/api/mcp/v1

Cursor

Or add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "geoly": {
      "url": "https://app.geoly.ai/api/mcp/v1"
    }
  }
}

Claude Desktop

Settings → Connectors → Add custom connector, then paste https://app.geoly.ai/api/mcp/v1 as the URL. Claude walks you through the OAuth consent in the browser.

ChatGPT

In ChatGPT settings, enable developer mode for connectors, then add a custom connector with the URL https://app.geoly.ai/api/mcp/v1 and complete the OAuth sign-in. Yes — you can ask ChatGPT about your brand's visibility inside ChatGPT.

VS Code (GitHub Copilot)

Or from the command line:

code --add-mcp '{"name":"geoly","type":"http","url":"https://app.geoly.ai/api/mcp/v1"}'

Codex CLI

Install through the GEOly plugin marketplace — the plugin registers the remote server and runs the OAuth flow on install, no manual config needed:

codex plugin marketplace add geoly-ai/codex-plugins
codex plugin add geoly-mcp@geoly

Windsurf

Settings → MCP Configuration:

{
  "mcpServers": {
    "geoly": {
      "serverUrl": "https://app.geoly.ai/api/mcp/v1"
    }
  }
}

Gemini CLI

gemini mcp add --transport http geoly https://app.geoly.ai/api/mcp/v1

Or in ~/.gemini/settings.json:

{
  "mcpServers": {
    "geoly": {
      "httpUrl": "https://app.geoly.ai/api/mcp/v1"
    }
  }
}

Cline

Cline supports remote servers natively (note the camel-cased streamableHttp):

{
  "mcpServers": {
    "geoly": {
      "type": "streamableHttp",
      "url": "https://app.geoly.ai/api/mcp/v1"
    }
  }
}

If the OAuth browser flow doesn't trigger in your Cline version, use the mcp-remote bridge below instead.

Any other MCP client

Clients without native remote/OAuth support can bridge through mcp-remote:

{
  "mcpServers": {
    "geoly": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.geoly.ai/api/mcp/v1"]
    }
  }
}

GEOly CLI (terminals & CI)

The same tools, packaged as a command line built for agents — see GEOly-Cli:

# macOS / Linux
curl -fsSL https://geoly.ai/install.sh | sh
# Windows
powershell -ExecutionPolicy Bypass -c "irm https://geoly.ai/install.ps1 | iex"

# No login step — the first call opens the browser to authorize
geoly call get_brand_overview --time_range 30d

Authentication

Track	How	Access
OAuth (default)	Configure the URL with no credentials. The first call returns a standards-compliant challenge (RFC 9728 protected-resource metadata) that sends your client to a browser consent screen: sign in, choose which workspaces to share, and review the permission grid.	Per-resource read/write grants — read is preselected, write stays off unless you tick it
Static token (CI / headless)	Generate a geom_... token in your GEOly workspace settings and send it as Authorization: Bearer geom_....	Always read-only

Agencies and multi-workspace users: a single connection can span every workspace you belong to, or pin one with https://app.geoly.ai/api/mcp/v1?org_id=<id> (get IDs from the list_organizations tool).

Security & data access

• The server only reads data from workspaces you explicitly share at the OAuth consent screen — nothing beyond that scope.
• Write access is opt-in per resource on the consent screen and covers exactly 7 tools (create prompt / topic / competitor, archive or restore a prompt, edit prompt tags, move prompts into a topic, trigger monitoring). Multi-workspace connections and static tokens are always read-only, no exceptions.
• Revoke a connection any time from your GEOly workspace settings; the client's cached credentials stop working immediately.
• The endpoint is stateless streamable HTTP over TLS. Nothing is installed or executed on your machine.

Tools

Up to 53 tools. The surface adapts to your access — single-brand connections skip the routing selectors, read-only connections skip the write tools, and the market-intelligence tools need the Grow plan (a read-only multi-workspace connection on Grow or above sees 47). Related reads share one tool: pick the view with its view / mode / section / source / window_caliber parameter. A parameter that belongs to a different view is rejected before the call runs.

Brand monitoring — overview & KPIs (3)

Tool	What it returns
get_brand_overview	Headline KPIs: AIGVR score, mention/citation rates, per-platform stats — matches the in-app numbers
query_analytics	Controlled aggregation (no SQL) over daily datasets — dimensions, metrics, filters, prompt-text subsets. Also the daily trend: dataset="brand_citations_daily" gives AIGVR / mention rate / citation rate per day per platform
resolve_my_brand_public	Bridge from your monitored brand to its public market-intelligence profile

Brand monitoring — prompts & answers (8)

Tool	What it returns
get_topic_list	The brand's monitored topics with active / archived prompt counts — where topic ids come from
get_prompt_list	view="table" (default): search/list monitored prompts with visibility stats. view="mention_rates": per-prompt mention rate, worst first — blind-spot discovery
get_prompt_detail	One prompt in full: per-platform performance, AIGVR, Share of Model, competitor mentions
list_prompt_records	Full execution history of one prompt over a time range, paginated — per-day trend work. latest_per_platform=true: just the latest record per platform
list_brand_answers	view="table" (default): every AI answer for the brand across all prompts, newest first, filterable by platform / topic / tag / country / brand. view="mention_samples": recent answers mentioning the brand — raw text + sentiment + context
get_prompt_record_detail	One monitored AI answer in full: text, citations, sentiment
get_prompt_citations	Citations for a prompt — raw or deduplicated URL list with share %
get_brand_search_queries	Query fanout: the real web searches ChatGPT / Perplexity ran while answering your prompts, by mode (overview, groups, query_detail, prompt_queries)

Brand monitoring — citations, domains & pages (3)

Tool	What it returns
get_citation_overview	Citation domain distribution + ownership breakdown across the brand. section="board" (default): totals, your share and rank, movers, trend, type share. section="table": one page of cited root domains with share and change vs the previous window; gap_only=true keeps domains where a competitor is mentioned and you are not
get_domain_detail	One domain's citation profile: trend, pages, prompts, platforms, regions
get_url_detail	One page URL. window_caliber="rolling" (default): its references across citations and ChatGPT search sources over a rolling or custom window. window_caliber="page": its citation detail on the in-app citations window — trend, prompt distribution, text snippets

Brand monitoring — competitors, topics & sentiment (7)

Tool	What it returns
get_competitor_list	The brand library: tracked, suggested and removed brands, with 30-day mentions and spellings
get_brand_board	The in-app brand board: your brand vs confirmed competitors on visibility and share, optional daily trend
get_platform_matrix	Brand + auto-discovered competitors × platform, or topics × platform. competitor_limit (up to 20) + include_totals=true = the full cross-platform competitor comparison
get_competitor_cooccurrence	Brand + competitor co-occurrence, with optional answer text
get_verdict	AI Verdict, view required. view="competitors": who AI prefers over you — per competitor, the answers where it was preferred, with change vs the previous window. view="sources": cited domains in answers that carry verdict votes, with the share where your brand was judged negatively (default 7-day window)
get_topic_analytics	Per-topic analysis: sentiment, competitors, response types, trends
get_sentiment_dashboard	Sentiment distribution, trends, platform comparison

Site audits & traffic (3)

Tool	What it returns
get_audit_list	GEO site audits (AI-readiness diagnostics), paginated history
get_audit_detail	One audit. section="report" (default): per-category scores, critical/warning/passed issues. section="pages": per-page results
get_traffic_data	Site traffic, source required. source="ga4": GA4 sessions, page views, AI-referred traffic (add page_path for one page's views, bounce rate, traffic sources). source="cloudflare": AI-crawler requests, crawled paths, blocked crawlers

Market intelligence — resolve & browse (3)

Tool	What it returns
search_public_entities	Free-text resolver: brand / category / topic / product name or domain → public IDs (products via include_products)
list_public_topics	Browse public topics, with status/search filters
get_public_coverage	Free discovery metadata, view required. view="locales": valid {country, language} pairs for an entity. view="platforms": which AI platforms have data for a scope, ordered by volume. view="data_window": the published-batch time anchor and its 30 / 60 / 90-day windows

Market intelligence — topics (3)

Tool	What it returns
get_public_topic	One public topic, by view: overview (default), brand_leaderboard (ranked by Share of Mention), som_trend, prompt_matrix (prompt × brand heatmap), prompts (every prompt, with leader brand & share), citation_domains, commerce (activation rate, price stats, retail channels), difficulty (AI-visibility difficulty 0–100, like SEO keyword difficulty — for a topic_id, a prompt_id, or a whole category via product_space_id)
get_public_topic_prompt_detail	One prompt: per-brand breakdown, recent records, top citation domains
get_public_topic_record_detail	One public AI answer: snippeted text, citations, brands mentioned

Market intelligence — brands (1)

Tool

What it returns

get_public_brand

One public brand across topics, by view: facets overview (default), visibility, footprint, competitors, citations, category_ranking, revenue, shopping, citation_totals. Pass brand_ids (2–4) instead of brand_id for a side-by-side comparison on one facet (default visibility). view="perception": AI perception profile — canonical aspects, polarity, evidence; view="perception_mentions" + aspect: the source mentions behind one aspect. view="rank_citation": Google AI Overview rankings × AI citations — coverage, four search-counting quadrants, displacers; view="rank_citation_rows": paginated per-search detail

Market intelligence — categories, whitespace & momentum (3)

Tool	What it returns
get_public_category	One product-space category, faceted: leaderboard, SoM trend, topics, citation domains
get_category_whitespace	Opportunity map: strengths (covered / leading / close / defend) vs opportunities (prioritize / gap / watch)
get_category_brand_momentum	Period-over-period Share-of-Mention change: risers vs fallers

Market intelligence — AI search queries (1)

Tool	What it returns
get_public_search_queries	AI-search demand for a product space, by mode: territories (which brand owns each demand territory), product_spaces, query_detail (one query: brands, prompts, top sources), theme_detail (one topic)

Market intelligence — shopping (2)

Tool	What it returns
list_public_shopping_products	view="products" (default): one category's AI shelf — ranked products, channels, price bands (product_space_id required; page starts at 1). view="boards": the cross-category AI shelf leaderboard — hot / climbers / entrants with week-over-week rank moves (page starts at 0)
get_public_shopping_product_detail	One product. mode="full" (default): its full AI analysis — shelves, weekly trend, rivals, channels. mode="card": a cheap preview — evidence, topics, prompts, retail offers (product_space_id required)

Public source domains (3)

Tool	What it returns
get_public_sources_overview	Most-cited source domains across all public topics, each with its AI DA score
get_public_source_domain_detail	One citation source domain: coverage, co-occurring brands, optional full AI DA scorecard
get_public_source_brand_conduit	The topics where one source domain funnels AI attention toward one brand

Write tools (7)

Require write access granted on the OAuth consent screen. Static tokens and multi-workspace connections stay read-only.

Tool	What it does
create_prompt	Create a new monitoring prompt
archive_prompt	Archive a prompt (stops monitoring), or restore it with restore=true
update_prompt_tags	Add or remove tags on up to 500 prompts, or rename a tag brand-wide
move_prompts_to_topic	Move up to 500 prompts into a topic, or ungroup them
create_topic	Create a prompt topic
create_competitor	Add a competitor to track
trigger_prompt	Run monitoring for a prompt now (consumes credits)

Reports (1)

Tool	What it returns
get_agent_ready_scans	Agent Readiness scans for the signed-in user: the scan history, or one full scan result with scan_id

Discovery & routing (6)

Tool	What it returns
get_brand_context	One-shot orientation, free — call it first: brand, workspace & plan, today's business date, platforms, topics, tracked competitors, data window, remaining credits
get_current_date	Server time, for date-range validation
get_quota	MCP credits used / remaining this month and the reset date (always available)
resolve_page_context	Resolves a GEOly app URL the user is viewing into its entity scope and suggested tools
list_organizations	Workspaces the connection can access (multi-workspace mode)
list_brands	Brands in the workspace (multi-brand mode)

Versioning

• https://app.geoly.ai/api/mcp/v1 is GEOly MCP v1 — the tool surface listed above. The unversioned https://app.geoly.ai/api/mcp is the same handler with the same behavior, kept for existing configs. Every response carries the header GEOly-MCP-Version: 1, and the server announces the version at initialize (serverInfo.version 1.0.0, plus a first paragraph in the server instructions).
• Policy — the same as the GEOly Agent API (GEOly-API-Version: 1): an old version keeps running, unmaintained, and is not shut down. A breaking change would ship as v2 on a new path (/api/mcp/v2), and /api/mcp/v1 (and /api/mcp) would keep serving v1 unchanged. New tools, new views and new optional parameters ship on v1 without a version bump. There is no v2 today.
• Tool names from before the 0.7.0 consolidation (34 names, e.g. compare_public_brands, list_citation_domains) are no longer listed. They keep answering on v1 until 2026-11-30 and are then removed (calls return Tool … not found). A successful call under an old name carries a machine-readable top-level _deprecated block: sunset is the removal date, use is the call to switch to. Old → new mappings: geoly.ai/open/mcp and the skill's tools-catalog.
• Already removed: get_competitor_overview, get_brand_citations_daily and get_content_opportunities were not drop-in replaceable. Until 2026-11-30 they only return a free TOOL_REMOVED error naming the replacement (get_platform_matrix dimension="competitor", query_analytics dataset="brand_citations_daily", get_citation_overview section="table" + gap_only=true).
• Retired modes deleted: get_brand_search_queries mode roots / root_detail / topic_roots and get_public_search_queries mode queries / themes / brand_landscape / prompt_map no longer exist, and mode is now required on both tools.

Plans & access

Tool group	Availability
Brand monitoring, audits, site traffic (GA4 / Cloudflare), reports	Any active GEOly workspace
Market intelligence (topics, brands, categories, search queries, shopping)	Grow plan and above
Public source domains	All connections
Write tools	Write access granted at OAuth consent, single-workspace

Heavy market-intelligence queries may count toward plan quotas, and trigger_prompt consumes monitoring credits. See www.geoly.ai for plans.

Troubleshooting

• The first call returns 401 — that's the OAuth handshake by design; your client should open a browser. If it doesn't, the client lacks remote-OAuth support: bridge with mcp-remote (see above).
• 402 Payment Required — the workspace subscription is inactive.
• Market-intelligence tools are missing — the topic / brand / category / search-query / shopping tool groups require the Grow plan or above. (The three public source domain tools are separate and available on all connections.)
• Write tools are missing — write access wasn't granted at consent, you're on a static token, or the connection spans multiple workspaces (writes are single-workspace only). Re-authenticate and tick the write permissions you need.
• Opening the URL in a browser shows 405 — expected; the endpoint is POST-only streamable HTTP, not a web page.

Related projects

Project	What it is
GEOly-Cli	The same tools as a CLI, built for agents & CI
agent-skills	Skills that teach AI agents to use this server correctly
codex-plugins	Codex plugin marketplace: this server + the geoly-mcp skill

Support

This repo documents the hosted GEOly MCP server. Issues with docs and config examples are welcome here; for account, plan, or data questions, reach us through www.geoly.ai.

License

Documentation and examples in this repository are MIT licensed. The GEOly service itself is a commercial product.

---

www.geoly.ai · GEOly CLI · © GEOly