> ## 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) are **read-only**: they read the same data your account can already see and cannot change anything. Connections authenticated with an API key can additionally use write tools that mirror the REST API.

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

<Steps>
  <Step title="Open connector settings">
    In [claude.ai](https://claude.ai), go to **Customize → Connectors → the "+" → Add custom connector**.
  </Step>

  <Step title="Paste the server URL">
    Enter `https://api.athenahq.ai/api/mcp` and continue.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Connect ChatGPT

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

<Steps>
  <Step title="Open connector settings">
    In ChatGPT, open **Settings** and add a custom MCP connector (found under **Apps** or **Connectors**, depending on your plan and version).
  </Step>

  <Step title="Paste the server URL">
    Enter `https://api.athenahq.ai/api/mcp` and continue.
  </Step>

  <Step title="Sign in and pick an organization">
    Authorize with your AthenaHQ account and choose which organization to connect. ChatGPT then discovers the available tools.
  </Step>
</Steps>

<Note>
  Custom MCP connectors in ChatGPT require a plan that supports them (Pro, Business, or Enterprise) and may need developer mode enabled. Exact menu labels can vary by ChatGPT version.
</Note>

## Connect other MCP clients

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

<Steps>
  <Step title="Create an API key">
    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.

    <Card title="Manage API Keys" icon="key" href="https://app.athenahq.ai/settings/api">
      Create, view, and manage API keys in your organization settings
    </Card>
  </Step>

  <Step title="Add the server to your client config">
    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"
          }
        }
      }
    }
    ```
  </Step>
</Steps>

### 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.
* Sign-in connections (Claude.ai and ChatGPT) are read-only. API-key connections can additionally use write tools that mirror the REST API, with the same validation and audit logging.

<Info>
  Only organization admins can create, edit, or delete API keys. Sign-in connections (Claude.ai, ChatGPT) only read data; API-key connections can also use write tools that mirror the REST API, with the same validation and audit logging.
</Info>

## Available tools

The assistant discovers these automatically once connected. Each maps 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_ai_search_value`            | AI search value: topic-market value, captured value, headroom, coverage, per-topic detail |

### Prompts and responses

| Tool            | What it returns                                                      |
| --------------- | -------------------------------------------------------------------- |
| `get_prompts`   | Tracked prompts for a website, with volume, status, and geography    |
| `get_responses` | AI answers for a website, with cited sources, sentiment, and ranking |

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

### 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_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              |

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