MCP Server

List all projects in the authenticated workspace. Use this as a first step to discover project IDs — every other tool requires a project_id. Returns each project's ID, name, and website, with optional search and pagination.

Parameters

Example response

{
  "projects": [
    { "id": 123, "name": "Acme Corp", "website": "https://acme.com" },
    { "id": 124, "name": "Acme EU", "website": "https://acme.eu" }
  ],
  "pagination": { "page": 1, "per_page": 50, "total": 2, "total_pages": 1 }
}

Get details about a project: name, website, description, location, project language, action language, and focus area. Call this first to understand what brand or entity you are working on.

Parameters

Example response

{
  "id": 123,
  "name": "Acme Corp",
  "website": "https://acme.com",
  "description": "B2B SaaS platform for...",
  "country": "United States",
  "language": "en",
  "action_language": null,
  "focus": "product"
}

Get a project's GEO visibility metrics over the last 3 months. Returns a time-series of visibility score (0–100), average AI ranking position, mention count, and coverage percentage, plus a per-brand competitor ranking breakdown for each data point.

Parameters

Example response

{
  "project_name": "Acme Corp",
  "rows": [
    {
      "date": "2026-04-07",
      "visibility_score": 42.5,
      "avg_position": 2.1,
      "mentions": 38,
      "coverage_pct": 61.3,
      "ranking": [
        { "name": "Acme Corp", "is_main_brand": true, "mentions": 38, "visibility_score": 42.5 },
        { "name": "Competitor X", "is_main_brand": false, "mentions": 55, "visibility_score": 58.2 }
      ]
    }
  ]
}

Get the visibility score trend broken down per AI model over a date range. Each data point shows the overall score plus individual scores for ChatGPT, Gemini, Perplexity, and other enabled models. Use this to diagnose which AI providers are driving visibility changes.

Parameters

Example response

{
  "project_id": 123,
  "start": "2026-04-01", "end": "2026-04-07",
  "models": ["chatgpt", "gemini", "perplexity"],
  "points": [
    {
      "date": "2026-04-01",
      "total": 48.5,
      "totals": { "chatgpt": 55.2, "gemini": 41.0, "perplexity": 49.3 }
    }
  ]
}

Get a ranked list of all domains and URLs cited by AI models across all prompts in a project — a project-wide citation audit. Supports grouping by individual page (default) or by domain with pages nested inside. Use this to understand which external sources AI models trust most when discussing topics relevant to your brand.

Parameters

Example response (group: page)

{
  "project_id": 123,
  "rows": [
    {
      "domain": "techcrunch.com",
      "page": "/2026/04/10/best-ai-tools",
      "url": "https://techcrunch.com/2026/04/10/best-ai-tools",
      "frequency": 14,
      "model_keys": ["chatgpt", "perplexity"],
      "model_frequencies": { "chatgpt": 9, "perplexity": 5 }
    }
  ],
  "groups": [],
  "pagination": { "page": 1, "per_page": 50, "total": 84, "total_pages": 2 }
}

List active prompts tracked by a project, with per-prompt visibility score, average AI position, sentiment, and competitor mention counts.

Parameters

Get full details and performance metrics for a single prompt by ID. Returns visibility score, average AI position, sentiment, and competitor mention breakdown. Use list_prompts to discover IDs.

Parameters

Get the actual text responses from ChatGPT, Gemini, Perplexity, and other AI models for a specific prompt. Each row includes the model key, the full response text, whether the brand was mentioned, the brand's ranking position, and a citations preview. This is the core intelligence tool for understanding how AI models talk about a brand.

Parameters

Example response row

{
  "model_key": "chatgpt",
  "position": 2,
  "brand_present": true,
  "response_text": "Acme Corp is a leading provider of...",
  "citations_count": 4,
  "citations": [ { "domain": "acme.com", "url": "https://acme.com/product" } ]
}

Get the domains and URLs that AI models cite when responding to a prompt, ranked by frequency. Each row includes the domain, page path, total citation count, and a per-model frequency breakdown. Use this to understand which sources AI models trust — and whether the brand's own site is being cited.

