MCP Server

AthenaHQ ships a remote Model Context Protocol (MCP) server. Once connected, an AI assistant like Claude or ChatGPT can query your AI search visibility data in plain language (share of voice, citation and mention rates, ranking positions, cited sources, tracked prompts and responses, content, and pitches) without you writing any API calls. Connections you sign in to (Claude.ai and ChatGPT) read the same data your account can already see. Write tools are available on API-key connections and, for signed-in connections, wherever your role has the matching write permission. Every write runs the same validation and audit logging as the dashboard. Server URL

https://api.athenahq.ai/api/mcp

Connect Claude.ai

No API key needed. You sign in with your AthenaHQ account.

Open connector settings

In claude.ai, go to Customize → Connectors → the ”+” → Add custom connector.

Paste the server URL

Enter https://api.athenahq.ai/api/mcp and continue.

You’ll be prompted to sign in with your AthenaHQ account and choose which organization to connect. Claude then discovers all available tools automatically.

Connect ChatGPT

The fastest way is the official AthenaHQ plugin. No API key needed. You sign in with your AthenaHQ account.

Does the plugin have a separate cost?

From AthenaHQ, the plugin is free to install and has no separate plugin cost. It uses your existing AthenaHQ account, and normal plan limits still apply to the features and actions you access. Plugin availability in ChatGPT depends on your OpenAI plan, workspace settings, role, and region.

Install the plugin

Open the AthenaHQ plugin listing in ChatGPT and click Install plugin.

Authorize with your AthenaHQ account and choose which organization to connect.

Mention @AthenaHQ in a chat

Type @AthenaHQ followed by your question, for example “@AthenaHQ how is my brand showing up in AI search?”, and ChatGPT pulls your data into the conversation.

Prefer a manual setup? You can still add the MCP server as a custom connector: in ChatGPT Settings, add a custom MCP connector (found under Apps or Connectors, depending on your plan and version), enter https://api.athenahq.ai/api/mcp, and sign in with your AthenaHQ account. Custom connectors require a plan that supports them (Pro, Business, or Enterprise) and may need developer mode enabled.

Connect other MCP clients

Clients that don’t support the sign-in flow authenticate with an API key using the x-api-key header.

Create an API key

Go to the API Keys page in your dashboard. Scope the key to specific websites if you want to limit access, then save it securely.

Manage API Keys

Create, view, and manage API keys in your organization settings

Add the server to your client config

Replace your_api_key_here with your key.

{
  "mcpServers": {
    "athenahq": {
      "type": "http",
      "url": "https://api.athenahq.ai/api/mcp",
      "headers": {
        "x-api-key": "your_api_key_here"
      }
    }
  }
}

Claude Code

claude mcp add --transport http --scope user athenahq https://api.athenahq.ai/api/mcp \
  --header "x-api-key: your_api_key_here"

Access and scope

An MCP connection sees exactly what its credential is authorized for, the same scoping as the REST API:

Organization and website access follow the signed-in user (Claude.ai) or the API key’s scope.
A website-scoped API key is limited to its websites, with one deliberate exception: organization-level tools (such as get_credits_organization) return org-wide aggregates. Each tool applies the same authorization as its REST endpoint.
Write tools register on API-key connections and on signed-in connections bound to an organization. On a signed-in connection, each write is gated by your role’s permission for that category (see the Write tools table); API keys act with admin privileges within their scope. Every write runs the same validation and audit logging as the dashboard.

Only organization admins can create, edit, or delete API keys. On signed-in connections, tools follow your role: a viewer can read everything below except the three org-wide admin reads (get_groups, get_group_detail, get_user_by_email), and can only use writes open to every member (such as create_saved_view).

Available tools

The assistant discovers these automatically once connected. Most map to an endpoint in the API reference.

Metrics

Tool	What it returns
`get_share_of_voice_cumulative`	Share of voice across competitors for a date range
`get_share_of_voice_time_series`	Share of voice over time (daily)
`get_citation_rate_cumulative`	Citation rate (how often AI answers link to you) across competitors
`get_citation_rate_time_series`	Citation rate over time (daily)
`get_mention_rate_cumulative`	Mention rate (how often AI answers name your brand) across competitors
`get_mention_rate_time_series`	Mention rate over time (daily)
`get_position_cumulative`	Average ranking position in AI answers for a date range
`get_position_time_series`	Ranking position over time (daily)
`get_position_distribution`	Share of responses where the brand ranks top, middle, or bottom
`get_ai_search_value`	AI search value: topic-market value, captured value, headroom, coverage, per-topic detail

Analytics queries

Flexible query tools over the same analytics warehouse the dashboard uses, for questions the fixed metrics tools don’t cover.

Tool	What it returns
`query_metrics`	Aggregated measures (count, avg, sum, min, max) over any cube, grouped by any dimension, with optional period-over-period comparison
`query_rows`	Individual rows (response text, identifiers, mentions) from any cube, with cursor pagination

