> ## Documentation Index
> Fetch the complete documentation index at: https://docs.athenahq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
> Connect AthenaHQ to Claude and other AI assistants via the Model Context Protocol
AthenaHQ ships a remote [Model Context Protocol](https://modelcontextprotocol.io) (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**
```text theme={null}
https://api.athenahq.ai/api/mcp
```
## Connect Claude.ai
No API key needed. You sign in with your AthenaHQ account.
In [claude.ai](https://claude.ai), go to **Customize → Connectors → the "+"
→ Add custom connector**.
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.
Open the [AthenaHQ plugin
listing](https://chatgpt.com/plugins/plugin_asdk_app_6a4da6c4bcfc81919397faceada2af69)
in ChatGPT and click **Install plugin**.
Authorize with your AthenaHQ account and choose which organization to
connect.
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.
Go to the [API Keys page](https://app.athenahq.ai/settings/api) in your dashboard. Scope the key to specific websites if you want to limit access, then save it securely.
Create, view, and manage API keys in your organization settings
Replace `your_api_key_here` with your key.
```json theme={null}
{
"mcpServers": {
"athenahq": {
"type": "http",
"url": "https://api.athenahq.ai/api/mcp",
"headers": {
"x-api-key": "your_api_key_here"
}
}
}
}
```
### Claude Code
```bash theme={null}
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](/api-reference/authentication):
* **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](#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](/api-reference/introduction).
### 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."