# Add-on MCP « SEO Insight »

Connecte ton agent IA (Cursor, Claude Code, VS Code, Windsurf, Claude Desktop…) directement à ton espace SEO Insight. Ton agent lit alors tes données au fil de la conversation, sans copier-coller : la checklist Website Specification, les audits de tes sites, et tes mots-clés / briefs.

---

## Ce que c'est

Le serveur MCP de SEO Insight expose tes données SEO à un client MCP (ton agent) en **lecture**, avec une seule action qui écrit (lancer un audit). Concrètement, ton agent peut :

- **Checklist Website Specification** — parcourir, chercher et lire les topics de la spec (foundations, SEO, accessibilité…). Contenu de référence, identique pour toutes les organisations.
- **Audit de site** — consulter la vue d'ensemble cross-sites, le détail du dernier audit d'un site, et **relancer un audit** (fetch réel de la surface publique du site : home, `robots.txt`, `sitemap`, `security.txt`, `llms.txt`).
- **Mots-clés & briefs** — récupérer les données de référence d'un mot-clé (volume, KD, CPC, top-10 SERP) et son brief YTG/Lumenia (grammages, entités, questions, intention).

Toutes les données renvoyées sont **limitées à l'organisation** de la clé API utilisée. Une clé ne voit jamais les données d'une autre organisation.

---

## Activation

L'add-on MCP est **inclus dès le plan Solo** — il s'active automatiquement dès qu'un plan payant a du quota MCP. Aucune option à acheter séparément.

### Créer une clé API

1. Ouvre **Réglages → Clés API**.
2. Clique **Créer une clé**, donne-lui un nom (ex. « Agent de production »).
3. **Copie la clé immédiatement** : elle commence par `eli_` et n'est affichée **qu'une seule fois**. Elle est stockée hashée (SHA-256) côté serveur — impossible de la retrouver ensuite.

Si tu perds une clé, révoque-la et crée-en une nouvelle.

---

## Connexion par client

L'URL du serveur et la clé sont les mêmes partout. Seul le format de configuration change selon le client.

- **URL du serveur** : `https://dash.seoinsight.app/api/mcp`
  (l'URL exacte de ton espace s'affiche dans **Réglages → Clés API**)
- **Authentification** : header `Authorization: Bearer <ta clé eli_…>`

### Cursor / Claude Code / VS Code / Windsurf (header natif)

Ces clients acceptent des headers HTTP. Ajoute ce bloc à leur configuration MCP :

```json
{
  "mcpServers": {
    "seo-insight": {
      "url": "https://dash.seoinsight.app/api/mcp",
      "headers": {
        "Authorization": "Bearer eli_ta_cle_ici"
      }
    }
  }
}
```

Emplacement de la config selon le client :

- **Cursor** — `~/.cursor/mcp.json` (ou Settings → MCP).
- **Claude Code** — `claude mcp add`, ou le bloc `mcpServers` de `~/.claude.json` / `.mcp.json` du projet.
- **VS Code** — le fichier `.vscode/mcp.json` du workspace (clé racine `servers`).
- **Windsurf** — `~/.codeium/windsurf/mcp_config.json`.

### Claude Desktop (contournement `mcp-remote`)

Claude Desktop ne sait pas encore envoyer un header d'authentification vers un serveur MCP distant. En attendant, on passe par le pont **`mcp-remote`**, qui injecte le header pour toi.

Dans le fichier de config de Claude Desktop
(`~/Library/Application Support/Claude/claude_desktop_config.json` sur macOS, `%APPDATA%\Claude\claude_desktop_config.json` sur Windows) :

```json
{
  "mcpServers": {
    "seo-insight": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://dash.seoinsight.app/api/mcp",
        "--header",
        "Authorization: Bearer eli_ta_cle_ici"
      ]
    }
  }
}
```

Redémarre Claude Desktop après modification. `npx` télécharge `mcp-remote` au premier lancement (Node.js requis).

