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) follow your account’s access permissions, with the Claude response-data exclusions described below. 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

Public AI crawler access

check_public_ai_access checks a public HTTPS domain without an AthenaHQ account. Pass { "domain": "example.com" }, with no path, credentials or custom port. The response includes nullable per-agent evidence, request diagnostics and a diagnostic log. Search, user retrieval and training have separate roles. Google-Extended is policy-only and receives no HTTP probe. The ChatGPT extension opens from supported sidebar and thread surfaces. It shows HTTP responses and robots permissions, restores tool-result reports, follows the host theme, and supports copy, export and explicit report sharing. Requests originate from AthenaHQ using crawler user-agent strings, not verified crawler IPs. Unknown observations stay inconclusive. These checks do not measure visibility or guarantee real crawler access, indexing or citation. Public scans are limited to five per minute per hashed ingress IP. Anonymous MCP requests have a separate limit of 60 per minute and 512 KiB per request; batches are rejected. Account analytics and writes retain authentication, scopes and audit checks. The authenticated check_ai_access tool and partner POST /v1/ai-access/check contract retain their existing behavior.

Date-range inputs

MCP tools with filters.start_date and filters.end_date accept these formats:

Format	Examples
Year first	`2026-09-29`, `2026/9/29`, `2026.9.29`
English month name	`September 29, 2026`, `Sep 29 2026`, `29 September 2026`, `29-Sep-2026`
Unambiguous numeric date	`09/29/2026`, `29/09/2026`, `29-09-2026`, `29.09.2026`
ISO 8601 timestamp	`2026-09-29T12:30:00Z`, `2026-09-29T12:30:00-07:00`

Dates are normalized before querying. Date-only inputs keep their calendar day; timestamps preserve their instant and are normalized to UTC. An ISO timestamp without a timezone is interpreted as UTC. A date-only start begins at midnight UTC; a date-only end includes that day through 23:59:59.999Z. Explicit end timestamps keep their exact instant, including midnight. Omitting end_date keeps the tool’s existing default. Invalid calendar dates, incomplete dates, relative expressions such as yesterday, and ambiguous numeric dates such as 03/04/2026 return a validation error instead of empty results. Spell out the month or use YYYY-MM-DD to resolve ambiguity. Use four-digit years. An explicit end must not precede the start. This flexibility applies to the shared MCP date-range filters, including metrics, responses, sources, and content analytics. Partner REST inputs, activity-feed timestamps, and generic cube query predicates retain their documented formats.

Connect Claude.ai

Connect from the AthenaHQ listing in Claude’s connector directory. No API key needed. You sign in with your AthenaHQ account.

The Claude connector excludes individual Claude-generated responses and response-level records derived from them by provider policy. You can use it to explore responses from other AI platforms, such as ChatGPT. Aggregate analytics, such as visibility totals and attribute metrics, can still include Claude data. To view individual Claude responses, use the AthenaHQ dashboard or the REST API with an API key.

On Claude Team plans, an Owner or Primary Owner must enable the connector for your organization before you can connect your account. On Enterprise plans, users with a custom role that includes Manage access to Libraries can also enable it.

Connect AthenaHQ

Open the AthenaHQ connector listing in Claude and follow the connection prompts. You can also find AthenaHQ under Customize > Connectors.

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

Ask about your AI search performance

In a chat, open + > Connectors and enable AthenaHQ for the conversation. Ask a question such as “Use AthenaHQ to compare our share of voice with competitors over the last 30 days.” Claude pulls your AthenaHQ data into the conversation. Review and approve tool requests when prompted.

Try questions like:

“How visible is our brand in AI search over the last 30 days?”
“What is ChatGPT saying about our brand in our tracked responses?”
“Which competitors gained share of voice over the last month?”
“Which pages are getting cited, and where should we focus next?”

Prefer a manual setup? In Claude, open Customize > Connectors and add a custom connector named AthenaHQ with the server URL https://api.athenahq.ai/api/mcp. Follow the authentication prompts to sign in with your AthenaHQ account and choose an organization. On Team and Enterprise plans, an Owner or Primary Owner must add the connector first; Enterprise users with Manage access to Libraries permission can also add it. See Claude’s custom connector guide for the steps for your plan.

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

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

In Opal, open Tools > External Providers > Add Remote MCP Provider.
Enter https://api.athenahq.ai/api/mcp, select OAuth 2.0, and click Discover OAuth Endpoints.
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.
Leave scopes empty. AthenaHQ advertises no OAuth scopes. Do not enter the placeholder values your-client-id or scope1,scope2,scope3.
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.
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.

Register a remote MCP provider with the same server URL.
Select Bearer token and paste the complete AthenaHQ API key into Bearer Token, without adding the word Bearer.
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.

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