Attributes

Brand-perception keywords (like “Affordable” or “Slow Support”) extracted from AI answers.

Tool	What it returns
`get_attributes`	Attributes tracked for a website, with attribute IDs
`get_attribute_metrics`	Per attribute, how many responses mentioned it across a date range
`get_competitor_attribute_metrics`	The same breakdown per tracked competitor
`get_attribute_time_series`	Daily trend for one attribute, brand and competitors side by side

Prompts and responses

Tool	What it returns
`get_prompts`	Tracked prompts for a website, with volume, status, and geography
`get_prompt_tags`	Prompt tags for a website, with per-tag prompt counts
`get_personas`	Personas configured for a website, with per-persona prompt counts
`get_topics`	Active topics for a website, with the count of active prompts in each
`get_responses`	AI answers for a website, with cited sources, sentiment, and ranking. Set `include_response: false` and `compact_sources: true` for a light variation-level export
`get_response_detail`	One AI answer with full sources, mentions, and rank details
`get_response_streaming_status`	State and queue progress of the latest (or a specific) response run

Content

Tool	What it returns
`get_tracked_content`	Tracked content with citation, mention, and impression metrics
`list_content`	Every content item, published or not, each with the ids of the prompts it targets
`get_content_detail`	Full text of one content item: brief, body, cited URLs, links, status, and the prompts it was written for
`get_content_citation_prompts`	Prompts whose AI answers cited a given content item
`get_content_hub_sheets`	Content Hub tabs configured for a website
`get_content_status`	Normalized generation status (running / succeeded / failed) for one content item
`get_content_draft`	Current draft text of one item: article body, brief, status, latest version
`get_content_versions`	Version history of a content item, newest first, with labels and authors
`get_content_version`	Full text of one saved version

Two of these answer different questions about the same page, and it is worth keeping them apart. get_content_detail and list_content return the prompts a page was written for (its targeting, the same ids create_content takes); that comes from the content record and does not depend on any AI answer having appeared. get_content_citation_prompts returns the prompts whose AI answers cited the page over a date range, so it is legitimately empty for a page nothing has cited yet. Targeting includes prompts that were later deleted, flagged status: "deleted", because the page was still written for them and the Content Hub still shows them. get_prompts does not list deleted prompts, so an id from a targeting list may not resolve there; get_content_detail returns the prompt text inline for that reason. Targeting is capped at 100 entries per page (25 ids per row in list_content), with the untruncated size in prompts_total / prompt_count.

Knowledge Base

Requires the Knowledge Base to be enabled for the organization; when it isn’t, these tools return an error explaining that.

Tool	What it returns
`search_brand_facts`	Semantic search over approved brand facts, including facts not filed under any pillar
`get_brand_facts`	Paged brand-fact listing with pillar, review-status, source-type, and unfiled filters
`get_pillars`	Knowledge Base pillars with approved-fact counts and synthesized-document availability
`get_pillar_document`	A pillar’s synthesized markdown document

Sources and competitors

Tool	What it returns
`get_sources`	Top cited root domains, classified as owned / competitor / partner / third-party
`get_source_pages`	Individual cited URLs with per-URL metrics
`get_competitors`	Competitors tracked for a website

Pitches

Tool	What it returns
`list_pitches`	Pitch reports for the organization
`get_pitch`	One pitch report: competitors, prompts, attributes, top citing sources, metrics

Account and configuration

Tool	What it returns
`list_websites`	Websites your credential can access
`get_groups`	Groups in the organization (global API key or org-admin sign-in)
`get_group_detail`	One group with its member websites (global API key or org-admin sign-in)
`get_user_by_email`	User lookup by email, scoped to the caller’s organization (global API key or org-admin sign-in)
`get_date_range`	Earliest and latest response dates for a website
`get_locations`	Geographies configured for a website
`get_saved_views`	Saved filter presets for a website
`get_group_saved_views`	Saved views shared across a group
`get_credits_website`	Credit balance for a website
`get_credits_organization`	Credit balance for the organization

Site diagnostics

Tool	What it returns
`check_ai_access`	Whether major AI answer engines (ChatGPT, Claude, Perplexity, Gemini, Copilot, Grok, DeepSeek, Rufus) can crawl a public domain, with per-model HTTP and robots.txt verdicts and a diagnostic log shaped for host or CDN tickets. API-key connections only.

Write tools

Available on API-key connections and on signed-in connections bound to an organization. On a signed-in connection, each tool follows your role’s permission for its category (rightmost column); API keys act with admin privileges within their scope. Every write is validated and audit-logged, same as the dashboard.