> **OAuth natif à venir**
> La connexion en un clic depuis **claude.ai** et **ChatGPT** (OAuth natif, sans clé API ni pont `mcp-remote`) est prévue dans une prochaine version. En attendant, utilise la clé API + `mcp-remote` comme ci-dessus.

---

## Les 9 outils

Tous les outils sont en **lecture seule sauf `run_site_audit`**, qui est la seule action modifiant l'état (elle relance et remplace l'audit stocké du site).

| Outil | Ce que ça fait | Entrée |
| --- | --- | --- |
| `list_sites` | Liste les sites de l'organisation (id, nom, url). | — (aucune) |
| `audit_overview` | Vue d'ensemble cross-sites : pour chaque site, score du dernier audit, compteurs pass/fail/warn et date. | — (aucune) |
| `get_site_audit` | Dernier audit détaillé d'un site (verdicts par item + score). | `siteId` |
| `run_site_audit` ⚠️ | **Seule action qui modifie.** Relance un audit (fetch réel : home, `robots.txt`, `sitemap`, `security.txt`, `llms.txt`) et remplace l'audit stocké. | `siteId` |
| `list_spec_topics` | Liste les topics de la checklist Website Specification (id, titre, statut, catégorie, résumé). | `category` (optionnel) |
| `search_spec_topics` | Recherche full-text déterministe dans les topics de la spec (titre, slug, résumé, corps). | `query`, `limit` (optionnel, défaut 5, max 25) |
| `get_spec_topic` | Contenu markdown complet d'un topic de la spec. | `category`, `slug` |
| `get_keyword` | Données de référence d'un mot-clé : terme, pays, intention, métriques (volume/kd/cpc), top-10 SERP. | `id` **ou** `term` (au moins un) |
| `get_keyword_brief` | Brief YTG/Lumenia d'un mot-clé : grammages (topTerms, 2/3-grams), entités, questions, objectifs, intention. | `id` **ou** `term` (au moins un) |

### Cooldown de `run_site_audit`

`run_site_audit` a un **cooldown de 60 secondes**. Si le dernier audit du site date de moins de 60 s, l'outil **renvoie l'audit existant sans re-fetcher** le site (la réponse le signale). Utile pour vérifier une correction sans marteler le site. L'appel compte quand même dans ton quota MCP mensuel.

---

## Quota

Chaque plan inclut un quota de **requêtes MCP par mois** :

| Plan | Requêtes MCP / mois |
| --- | --- |
| Solo | 1 000 |
| Starter | 10 000 |
| Pro | 100 000 |
| Agency | 500 000 |

**Chaque requête MCP compte** — pas seulement les appels d'outils. L'ouverture de connexion, la négociation de session et le listing des outils par ton client consomment aussi du quota. Le compteur se remet à zéro chaque mois.

### Codes d'erreur

- **429 — Trop de requêtes** : tu as dépassé le débit autorisé (rate-limit à court terme, indépendant du quota mensuel). La réponse inclut un header `Retry-After` (en secondes). **Réessaie après ce délai** ; ton agent ralentit et repart.
- **403 — Quota épuisé** : ton quota MCP mensuel est atteint (ou l'add-on n'est pas activé). **Passe à un plan supérieur** ou attends la remise à zéro mensuelle.
- **401 — Clé manquante / invalide / révoquée** : vérifie le header `Authorization` et que la clé n'a pas été révoquée.

---

## Sécurité

- **Clé secrète, affichée une seule fois** : la clé complète (`eli_…`) n'apparaît qu'à la création. Elle est stockée hashée (SHA-256), jamais en clair. Traite-la comme un mot de passe.
- **Révocation immédiate** : depuis **Réglages → Clés API**, tu peux révoquer une clé à tout moment. Les agents qui l'utilisent perdent l'accès instantanément.
- **Portée limitée à l'organisation** : une clé ne donne accès qu'aux données de son organisation. L'org est résolue à partir de la clé validée côté serveur, jamais depuis les paramètres d'un outil — aucune fuite cross-org possible.
- **Une clé par usage** : crée une clé distincte par agent / environnement pour pouvoir en révoquer une sans impacter les autres.