MCP Server

Connect AthenaHQ to ChatGPT, 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.

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.

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 Optimizely Opal

You need the Opal administrator role to register a remote MCP provider.

Sign in with OAuth

1. In Opal, open Tools > External Providers > Add Remote MCP Provider.
2. Enter https://api.athenahq.ai/api/mcp, select OAuth 2.0, and click Discover OAuth Endpoints.
3. Leave Use my own credentials off so Opal uses Dynamic Client Registration. AthenaHQ issues a client ID automatically; you do not need a pre-issued client ID or client secret.
4. Leave scopes empty. AthenaHQ advertises no OAuth scopes. Do not enter the placeholder values your-client-id or scope1,scope2,scope3.
5. Enter a unique provider name and register it. Complete Opal’s approval steps, then connect from Tools > Connectors and sign in to AthenaHQ to choose your organization.
6. Select the tools to add. To use them in Opal Chat, enable Enable for Chat in Tools > Tools.

Connect with an API key

If you prefer a shared API-key connection, create a key on the API Keys page. Scope it to the websites Opal should access.

1. Register a remote MCP provider with the same server URL.
2. Select Bearer token and paste the complete AthenaHQ API key into Bearer Token, without adding the word Bearer.
3. Complete registration, add the tools, and enable them for chat as needed.

Opal sends the key as Authorization: Bearer <api-key>. The connection uses the key’s organization and website permissions, including write access within that scope. Delete the key in AthenaHQ to revoke access.

See Optimizely’s remote MCP setup guide for its provider approval and tool setup steps.

Connect other MCP clients

Clients that don’t support the sign-in flow authenticate with an API key using either x-api-key: <api-key> or Authorization: Bearer <api-key>. Bearer API-key authentication is supported on /api/mcp; REST endpoints under /api/v1 require x-api-key.

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. The existing get_credits_organization balance tool also allows scoped keys to read its organization-wide aggregate. Detailed usage tools (get_credit_usage and get_credit_usage_events) require a global organization API key, or a signed-in user with organization billing access. Website/group-only membership is insufficient for these usage tools.
• 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 the credit-usage tools, which require organization billing access. Viewers 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
get_shopping_metrics	Shopping Insights: product appearances in AI shopping answers, positions, prices, rivals

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, with the country market each targets (baseCountry)
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
get_credit_usage	Credit usage totals, time buckets, and paginated charged-pool breakdown for the organization
get_credit_usage_events	Paginated credit charges/refunds, recorded actions, and originating-website attribution

Credit-usage tools accept website_id to identify the organization, an optional range (24h, 7d, 30d, 90d, or all), and an optional UTC window with start_at_utc and end_at_utc. Use an explicit window for calendar months. For subsequent pages, keep the returned window and use next_offset; page sizes default to 25 and are capped at 50. get_credit_usage_events also accepts originating_website_id within the same organization.

Totals describe the full requested interval; entity and event pages may be partial. Charged group pools differ from originating websites, negative credits are refunds, and “Not recorded” means historical attribution is unavailable. These are read-only MCP tools; they add no public REST endpoints.

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