Parameters

Example response

{
  "rows": [
    {
      "domain": "acme.com",
      "page": "/blog/overview",
      "url": "https://acme.com/blog/overview",
      "frequency": 7,
      "model_keys": ["chatgpt", "gemini"],
      "model_frequencies": { "chatgpt": 5, "gemini": 2 }
    }
  ],
  "pagination": { "page": 1, "per_page": 15, "total": 23, "total_pages": 2 }
}

Get the competitor ranking table for a specific prompt — how often each brand and direct competitor is mentioned in AI responses to that question, with visibility score and average AI position. Use this for a deep-dive into competitive dynamics for a single query (vs get_competitor_rankings which aggregates across all prompts).

Parameters

Example response

{
  "project_id": 123,
  "prompt_id": 456,
  "start": "2026-04-01", "end": "2026-04-07",
  "models": ["chatgpt", "gemini", "perplexity"],
  "denominator": 42,
  "rows": [
    {
      "rank": 1, "name": "Acme Corp", "website": "acme.com",
      "is_main_brand": true, "brand_present": true,
      "visibility": 71.43, "position": 1.8, "mentions": 30
    },
    {
      "rank": 2, "name": "Rival Inc", "website": "rival.com",
      "is_main_brand": false, "brand_present": true,
      "visibility": 52.38, "position": 2.4, "mentions": 22
    }
  ]
}

Add a new prompt to be tracked by a project. The prompt is queued for the next scheduled scan across all enabled AI models. Requires a topic_id — use list_topics to find available topics, or create_topic to create a new one.

Parameters

Stop tracking a prompt. Archived prompts are excluded from future scans and hidden from the active list. This is a soft-delete — historical data is fully preserved and the prompt can be found in the archived list via the REST API.

Parameters

Enqueue AI-powered optimization action generation for one or more prompts. Actions are created asynchronously and appear in list_actions once ready.

Parameters

Example response

{
  "enqueued_prompts_count": 3,
  "credit_cost_per_prompt": 5,
  "total_credit_cost": 15,
  "request_id": "a1b2c3d4-...",
  "message": "Enqueued action generation. Actions will be created asynchronously."
}

List topics for a project. Returns each topic's ID and name. Use the returned IDs when calling create_prompt.

Parameters

Create a new topic. Topic names must be unique within the project. Returns the new topic ID — use it immediately in create_prompt.

Parameters

List active (todo or in_progress) AI-generated optimization actions for a project, sorted high → medium → low priority. Each action includes a title, implementation detail, priority, effort level, estimated impact score, and an optional Markdown implementation guide.

Parameters

Action fields

Update the status of an optimization action to track progress as work is completed.

Parameters

Get the visibility ranking table for all tracked brands and competitors. Returns mention count, average AI position, and visibility score (% of prompts where each brand appears) from the most recent scan data.

Parameters

List the direct competitors currently configured for a project. Returns each competitor's ID, name, and website. Use the competitor ID when calling remove_direct_competitor.

Parameters

Add a competitor website to track. The competitor is included in future scans. Display name is derived from the domain automatically if not provided.

Parameters

Remove a competitor from tracking. Future scans will no longer include this competitor. Historical data is preserved. Use list_direct_competitors to find competitor IDs.

Parameters

List fan-out queries for a project. Results are grouped by topic → prompt → query list. Each query includes which LLM model returned it and a timestamp. Supports filtering by topic IDs, model, and full-text search.

Parameters

Example response

{
  "project_id": 1,
  "models": ["chatgpt", "gemini"],
  "pagination": { "page": 1, "per_page": 50, "total": 14, "total_pages": 1 },
  "topics": [
    {
      "id": 1,
      "name": "AI brand monitoring",
      "prompts": [
        {
          "id": 13,
          "content": "which platforms provide ai brand monitoring?",
          "fanout_updated_at": "2026-05-01T10:00:00Z",
          "fanout_queries": [
            { "query": "best ai brand monitoring tools 2026", "model_key": "chatgpt", "fetched_at": "2026-05-01T10:00:00Z" },
            { "query": "ai-powered brand tracking software", "model_key": "gemini", "fetched_at": "2026-05-01T10:00:00Z" }
          ]
        }
      ]
    }
  ]
}