Tool	What it does	Sign-in permission
`create_prompts`	Create one or more prompts, with topics, tags, personas, and geography	Prompts: write
`update_prompt`	Update a prompt’s text, type, topic, or geography	Prompts: write
`set_prompts_status`	Pause or unpause multiple prompts in one call	Prompts: write
`delete_prompt`	Delete a prompt (soft when responses exist, hard otherwise)	Prompts: write
`create_topic`	Create a topic (returns the existing topic when the name is taken)	Prompts: write
`update_topic`	Update a topic’s name or description	Prompts: write
`delete_topic`	Delete a topic, optionally with its prompts	Prompts: write
`create_location`	Create a geo-location, optionally attached to prompts	Prompts: write
`update_location`	Update a location	Prompts: write
`delete_location`	Delete a location	Prompts: write
`start_response_streaming`	Start a response run for all prompts or a selection	Prompts: write
`create_content`	Start the content pipeline (brief or full article, from a prompt or a topic)	Content: write
`revise_brief`	Rewrite a content brief from an instruction, recorded as a version	Content: write
`approve_brief`	Approve a brief and start the article from it (uses content credits)	Content: write
`revise_content`	Rewrite an article draft from an instruction, recorded as a version	Content: write
`edit_content`	Apply exact find-and-replace edits to a draft (deterministic, no AI model), recorded as a version	Content: write
`restore_content_version`	Bring an earlier version’s text back as the current draft (appends, never deletes)	Content: write
`publish_content`	Mark a piece as live at its URL so citation tracking starts	Content: write
`track_content_urls`	Register existing or third-party URLs as tracked pages (batch, idempotent, no credits)	Content: write
`rename_content`	Rename a content row	Content: write
`move_content`	Move content items between sheets (values on conflicting custom columns are permanently dropped)	Content: write
`delete_content`	Delete a content row (permanent, no undo)	Content: write
`add_brand_facts`	Add 1-50 brand facts through the full ingestion pipeline, with a per-fact outcome report	Brand knowledge: write
`update_brand_fact`	Update one brand fact’s text, source URL, or confidence	Brand knowledge: write
`delete_brand_facts`	Permanently delete 1-50 brand facts (no undo; missing ids reported, not errors)	Admin role
`create_pillar`	Create a Knowledge Base pillar (get-or-create by name)	Brand knowledge: write
`update_pillar`	Update a pillar’s name or description, or publish/archive it	Brand knowledge: write
`delete_pillars`	Permanently delete 1-20 pillars and every fact filed under them (no undo)	Admin role
`merge_pillars`	Merge source pillars into a published target, then delete the sources	Brand knowledge: write
`move_brand_facts`	File 1-50 facts under a published pillar (works for unfiled facts)	Brand knowledge: write
`create_saved_view`	Save a dashboard filter preset (name, optional icon, `filters` object up to 64KB, stored verbatim)	Any member

create_saved_view is the one write open to every website member, since saved views are personal presets: sign-in creations are attributed to the connected user, while API-key creations have no owning user, show as created via API in the dashboard, and can only be edited or deleted there by website admins. create_saved_view and move_content are the two write tools with no REST equivalent. delete_brand_facts and delete_pillars are the two writes gated on your role itself rather than a category permission: deleting brand knowledge matches the dashboard’s admin-only delete, and deleting a pillar permanently deletes every fact filed under it. An Editor with brand-knowledge write can update facts, curate pillars, and merge them, but not delete. API-key connections qualify through their admin scope.

Example prompts

Once connected, try:

“What’s my share of voice in AI answers versus my tracked competitors this quarter?”
“Which domains get cited most for the prompts I track?”
“Show my citation rate trend over the last 90 days.”
“What’s my captured AI search value and headroom by topic?”
“Pull the AI responses that mention my brand and summarize their sentiment.”

Overview

Integrations

Core Resources

Analytics

Content & Knowledge

Administration

Connect Claude.ai

Connect ChatGPT

Does the plugin have a separate cost?

Connect other MCP clients

Manage API Keys

Claude Code

Access and scope

Available tools

Metrics

Analytics queries

Attributes

Prompts and responses

Content

Knowledge Base

Sources and competitors

Pitches

Account and configuration

Site diagnostics

Write tools

Example prompts

​Connect Claude.ai

​Connect ChatGPT

​Does the plugin have a separate cost?

​Connect other MCP clients

Manage API Keys

​Claude Code

​Access and scope

​Available tools

​Metrics

​Analytics queries

​Attributes

​Prompts and responses

​Content

​Knowledge Base

​Sources and competitors

​Pitches

​Account and configuration

​Site diagnostics

​Write tools

​Example prompts

Connect Claude.ai

Connect ChatGPT

Does the plugin have a separate cost?

Connect other MCP clients

Claude Code

Access and scope

Available tools

Metrics

Analytics queries

Attributes

Prompts and responses

Content

Knowledge Base

Sources and competitors

Pitches

Account and configuration

Site diagnostics

Write tools

Example prompts