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

# Serveur MCP

> Connectez AthenaHQ à ChatGPT, Claude et aux autres assistants IA via le Model Context Protocol

AthenaHQ propose un serveur distant [Model Context Protocol](https://modelcontextprotocol.io) (MCP). Une fois connecté, un assistant comme Claude ou ChatGPT peut interroger en langage courant vos données de visibilité dans la recherche IA : part de voix, taux de citation et de mention, positions, sources citées, prompts et réponses suivis, contenus et propositions, sans écrire d’appels API.

Les connexions par compte (Claude.ai et ChatGPT) respectent vos autorisations, avec les exclusions de réponses Claude décrites ci-dessous. Les outils d’écriture sont disponibles avec une clé API et, pour les connexions par compte, lorsque votre rôle possède l’autorisation correspondante. Chaque écriture applique les mêmes validations et journaux d’audit que le tableau de bord.

**URL du serveur**

```text theme={null}
https://api.athenahq.ai/api/mcp
```

## Étiquettes de sources

Utilisez `source_tags__list`, `source_tags__get_sources`, `source_tags__create`, `source_tags__update` et `source_tags__delete` pour gérer les étiquettes de sources. Trois catégories sont visibles pour un site : Propriétaire et Concurrent (définies d’après les identifiants des marques), étiquettes natives classées automatiquement par AthenaHQ (Médias, Réseaux sociaux, Gouvernement, E-commerce, Sites d’avis, Communiqués de presse, Enseignement et recherche, Wiki) et étiquettes personnalisées. Elles sont distinctes des étiquettes de prompts. Tous les outils exigent `website_id` et respectent le périmètre de la clé ou les autorisations Analyses du compte. La lecture exige un accès en consultation ; les écritures, un accès en écriture.

`source_tags__list` renvoie chaque étiquette avec son type, icône, couleur, révision et motifs : les motifs propres aux étiquettes personnalisées ou, pour les natives, uniquement les ajouts/retraits de ce site. Les motifs internes de la plateforme ne sont jamais listés. `offset` et `limit` paginent les étiquettes ; `tag_id`, `pattern_offset` et `pattern_limit` paginent les motifs d’une étiquette.

`source_tags__get_sources` liste les domaines cités et leur nombre de citations : ceux correspondant à une étiquette personnalisée (`tag_id`) ou, avec `untagged: true`, ceux sans aucune étiquette. Les étiquettes natives et Propriétaire/Concurrent sont refusées comme `tag_id` ; ajoutez ou retirez plutôt leurs motifs.

`source_tags__update` modifie une étiquette avec son `expected_revision` actuel. Pour une étiquette personnalisée, il accepte `name`, `add_patterns` et les `remove_patterns` exacts. Pour une native, il ajoute ou retire des motifs dans la copie du site : un ajout est accepté seulement si le motif ne porte pas déjà cette étiquette ici ; un retrait seulement s’il la porte, via règle de plateforme, classification automatique ou ajout personnel. Les étiquettes natives ne peuvent pas être renommées. `source_tags__create` crée une étiquette personnalisée avec motifs, icône et couleur facultatives ; les noms natifs sont réservés. `source_tags__delete` supprime une étiquette personnalisée et ses attributions en conservant les sources ; les natives ne peuvent pas être supprimées. Les motifs acceptent hôtes, sous-arbres (`*.example.com`), sections de chemin, pages exactes et contraintes de requête, avec 500 motifs maximum par liste.

La modification et la suppression déclarent des indications d’action destructrice et demandent à l’assistant d’obtenir une confirmation explicite. Votre client MCP contrôle les demandes d’approbation ; ces indications n’imposent pas de dialogue. Les appels autorisés s’exécutent immédiatement. La conversation IA Athena conserve ses cartes d’approbation. Si `analytics_refreshed` est faux, l’écriture a réussi mais les analyses filtrées peuvent être en cache ; ne répétez pas l’écriture pour les actualiser. Ces outils n’ajoutent aucun point de terminaison REST.

## Prospection

La prospection identifie les auteurs des pages citées par l’IA et prépare un message pour chacun. Cinq outils couvrent le même travail que la page Prospection :

* `list_outreach_contacts` lit les contacts enregistrés : statut, auteur, e-mail et source, LinkedIn, page de contact et brouillon. Seules les pages triées, enrichies ou avec brouillon apparaissent ; trouvez les autres via `get_source_pages`. Filtrez par `url` ou `statuses` ; paginez avec `offset` et `limit` (20 par défaut, 50 maximum).
* `find_outreach_author` lit la signature de la page, les adresses publiées et Hunter.io, puis enregistre le résultat. Sans auteur, il conserve l’adresse générale ou page de contact trouvée.
* `draft_outreach_message` rédige et enregistre un brouillon pour une page, avec les instructions personnalisées communes au site (définies dans Prospection), le nom d’auteur enregistré et le nom de l’utilisateur connecté ; une clé API peut fournir `sender_name`. Rien n’est envoyé.
* `update_outreach_contact` modifie auteur, e-mail, LinkedIn, objet ou corps. Fournissez au moins un champ ; seuls ceux fournis changent, et `null` efface un champ. Changer d’auteur efface aussi l’e-mail et LinkedIn précédents sauf si vous en fournissez de nouveaux.
* `set_outreach_status` déplace jusqu’à 100 pages vers `New`, `Todo`, `In Progress`, `Done` ou `Rejected` et consigne les changements des contacts existants dans leur activité. Une page sans contact en reçoit un au nouveau statut, sans entrée d’activité initiale ; `New` ne réinitialise que les contacts existants.

Chaque e-mail porte `email_source` : `page_author` (publié et correspondant à l’auteur), `page_contact` (adresse du site, pas forcément de l’auteur), `hunter` (correspondance Hunter.io non publiée sur la page, à vérifier avant envoi) ou `manual`. `null` signifie une source inconnue, notamment pour les anciennes adresses. `page_emails` liste jusqu’à cinq adresses publiées par la page ou sa page de contact, celle choisie d’abord pour comparaison ; ce n’est pas un inventaire exhaustif.

Les pages sont identifiées par `url` dans le format du flux Prospection, comme `example.com/blog/post`. Un contact enregistré à l’URL exacte fournie est utilisé en priorité, notamment une variante de requête traitée séparément par les règles d’URL. Sinon protocole, `www.` et paramètres (comme `utm_`) sont ignorés, comme sur la page Prospection. La lecture utilise toujours l’URL fournie. Tous les outils exigent `website_id` et les droits Contenu : consultation pour lister, écriture pour le reste. `find_outreach_author` coûte 0,1 crédit lorsqu’il trouve un auteur ; `draft_outreach_message`, 0,1 crédit par brouillon, facturés en crédits entiers toutes les 10 lignes réussies, comme dans l’interface. Ces outils n’ajoutent aucun point de terminaison REST.

## Accès public des robots d’IA

`check_public_ai_access` vérifie un domaine HTTPS public sans compte AthenaHQ. Fournissez `{ "domain": "example.com" }`, sans chemin, identifiants ni port personnalisé. La réponse contient les observations `evidence` nullables par agent, les `diagnostics` des requêtes et un `log`. Recherche, récupération utilisateur et entraînement ont des rôles séparés. Google-Extended est limité aux règles et ne reçoit aucun test HTTP.

L’extension ChatGPT s’ouvre depuis les surfaces compatibles de barre latérale et de conversation. Elle affiche réponses HTTP et autorisations robots, restaure les rapports de résultats d’outil, suit le thème hôte et permet copie, export et partage explicite. Les requêtes viennent d’AthenaHQ avec les agents utilisateurs des robots, pas d’IP de robots vérifiées. Les observations inconnues restent non concluantes. Ces vérifications ne mesurent pas la visibilité et ne garantissent ni accès réel, ni indexation, ni citation.

Les analyses publiques sont limitées à cinq par minute et par IP d’entrée hachée. Les requêtes MCP anonymes ont une limite distincte de 60 par minute et de 512 Kio par requête ; les lots sont refusés. Analyses de compte et écritures conservent authentification, périmètres et contrôles d’audit. L’outil authentifié `check_ai_access` et le contrat partenaire `POST /v1/ai-access/check` conservent leur fonctionnement.

Un appel d’outil de compte sans identifiants renvoie HTTP 401 avec `WWW-Authenticate` vers les métadonnées de ressource OAuth. La réponse conserve aussi le défi `_meta["mcp/www_authenticate"]`. Le client peut utiliser l’un ou l’autre pour lancer la connexion puis réessayer. Initialisation, découverte d’outils et outils publics de robots restent accessibles sans connexion.

## Formats de plage de dates

Les outils avec `filters.start_date` et `filters.end_date` acceptent :

| Format | Exemples |
| - | - |
| Année en premier | `2026-09-29`, `2026/9/29`, `2026.9.29` |
| Nom du mois en anglais | `September 29, 2026`, `Sep 29 2026`, `29 September 2026`, `29-Sep-2026` |
| Date numérique non ambiguë | `09/29/2026`, `29/09/2026`, `29-09-2026`, `29.09.2026` |
| Horodatage ISO 8601 | `2026-09-29T12:30:00Z`, `2026-09-29T12:30:00-07:00` |

Les dates sont normalisées avant interrogation. Les dates seules gardent leur jour calendaire ; les horodatages gardent leur instant, normalisé en UTC. Sans fuseau, un horodatage ISO est interprété en UTC. Une date de début seule commence à minuit UTC ; une date de fin seule inclut la journée jusqu’à `23:59:59.999Z`. Une fin horodatée garde son instant exact, même à minuit. Omettre `end_date` conserve la valeur par défaut de l’outil.

Dates invalides ou incomplètes, expressions relatives comme `yesterday` et dates numériques ambiguës comme `03/04/2026` renvoient une erreur de validation plutôt que des résultats vides. Écrivez le mois ou utilisez `YYYY-MM-DD`, avec année sur quatre chiffres. Une fin explicite ne doit pas précéder le début.

Cette souplesse concerne les filtres MCP communs, notamment métriques, réponses, sources et analyses de contenu. Les entrées REST partenaires, horodatages d’activité et prédicats de requêtes de cubes gardent leurs formats documentés.

## Connecter Claude.ai

Connectez-vous depuis AthenaHQ dans l’annuaire de connecteurs Claude. Aucune clé API nécessaire : utilisez votre compte AthenaHQ.

> [!NOTE]
>
> Le connecteur Claude exclut les réponses individuelles générées par Claude et
> les enregistrements au niveau réponse qui en dérivent, selon les règles du
> fournisseur. Vous pouvez explorer les réponses d’autres plateformes, comme
> ChatGPT. Les analyses agrégées (totaux de visibilité, attributs, etc.) peuvent
> toujours inclure Claude. Pour les réponses Claude individuelles, utilisez le
> tableau de bord ou l’API REST avec une [clé
> API](https://docs.athenahq.ai/fr/api-reference/authentication.md).

Avec Claude Team, un propriétaire ou propriétaire principal doit activer le connecteur pour l’organisation. Avec Enterprise, un rôle personnalisé incluant **Gérer l’accès aux bibliothèques** peut aussi l’activer.

**1. Connecter AthenaHQ**

Ouvrez la [fiche du connecteur AthenaHQ](https://claude.ai/directory/athenahq) et suivez les instructions. Vous pouvez aussi le trouver dans **Personnaliser > Connecteurs**.

**2. Vous connecter et choisir une organisation**

Connectez-vous à AthenaHQ et choisissez l’organisation à connecter. Claude découvre automatiquement tous les outils disponibles.

**3. Interroger vos performances de recherche IA**

Dans une conversation, ouvrez **+ > Connecteurs** et activez AthenaHQ. Demandez par exemple « Utilise AthenaHQ pour comparer notre part de voix aux concurrents sur les 30 derniers jours. » Claude ajoute les données à la conversation. Examinez et approuvez les appels demandés.

Exemples de questions :

* « Quelle est la visibilité de notre marque dans la recherche IA sur les 30 derniers jours ? »
* « Que dit ChatGPT de notre marque dans nos réponses suivies ? »
* « Quels concurrents ont gagné de la part de voix le mois dernier ? »
* « Quelles pages sont citées et où devons-nous concentrer nos efforts ? »

> [!NOTE]
>
> Pour une configuration manuelle, ouvrez **Personnaliser > Connecteurs** dans Claude et ajoutez **AthenaHQ** avec `https://api.athenahq.ai/api/mcp`. Authentifiez-vous puis choisissez une organisation. Avec Team/Enterprise, un propriétaire ou propriétaire principal doit d’abord l’ajouter ; les utilisateurs Enterprise avec **Gérer l’accès aux bibliothèques** le peuvent aussi. Consultez le [guide des connecteurs personnalisés Claude](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) pour votre offre.

## Connecter ChatGPT

Le plus rapide est le plugin officiel AthenaHQ. Sans clé API : connectez-vous avec votre compte AthenaHQ.

### Le plugin a-t-il un coût distinct ?

Côté AthenaHQ, l’installation est gratuite, sans coût propre au plugin. Il utilise votre compte existant et les limites habituelles de votre offre s’appliquent aux fonctionnalités et actions. Sa disponibilité dans ChatGPT dépend de l’offre OpenAI, des paramètres d’espace, du rôle et de la région.

**1. Installer le plugin**

Ouvrez la [fiche du plugin
AthenaHQ](https://chatgpt.com/plugins/plugin_asdk_app_6a4da6c4bcfc81919397faceada2af69)
dans ChatGPT et cliquez sur **Installer le plugin**.

**2. Vous connecter et choisir une organisation**

Autorisez avec votre compte AthenaHQ puis choisissez l’organisation.

**3. Mentionner @AthenaHQ dans une conversation**

Saisissez `@AthenaHQ` suivi de la question, comme « @AthenaHQ comment ma
marque apparaît-elle dans la recherche IA ? ». ChatGPT ajoute vos données à
la conversation.

> [!NOTE]
>
> Pour une configuration manuelle, ajoutez dans les **Paramètres** ChatGPT un
> connecteur MCP personnalisé, sous **Applications** ou **Connecteurs** selon
> votre offre/version. Saisissez `https://api.athenahq.ai/api/mcp` puis
> connectez-vous à AthenaHQ. Une offre compatible (Pro, Business ou Enterprise)
> est nécessaire, parfois avec le mode développeur activé.

## Connecter Optimizely Opal

Le rôle administrateur Opal est nécessaire pour enregistrer un fournisseur MCP distant.

### Connexion OAuth

1. Dans Opal, ouvrez **Outils > Fournisseurs externes > Ajouter un fournisseur MCP distant**.
2. Saisissez `https://api.athenahq.ai/api/mcp`, choisissez **OAuth 2.0**, puis **Découvrir les points de terminaison OAuth**.
3. Laissez **Utiliser mes propres identifiants** désactivé pour utiliser Dynamic Client Registration. AthenaHQ émet automatiquement un ID client ; aucun ID ou secret préémis n’est nécessaire.
4. Laissez les périmètres vides : AthenaHQ n’en déclare aucun. Ne saisissez pas `your-client-id` ni `scope1,scope2,scope3`.
5. Donnez un nom unique et enregistrez. Terminez les approbations Opal, puis connectez depuis **Outils > Connecteurs** et choisissez votre organisation après connexion AthenaHQ.
6. Choisissez les outils. Pour Opal Chat, activez **Activer pour la conversation** dans **Outils > Outils**.

### Connexion par clé API

Pour une clé partagée, créez-la dans [Clés API](https://app.athenahq.ai/settings/api), limitée aux sites accessibles à Opal.

1. Enregistrez un fournisseur MCP distant avec la même URL.
2. Choisissez **Jeton bearer** et collez la clé AthenaHQ complète dans **Bearer Token**, sans ajouter `Bearer`.
3. Terminez, ajoutez les outils et activez-les pour les conversations si nécessaire.

Opal envoie `Authorization: Bearer <api-key>`. La connexion utilise les droits d’organisation et de site de la clé, y compris l’écriture dans ce périmètre. Supprimez la clé dans AthenaHQ pour révoquer l’accès.

Consultez le [guide MCP distant d’Optimizely](https://support.optimizely.com/hc/en-us/articles/47179211028749-Add-a-remote-MCP-provider) pour l’approbation et la configuration des outils.

## Connecter d’autres clients MCP

Les clients sans connexion par compte utilisent `x-api-key: <api-key>` ou `Authorization: Bearer <api-key>`. L’authentification bearer par clé est prise en charge sur `/api/mcp` ; les points REST `/api/v1` exigent `x-api-key`.

**1. Créer une clé API**

Ouvrez [Clés API](https://app.athenahq.ai/settings/api) dans le tableau de bord. Limitez la clé aux sites souhaités et conservez-la en sécurité.

> [card] [Gérer les clés API](https://app.athenahq.ai/settings/api)
>
> Créez, consultez et gérez les clés API de votre organisation

**2. Ajouter le serveur à la configuration du client**

Remplacez `your_api_key_here` par votre clé.

```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"
```

## Accès et périmètre

Une connexion MCP ne voit que ce que ses identifiants autorisent, comme l’[API REST](https://docs.athenahq.ai/fr/api-reference/authentication.md) :

* L’accès à l’**organisation** et aux **sites** suit l’utilisateur connecté (Claude.ai) ou le périmètre de la clé.
* Une clé limitée à certains sites reste dans ce périmètre. `get_credits_organization` lui permet aussi de lire le solde agrégé de l’organisation. Les détails de consommation (`get_credit_usage`, `get_credit_usage_events`) exigent une clé globale ou un utilisateur avec accès à la facturation de l’organisation. Une appartenance limitée à un site/groupe ne suffit pas.
* Les **outils d’écriture** sont enregistrés pour les clés API et connexions par compte liées à une organisation. Chaque écriture par compte exige l’autorisation de catégorie du rôle (voir [Outils d’écriture](#write-tools)) ; les clés agissent comme administrateurs dans leur périmètre. Les validations et journaux d’audit sont identiques au tableau de bord.

> [!NOTE]
>
> Seuls les administrateurs d’organisation peuvent créer, modifier ou supprimer
> des clés. Avec un compte connecté, les outils suivent le rôle : un lecteur
> peut tout lire ci-dessous sauf les trois lectures d’administration globales
> (`get_groups`, `get_group_detail`, `get_user_by_email`) et les outils de
> consommation exigeant l’accès à la facturation de l’organisation. Il ne peut
> utiliser que les écritures ouvertes à tous les membres, comme
> `create_saved_view`.

## Outils disponibles

L’assistant les découvre automatiquement après connexion. La plupart correspondent à un point de terminaison de la [référence API](https://docs.athenahq.ai/fr/api-reference/introduction.md).

### Métriques

| Outil | Résultat |
| - | - |
| `get_share_of_voice_cumulative` | Part de voix face aux concurrents sur une période |
| `get_share_of_voice_time_series` | Évolution quotidienne de la part de voix |
| `get_citation_rate_cumulative` | Taux de citation (fréquence des liens vers vous) face aux concurrents |
| `get_citation_rate_time_series` | Évolution quotidienne du taux de citation |
| `get_mention_rate_cumulative` | Taux de mention de votre marque face aux concurrents |
| `get_mention_rate_time_series` | Évolution quotidienne du taux de mention |
| `get_position_cumulative` | Rang moyen dans les réponses IA sur une période |
| `get_position_time_series` | Évolution quotidienne du rang |
| `get_position_distribution` | Part des réponses où la marque est en haut, au milieu ou en bas du classement |
| `get_ai_search_value` | Valeur de recherche IA : marché du sujet, valeur captée, potentiel restant, couverture et détail par sujet |
| `get_shopping_metrics` | Shopping Insights : apparitions de produits dans les réponses d’achat IA, positions, prix et concurrents |

### Requêtes analytiques

Outils souples interrogeant le même entrepôt que le tableau de bord pour les questions non couvertes par les métriques prédéfinies.

| Outil | Résultat |
| - | - |
| `query_metrics` | Mesures agrégées (count, avg, sum, min, max) sur tout cube, regroupées selon ses dimensions autorisées, avec comparaison de périodes facultative |
| `query_rows` | Lignes individuelles (texte, identifiants, mentions) de tout cube, avec pagination par curseur |

### Caractéristiques de marque

Mots-clés de perception (comme « Abordable » ou « Assistance lente ») extraits des réponses. L’API et les outils les nomment attributs.

| Outil | Résultat |
| - | - |
| `get_attributes` | Caractéristiques suivies d’un site avec leurs ID |
| `get_attribute_metrics` | Nombre de réponses mentionnant chaque caractéristique sur une période |
| `get_competitor_attribute_metrics` | Même répartition par concurrent suivi |
| `get_attribute_time_series` | Tendance quotidienne d’une caractéristique, marque et concurrents côte à côte |
| `get_attribute_observations` | Observations individuelles avec extrait et score de -1 à 1 |

### Prompts et réponses

| Outil | Résultat |
| - | - |
| `get_prompts` | Prompts suivis du site, avec volume, statut et géographie |
| `get_prompt_tags` | Étiquettes de prompts et nombre de prompts par étiquette |
| `get_personas` | Personas du site et nombre de prompts par persona |
| `get_topics` | Sujets actifs et nombre de prompts actifs par sujet |
| `get_responses` | Réponses IA, sources, sentiment et classement. `include_response: false` et `compact_sources: true` donnent un export léger par variante |
| `get_response_detail` | Une réponse avec sources, mentions et classement complets |
| `get_response_streaming_status` | État et progression en file de la dernière exécution de réponses, ou d’une exécution précise |

### Contenu

| Outil | Résultat |
| - | - |
| `get_tracked_content` | Contenus suivis avec citations, mentions et impressions |
| `list_content` | Tous les contenus, publiés ou non, avec les ID des prompts ciblés |
| `get_content_detail` | Contenu complet : brief, corps, URL citées, liens, statut et prompts visés |
| `get_content_citation_prompts` | Prompts dont les réponses IA ont cité un contenu donné |
| `get_content_hub_sheets` | Onglets Content Hub du site |
| `get_content_status` | Statut de génération normalisé (running / succeeded / failed) d’un contenu |
| `get_content_draft` | Brouillon actuel : corps d’article, brief, statut, dernière version |
| `get_content_versions` | Historique, du plus récent au plus ancien, avec libellés et auteurs |
| `get_content_version` | Texte intégral d’une version enregistrée |

Distinguez deux questions sur la même page. `get_content_detail` et `list_content` donnent les prompts **pour lesquels elle a été écrite** : son ciblage, avec les mêmes ID que `create_content`, issu de sa fiche et indépendant des réponses IA. `get_content_citation_prompts` donne ceux dont les réponses **ont cité** la page sur une période ; ce résultat est donc légitimement vide sans citation.

Le ciblage inclut les prompts supprimés ensuite, avec `status: "deleted"`, car la page a été écrite pour eux et Content Hub les conserve. `get_prompts` ne les liste pas ; un ID ciblé peut donc y être introuvable, raison pour laquelle `get_content_detail` inclut leur texte. Le ciblage est limité à 100 entrées par page (25 ID par ligne dans `list_content`), avec le total non tronqué dans `prompts_total` / `prompt_count`.

### Base de connaissances

Son activation pour l’organisation est requise ; sinon les outils renvoient une erreur explicative.

| Outil | Résultat |
| - | - |
| `search_brand_facts` | Recherche sémantique des faits approuvés, y compris sans pilier |
| `get_brand_facts` | Liste paginée filtrable par pilier, statut de révision, source et absence de classement |
| `get_pillars` | Piliers avec nombre de faits approuvés et disponibilité d’une synthèse |
| `get_pillar_document` | Document markdown de synthèse d’un pilier |

### Sources et concurrents

| Outil | Résultat |
| - | - |
| `get_sources` | Principaux domaines racines cités, classés Propriétaire / Concurrent / Partenaire / Tiers |
| `get_source_pages` | URL citées et métriques individuelles |
| `get_competitors` | Concurrents suivis du site |
| `get_identifiers` | Noms, alias et domaines comptant comme mentions de votre marque ou d’un concurrent |

### Prospection

| Outil | Action | Autorisation par compte |
| - | - | - |
| `list_outreach_contacts` | Contacts enregistrés avec auteur, e-mail, source et brouillon | Contenu : consultation |
| `find_outreach_author` | Trouve et conserve auteur et e-mail d’une page citée, ou page de contact du site | Contenu : écriture |
| `draft_outreach_message` | Rédige et conserve un message selon les instructions d’équipe | Contenu : écriture |
| `update_outreach_contact` | Modifie auteur, e-mail, LinkedIn ou brouillon | Contenu : écriture |
| `set_outreach_status` | Déplace les pages entre les statuts du pipeline | Contenu : écriture |

### Propositions

| Outil | Résultat |
| - | - |
| `list_pitches` | Rapports de proposition de l’organisation |
| `get_pitch` | Un rapport : concurrents, prompts, attributs, principales sources et métriques |

### Compte et configuration

| Outil | Résultat |
| - | - |
| `list_websites` | Sites accessibles et pays cible (`baseCountry`) |
| `get_groups` | Groupes de l’organisation (clé globale ou compte administrateur) |
| `get_group_detail` | Un groupe et ses sites membres (clé globale ou compte administrateur) |
| `get_user_by_email` | Recherche par e-mail, limitée à l’organisation de l’appelant (clé globale ou compte administrateur) |
| `get_date_range` | Première et dernière dates de réponse d’un site |
| `get_locations` | Emplacements configurés du site |
| `get_saved_views` | Préréglages de filtres du site |
| `get_group_saved_views` | Vues partagées d’un groupe |
| `get_credits_website` | Solde de crédits d’un site |
| `get_credits_organization` | Solde de l’organisation |
| `get_credit_usage` | Totaux de consommation, tranches temporelles et ventilation paginée des réserves débitées |
| `get_credit_usage_events` | Débits/remboursements paginés, actions enregistrées et attribution au site d’origine |

Les outils de consommation acceptent `website_id` pour identifier l’organisation, `range` facultatif (`24h`, `7d`, `30d`, `90d`, `all`) et une `window` UTC facultative avec `start_at_utc` et `end_at_utc`. Utilisez une fenêtre explicite pour un mois calendaire. Pour les pages suivantes, conservez la fenêtre renvoyée et utilisez `next_offset` ; 25 lignes par défaut, 50 maximum. `get_credit_usage_events` accepte aussi `originating_website_id` de la même organisation.

Les totaux couvrent toute la période ; les pages d’entités/événements peuvent être partielles. Les réserves de groupe débitées diffèrent des sites d’origine ; des crédits négatifs sont des remboursements et « Non enregistré » signifie une attribution historique indisponible. Ces outils MCP sont en lecture seule et n’ajoutent aucun point REST public.

### Découverte de prompts

| Outil | Action | Autorisation par compte |
| - | - | - |
| `start_prompt_discovery` | Lance une étude Discover asynchrone d’opportunités non suivies | Prompts : écriture |
| `find_more_prompt_discovery` | Lance une nouvelle série d’une étude terminée pour trouver plus de prompts | Prompts : écriture |
| `get_prompt_discovery_runs` | Lit l’historique visible ou la progression d’une exécution | Prompts : consultation |

Pour démarrer, fournissez `website_id`, `name` et au moins une source : `website_analysis`, `social`, `search_console`, `keyword_gaps`, `competitive_landscape`, `brand_guidelines`. Vous pouvez préciser `country`, `language`, `prompt_count_range` avec `min`/`max` et `custom_instructions`. Par défaut : locale `en-US`, États-Unis et cible de 25 à 50 prompts. Plages actuelles : 25–50, 50–75, 75–100, 100–150, 150–200. `brand_guidelines` exige des instructions non vides. Lacunes de mots-clés et Paysage concurrentiel conservent leurs restrictions d’offre. Ce dernier nécessite au moins un concurrent suivi et Search Console une intégration connectée pour fournir les données.

Vérifiez sources, locale, nombre souhaité et instructions avant lancement. Il utilise des services de recherche externes et des modèles IA. Le client MCP gère la confirmation d’appel ; la carte d’approbation de la conversation Athena n’est pas affichée via MCP. Le nombre est une cible, sans garantie ; la découverte n’ajoute pas automatiquement les prompts au suivi.

Le lancement renvoie `run_id` et `version`. Transmettez cet ID à `get_prompt_discovery_runs` pour interroger la même étude, sans en créer une seconde pour suivre sa progression. Sans `run_id`, l’outil renvoie l’historique récent. `limit` vaut 10 par défaut, 20 maximum. Statuts : `pending`, `running`, `completed`, `partial`, `failed`, `cancelled`. Les résultats incluent `progress_percentage`, la `phase` courante si disponible et `total_prompts`. Une exécution terminée fournit aussi `reason_code` (motif terminal ou code d’échec) et `reason` (explication montrable à l’utilisateur d’un résultat vide, court ou en échec, identique à Discover). Tous deux valent `null` sans explication nécessaire. `rounds` compte les séries poursuivies par `find_more_prompt_discovery` (1 sans poursuite) ; statut, progression et motif décrivent alors la dernière série, et `total_prompts` les additionne. `can_find_more` indique si une nouvelle série est possible ; `find_more_reason` explique sinon pourquoi. Examinez les candidats dans Discover de l’application. Ces outils n’envoient aucune notification et n’ajoutent pas de point REST public.

Pour poursuivre une étude terminée, passez son `run_id` (ou celui d’une série terminée qui la poursuit) à `find_more_prompt_discovery` avec `website_id`. La nouvelle série reprend sources, pays, langue, cible de nombre et instructions, exclut les questions déjà suggérées et lit des éléments encore inutilisés. Chaque série effectue la même recherche qu’une nouvelle étude : confirmez d’abord avec l’utilisateur. Une étude traite une série à la fois, au maximum deux après la première, et s’arrête plus tôt si une série trouve moins de dix nouveaux prompts ou rien de nouveau à lire ; l’outil renvoie alors une erreur motivée. La réponse donne les nouveaux `run_id` et `version`, à suivre avec `get_prompt_discovery_runs`.

### Diagnostics du site

| Outil | Résultat |
| - | - |
| `check_ai_access` | Règles robots.txt et réponses observées avec les agents utilisateurs des robots depuis le réseau Athena. `result.evidence` distingue résultats nullables par agent et recherche/entraînement ; tests échoués ou soumis à un défi signifient un accès indéterminé. Ne garantit ni accès réel, indexation ou citations. Journal de diagnostic pour l’hébergeur/CDN. Connexion par clé API uniquement. |

### Outils d’écriture

Disponibles par clé API et par compte lié à une organisation. Chaque outil suit l’autorisation de catégorie de votre rôle (dernière colonne) ; les clés agissent comme administrateurs dans leur périmètre. Chaque écriture est validée et consignée comme dans le tableau de bord.

Pour créer une étiquette de prompt, appelez `create_prompt_tag` avec `website_id` et `tag`. Le résultat contient `tag_id`. Les espaces périphériques du nom sont retirés ; une correspondance existante sans tenir compte de la casse renvoie `created: false`.

Avant de changer les attributions, appelez `get_prompts` avec le même `website_id` et trouvez le prompt par `id`. Son tableau `tags` contient les attributions `{ id, name }`. Construisez la liste complète `tag_ids` souhaitée : ajoutez le nouveau `tag_id`, ou retirez l’ID à désattribuer, en gardant tous les autres. Appelez `set_prompt_tags` avec `website_id`, son `prompt_id` et cette liste. Une liste vide efface toutes les étiquettes : ne la transmettez que si c’est votre intention. Répétez lecture et mise à jour pour chaque prompt.

Les identifiants sont les noms, alias et domaines recherchés dans les réponses pour compter les mentions. Avant modification, appelez `get_identifiers` avec `website_id` et, pour un concurrent, `competitor_id` issu de `get_competitors` (omettez-le pour votre marque). Les `default_identifiers`, nom et domaine, sont toujours recherchés et ne peuvent pas être retirés. Appelez ensuite `update_identifiers` avec les mêmes ID et listes `add`/`remove`. Les règles de Concurrents s’appliquent : valeur déjà présente ou déjà utilisée par une autre marque suivie du site refusée, sans enregistrement. Le changement s’applique immédiatement aux nouvelles réponses. L’historique n’est réanalysé que depuis Concurrents, moyennant crédits ; `changes_awaiting_backfill` compte les changements en attente.

Pour suivre de nouveaux concurrents, `add_competitors` accepte `website_id` et 1 à 25 `competitors`, chacun avec `name`, `url` (ou `no_website: true` sans site), plus `identifiers` et `additional_urls` facultatifs. Résultat individuel : `added` avec `competitor_id`, `already_tracked` si l’URL est déjà suivie (aucun changement) ou `rejected` avec `reason` (URL de vos domaines, limite de 500 concurrents par site, etc.). Pour arrêter le suivi, `remove_competitors` accepte jusqu’à 25 `competitor_ids` issus de `get_competitors` ; résultats `removed`, `no_change` (déjà retiré), `not_found`. Le retrait garde les mentions/citations passées et peut être annulé dans Concurrents. Aucun de ces outils ne réanalyse l’historique ni ne dépense de crédits ; cette réanalyse reste dans Concurrents.

| Outil | Action | Autorisation par compte |
| - | - | - |
| `create_prompts` | Crée des prompts avec sujets, étiquettes, personas et géographie | Prompts : écriture |
| `update_prompt` | Modifie texte, type, sujet ou géographie | Prompts : écriture |
| `create_prompt_tag` | Crée une étiquette ou renvoie celle de même nom, sans tenir compte de la casse | Prompts : écriture |
| `set_prompt_tags` | Remplace les attributions d’étiquettes ou les efface avec une liste vide | Prompts : écriture |
| `set_prompts_status` | Met plusieurs prompts en pause ou les réactive | Prompts : écriture |
| `delete_prompt` | Supprime un prompt, logiquement avec réponses, physiquement sinon | Prompts : écriture |
| `create_topic` | Crée un sujet ou renvoie celui de même nom | Prompts : écriture |
| `update_topic` | Modifie nom ou description d’un sujet | Prompts : écriture |
| `delete_topic` | Supprime un sujet, éventuellement ses prompts | Prompts : écriture |
| `create_location` | Crée un emplacement, éventuellement associé à des prompts | Prompts : écriture |
| `update_location` | Modifie un emplacement | Prompts : écriture |
| `delete_location` | Supprime un emplacement | Prompts : écriture |
| `update_identifiers` | Ajoute/retire des identifiants de marque ou concurrent, sans réanalyse ni crédits | Concurrents : écriture |
| `add_competitors` | Suit jusqu’à 25 nouveaux concurrents, résultat individuel, sans réanalyse ni crédits | Concurrents : écriture |
| `remove_competitors` | Arrête jusqu’à 25 suivis, résultat individuel, sans réanalyse ni crédits | Concurrents : écriture |
| `start_response_streaming` | Lance la collecte de réponses pour tous les prompts ou une sélection | Prompts : écriture |
| `start_prompt_discovery` | Lance Discover avec sources, locale et instructions facultatives | Prompts : écriture |
| `find_more_prompt_discovery` | Poursuit une étude Discover terminée en excluant les suggestions précédentes | Prompts : écriture |
| `create_content` | Lance la génération de brief ou article depuis un prompt ou sujet | Contenu : écriture |
| `add_content` | Ajoute un article déjà rédigé en brouillon modifiable, version 1, sans génération ni crédits | Contenu : écriture |
| `revise_brief` | Réécrit un brief selon une instruction, enregistré comme version | Contenu : écriture |
| `approve_brief` | Approuve un brief et lance l’article, avec crédits de contenu | Contenu : écriture |
| `revise_content` | Réécrit un brouillon selon une instruction, enregistré comme version | Contenu : écriture |
| `edit_content` | Applique des remplacements exacts déterministes sans IA, enregistrés comme version | Contenu : écriture |
| `restore_content_version` | Rétablit le texte d’une ancienne version comme brouillon courant, par ajout sans suppression | Contenu : écriture |
| `publish_content` | Marque un contenu en ligne à son URL pour lancer le suivi des citations | Contenu : écriture |
| `track_content_urls` | Enregistre des URL existantes ou tierces comme pages suivies, en lot, idempotent, sans crédits | Contenu : écriture |
| `rename_content` | Renomme une ligne de contenu | Contenu : écriture |
| `move_content` | Déplace entre feuilles, supprimant définitivement les valeurs de colonnes incompatibles | Contenu : écriture |
| `delete_content` | Supprime définitivement une ligne sans annulation | Contenu : écriture |
| `add_brand_facts` | Ajoute 1 à 50 faits par ingestion complète, avec résultat individuel | Connaissances de marque : écriture |
| `update_brand_fact` | Modifie texte, URL source ou confiance d’un fait | Connaissances de marque : écriture |
| `delete_brand_facts` | Supprime définitivement 1 à 50 faits ; ID absents signalés, sans erreur | Rôle administrateur |
| `create_pillar` | Crée un pilier ou renvoie celui de même nom | Connaissances de marque : écriture |
| `update_pillar` | Modifie nom/description, publie ou archive | Connaissances de marque : écriture |
| `delete_pillars` | Supprime définitivement 1 à 20 piliers et tous leurs faits, sans annulation | Rôle administrateur |
| `merge_pillars` | Fusionne les sources dans une cible publiée puis supprime les sources | Connaissances de marque : écriture |
| `move_brand_facts` | Classe 1 à 50 faits, même non classés, dans un pilier publié | Connaissances de marque : écriture |
| `create_saved_view` | Enregistre nom, icône facultative et objet `filters` jusqu’à 64 Ko, conservé tel quel | Tout membre |

`create_saved_view` est la seule écriture ouverte à tous les membres du site : les vues sont des préréglages personnels. Celles créées par compte sont attribuées à l’utilisateur ; celles par clé n’ont pas de propriétaire, sont signalées comme créées via API et seuls les administrateurs de site peuvent les modifier/supprimer dans le tableau de bord. `create_saved_view`, `move_content` et `add_content` sont les trois écritures sans équivalent REST.

`delete_brand_facts` et `delete_pillars` sont conditionnés au rôle lui-même plutôt qu’à une autorisation de catégorie : la suppression des connaissances est réservée aux administrateurs, comme dans le tableau de bord, et celle d’un pilier supprime tous ses faits. Un éditeur avec l’écriture sur les connaissances peut actualiser les faits, organiser et fusionner les piliers, mais pas supprimer. Les clés API disposent du rôle via leur périmètre administrateur.

## Exemples de prompts

Après connexion, essayez :

* « Quelle est ma part de voix dans les réponses IA par rapport aux concurrents suivis ce trimestre ? »
* « Quels domaines sont les plus cités pour mes prompts suivis ? »
* « Montre l’évolution de mon taux de citation sur les 90 derniers jours. »
* « Quelle est ma valeur captée en recherche IA et mon potentiel restant par sujet ? »
* « Récupère les réponses mentionnant ma marque et résume leur sentiment. »


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.