Fetch fan-out queries from LLM models for a single prompt. Each enabled model returns the semantically related query variants it associates with the prompt. Runs asynchronously — results appear in list_fanout_queries once ready.

Parameters

Fetch fan-out queries from LLM models for multiple prompts at once. Each enabled model returns the related query variants for each prompt. Prompts on cooldown are automatically skipped and reported in the response. Results appear in list_fanout_queries once ready.

Parameters

Example response

{
  "project_id": 1,
  "queued_count": 3,
  "skipped_count": 1,
  "skipped_prompt_ids": [17],
  "credits_charged": 9,
  "message": "Fan-out query generation queued for 3 prompt(s). Results will appear in list_fanout_queries once ready."
}

Get information about the authenticated workspace: name, description, enabled LLM models, and a credits summary. Use this to check available credits before calling credit-consuming tools.

Parameters

No parameters required.

Example response

{
  "id": 1,
  "name": "Acme Corp",
  "workspace_type": "standard",
  "llm_models": ["chatgpt", "gemini", "perplexity"],
  "credits": {
    "balance": 850,
    "used_this_period": 150,
    "monthly_allowance": 1000
  }
}

Create a fully provisioned Ceyo project in one call. The project is created immediately and an async onboarding job populates topics, prompts, and initial scan data. Poll get_onboard_status to track completion.

Parameters

Example response

{
  "onboard_id": "ob_a1b2c3d4-...",
  "project_id": 42,
  "status": "running",
  "message": "Project created and onboarding started. Poll get_onboard_status with the onboard_id to track progress."
}

Poll the onboarding status of a project created via create_project. Returns the current status and counts of topics, prompts, and competitors once the project structure is ready.

Parameters

Status values

Get full details for a single optimization action. Returns the complete payload including the Markdown implementation guide, action type, effort level, estimated impact, feasibility score, target URL/platform, and linked prompts. Use list_actions to discover action IDs.

Parameters

Additional fields (vs list_actions)

List prompts that Ceyo has suggested for tracking, grouped by topic. Suggested prompts are pending review — they are not yet tracked or included in scans. Use promote_suggested_prompt to add one to active tracking.

Parameters

Promote a suggested prompt to active tracking. The prompt will be included in future scans across all enabled AI models. Use list_suggested_prompts to discover suggested prompt IDs.

Parameters

List competitors that Ceyo has identified as relevant based on scan data, but have not yet been added to direct tracking. Each entry includes visibility score and mention count. Use promote_suggested_competitor to add one to direct tracking.

Parameters

Promote a suggested competitor to direct competitor tracking. Once promoted, they will appear in future scans and all ranking data. Use list_suggested_competitors to discover competitor IDs.

Parameters

Get the GA4 overview for a project: total and AI-sourced sessions, AI share of traffic, conversion summary, daily time series, and a per-AI-platform breakdown (ChatGPT, Gemini, Perplexity, etc.). Also includes completed action markers to correlate GEO actions with traffic changes.

Parameters

Get the GA4 conversion breakdown. Returns conversion rates and counts split by AI referrals, organic, and direct traffic — plus per-AI-platform conversion rates. Optionally filter by specific GA4 key event names using get_analytics_conversion_events to discover available events.

Parameters

Get the top landing pages by AI referral traffic. Each page includes AI sessions, total sessions, conversions, trend vs the previous period, and a per-platform breakdown. Also includes a platform matrix showing which AI sources send traffic to each page.

Parameters

Get earned referral sources — websites driving referral traffic that were targeted by completed optimization actions. Each source shows session counts, earned type (Editorial, UGC, Reference), and a daily trend series. Use this to measure the real-world traffic impact of completed actions.

Parameters

List GA4 key events (conversion events) recorded for a project, with total counts. Use the returned event names as input to the event_names filter in get_analytics_conversions.

Parameters