Brand traits

Brand-perception keywords (like “Affordable” or “Slow Support”) extracted from AI answers. The API and tool names call them attributes.

Tool	What it returns
`get_attributes`	Brand traits tracked for a website, with attribute IDs
`get_attribute_metrics`	Per brand trait, 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 brand trait, brand and competitors side by side
`get_attribute_observations`	Individual brand trait observations with the response excerpt and a score from -1 to 1

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.

Prompt discovery

Tool	What it does	Sign-in permission
`start_prompt_discovery`	Start an asynchronous Discover study for untracked prompt opportunities	Prompts: write
`get_prompt_discovery_runs`	Read visible discovery history or one run’s progress	Prompts: view

To start a study, supply website_id, a name, and at least one source: website_analysis, social, search_console, keyword_gaps, or brand_guidelines. You can specify country, language, prompt_count_range with min and max, and custom_instructions. The default locale is en-US, the default country is United States, and the default prompt-count target is 25 to 50. Current count bands are 25 to 50, 50 to 75, 75 to 100, 100 to 150, and 150 to 200. Selecting brand_guidelines requires non-empty custom instructions. Keyword-gap sources retain their plan restrictions, and Search Console requires a connected integration to supply evidence. Review the sources, locale, requested count and instructions before launching. Launch uses external research services and AI models. Your MCP client handles invocation confirmation; Athena’s in-app chat approval card is not displayed over MCP. The requested count is a target, not a guarantee, and discovery does not add prompts to tracking automatically. Startup returns run_id and version. Pass that ID as run_id to get_prompt_discovery_runs to poll the same study; do not start a second study to check progress. Without run_id, the tool returns recent history. limit defaults to 10 and is capped at 20. Status is pending, running, completed, partial, failed, or cancelled; results include progress_percentage, the current phase when available, and total_prompts. Review candidate prompts on the application’s Discover page. These tools do not send notifications or add public REST endpoints.

Site diagnostics

Tool	What it returns
`check_ai_access`	Robots.txt policies and observed crawler user-agent responses from Athena’s network. Use `result.evidence` for nullable per-agent results and separate search/training; failed or challenged probes mean unknown access. No guarantee of real crawler access, indexing or citations. Includes a diagnostic log 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. To create a prompt tag, call create_prompt_tag with website_id and tag. The result includes tag_id. Tag names are trimmed, and an existing case-insensitive match returns created: false. Before changing assignments, call get_prompts with the same website_id and find the target prompt by its id. Its tags array contains the current assignments as { id, name } entries. Build the full desired tag_ids list from those IDs: add the new tag_id to assign it, or remove a tag’s ID to unassign it, keeping all other IDs. Call set_prompt_tags with website_id, that prompt’s prompt_id, and the resulting tag_ids. Pass an empty list only when you want to clear all tags. Repeat this read-and-update process for each prompt.

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
`create_prompt_tag`	Create a prompt tag, or return an existing tag with the same name (case-insensitive)	Prompts: write
`set_prompt_tags`	Replace one prompt’s tag assignments, or clear them with an empty list	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
`start_prompt_discovery`	Start a Discover study with selected sources, locale and optional instructions	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

Public AI crawler access

Date-range inputs

Connect Claude.ai

Connect ChatGPT

Does the plugin have a separate cost?

Connect Optimizely Opal

Connect with an API key

Connect other MCP clients

Manage API Keys

Claude Code

Access and scope

Available tools

Metrics

Analytics queries

Brand traits

Prompts and responses

Content

Knowledge Base

Sources and competitors

Pitches

Account and configuration

Prompt discovery

Site diagnostics

Write tools

Example prompts

​Public AI crawler access

​Date-range inputs

​Connect Claude.ai

​Connect ChatGPT

​Does the plugin have a separate cost?

​Connect Optimizely Opal

​Sign in with OAuth

​Connect with an API key

​Connect other MCP clients

Manage API Keys

​Claude Code

​Access and scope

​Available tools

​Metrics

​Analytics queries

​Brand traits

​Prompts and responses

​Content

​Knowledge Base

​Sources and competitors

​Pitches

​Account and configuration

​Prompt discovery

​Site diagnostics

​Write tools

​Example prompts

Public AI crawler access

Date-range inputs

Connect Claude.ai

Connect ChatGPT

Does the plugin have a separate cost?

Connect Optimizely Opal

Sign in with OAuth

Connect with an API key

Connect other MCP clients

Claude Code

Access and scope

Available tools

Metrics

Analytics queries

Brand traits

Prompts and responses

Content

Knowledge Base

Sources and competitors

Pitches

Account and configuration

Prompt discovery

Site diagnostics

Write tools

Example prompts