MCP Server

Connect AthenaHQ to Claude and other AI assistants via the Model Context Protocol

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.

1. Open connector settings

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

2. Paste the server URL

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

3. Sign in and pick an organization

   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.

1. Install the plugin

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

2. Sign in and pick an organization

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

3. 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.

1. 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

2. 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
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
get_content_detail	Full text of one content item: brief, body, cited URLs, links, status
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

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
rename_content	Rename a content row	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
create_pillar	Create a Knowledge Base pillar (get-or-create by name)	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. It is also the one write tool with no REST equivalent.

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.”