# Connecter Ondes PRO à JetBrains AI Assistant

> Ajoutez le serveur MCP d’Ondes PRO à AI Assistant dans IntelliJ IDEA, PyCharm, PhpStorm ou WebStorm : réglage MCP, clé API et ce que JetBrains documente ou non.

Mis à jour le 2026-10-21 · L’équipe Ondes PRO · https://ondes.pro/fr/integrations/mcp/clients/jetbrains

Dans les IDE JetBrains — IntelliJ IDEA, PyCharm, PhpStorm, WebStorm et les autres —, c’est **AI Assistant** qui utilise les serveurs MCP. Il accepte un serveur distant déclaré par son adresse. Cette page vous donne la configuration pour votre espace Ondes PRO, et vous dit honnêtement quelle partie est documentée par JetBrains et quelle partie ne l’est pas encore.

## Ajouter le serveur MCP d’Ondes PRO dans AI Assistant

Il vous faut un IDE JetBrains avec le plugin AI Assistant activé. Les intitulés ci-dessous sont ceux de la version anglaise des réglages, la plus répandue.

1. **Ouvrez les réglages MCP d’AI Assistant** — Dans **Settings**, allez dans **Tools → AI Assistant → Model Context Protocol (MCP)**.
2. **Ajoutez un serveur par sa configuration JSON** — Cliquez sur **Add** et choisissez la saisie en JSON. La forme que JetBrains documente pour un serveur distant tient en une adresse :

```json
{
  "mcpServers": {
    "ondes": { "url": "https://votre-espace.ondes.pro/mcp/" }
  }
}
```
3. **Choisissez votre mode d’authentification** — Si votre version d’AI Assistant ouvre d’elle-même une fenêtre de votre espace Ondes PRO pour autoriser la connexion, la forme ci-dessus suffit. Sinon, ajoutez l’en-tête `Authorization` avec une clé API, comme dans la configuration plus bas.
4. **Appliquez et vérifiez l’état** — Validez les réglages : le serveur `ondes` apparaît dans la liste avec son état. Une fois connecté, ses huit outils sont disponibles dans le chat d’AI Assistant.
5. **Interrogez votre espace depuis l’IDE** — Dans le chat d’AI Assistant, demandez par exemple « Quelles actions propose la ressource des factures ? ». L’assistant appelle les outils du serveur pour répondre.

## Configuration par clé API pour AI Assistant

C’est la voie la plus sûre de fonctionner aujourd’hui avec AI Assistant. Créez une clé dans **API & Développeurs → Clés API** ; donnez-lui les seules portées utiles, la lecture de la facturation par exemple.

Où se règle la connexion : Réglages → Tools → AI Assistant → Model Context Protocol (MCP).

**Connexion par clé API** (Configuration JSON)

```json
{
  "mcpServers": {
    "ondes": {
      "url": "https://votre-espace.ondes.pro/mcp/",
      "headers": {
        "Authorization": "ApiKey opk_…"
      }
    }
  }
}
```

_Compatible MCP standard. Documentation de l’éditeur : https://www.jetbrains.com/help/ai-assistant/mcp.html_

> **Ce que JetBrains documente, et ce qu’il ne documente pas** — Au 21 octobre 2026, la documentation d’AI Assistant décrit la déclaration d’un serveur distant par son `url`, mais **ni l’envoi d’en-têtes `headers`, ni l’autorisation OAuth** pour un tel serveur. La forme avec `headers` ci-dessus est celle de la configuration MCP standard, reprise par d’autres éditeurs ; elle est proposée en repli, sans promesse. Si elle n’est pas prise en compte par votre version, référez-vous à la documentation de JetBrains, qui évolue vite. Et si vous passez par un pont local du type `mcp-remote`, utilisez une version corrigée de la faille CVE-2025-6514.

## Pourquoi une clé API restreinte convient bien à un IDE

Une connexion OAuth vaut votre identité complète dans Ondes PRO : tout ce que votre rôle permet, l’assistant le peut. Dans un IDE, où l’on travaille souvent sur une seule partie de l’intégration, une **clé à portées** est un bon réflexe : elle ne donne accès qu’aux modules et aux actions choisis — `billing:read` pour écrire un export comptable, par exemple — et n’atteint jamais plus que les droits de son porteur.

La clé ne s’affiche qu’une fois à sa création. Elle peut être suspendue ou révoquée à tout moment depuis votre espace, et ses appels sont journalisés. Son quota par minute se règle à la création. La page [sécurité du serveur MCP](https://ondes.pro/fr/integrations/mcp/securite) compare en détail les deux voies.

## Exemple : coder les retours clients sans inventer d’endpoint

_Exemple de conversation · données de démonstration (Atelier Lumen)_

> **Vous** : Dans `RetourService`, quand un retour est accepté, il faut annuler la facture correspondante. Quel appel à l’API Ondes PRO dois-je faire ?
>
> 🔧 `ondes_impossible` Une facture émise ne se supprime ni ne s’annule par l’API : on émet un avoir.
>
> 🔧 `ondes_ressource` Fiche `billing/factures` : action `avoir/` avec `motif` obligatoire, `nature` `total` ou `partiel`, et pour un partiel `montant_ht` et `taux_tva`.
>
> **Assistant** : On n’annule pas une facture émise : on émet un **avoir**. Pour un retour de deux lampes sur une facture plus large, c’est un avoir partiel. J’ai ajouté dans `RetourService` un appel `POST billing/factures/{id}/avoir/` avec `nature: partiel`, le montant HT des deux lampes et le motif « Retour client ». L’avoir recevra un numéro AV-2026-… et le cumul ne pourra jamais dépasser le TTC de la facture. Je n’ai rien émis depuis l’IDE : la facturation n’a pas de mode test, à vous de décider quand l’essayer.

## Ce qu’AI Assistant gagne avec le serveur Ondes PRO

- La documentation de **votre** espace, à jour à chaque appel, plutôt qu’un fichier copié dans le projet.
- Un garde-fou contre l’hallucination : `ondes_impossible` liste ce que l’API ne fait pas volontairement.
- Des fiches de ressources complètes : champs typés et obligatoires, filtres, tri, actions, permission exigée.
- Environ 2 700 tokens de contexte permanent seulement, contre quelque 44 000 pour l’ancien fichier de documentation.

## Pour aller plus loin

- [Facturation](https://ondes.pro/fr/integrations/mcp/modules/facturation) — Devis, factures, relances et avoirs préparés par votre assistant, dans le respect des règles de facturation.
- [Construire une intégration](https://ondes.pro/fr/integrations/mcp/guides/construire-une-integration) — Clés à portées, webhooks signés, idempotence et mode test pour un back-office qui ne crée jamais de doublon.
- [API REST v1](https://ondes.pro/fr/integrations/api-rest) — Environ 135 ressources REST, des clés à portées, un schéma OpenAPI et des webhooks signés.
- [Sécurité du serveur MCP](https://ondes.pro/fr/integrations/mcp/securite) — OAuth 2.1, jetons courts, révocation immédiate et garde-fous d’écriture : ce que votre DSI doit savoir.

## Questions fréquentes

### Où ajouter un serveur MCP dans un IDE JetBrains ?

Dans Settings → Tools → AI Assistant → Model Context Protocol (MCP), avec le bouton Add. Pour Ondes PRO, déclarez l’adresse `https://<votre-espace>.ondes.pro/mcp/` dans le champ `url`.

### AI Assistant gère-t-il la connexion OAuth avec Ondes PRO ?

JetBrains ne documente pas, à ce jour, l’autorisation OAuth pour un serveur MCP distant. Si votre version ouvre une fenêtre d’autorisation, la connexion devrait fonctionner ; sinon, utilisez une clé API dans l’en-tête `Authorization`.

### L’en-tête headers est-il pris en charge par AI Assistant ?

Il n’est pas décrit dans la documentation de JetBrains au 21 octobre 2026. Nous le proposons parce qu’il fait partie de la configuration MCP standard reprise par d’autres éditeurs, mais sans pouvoir le garantir pour AI Assistant.

### Quels IDE JetBrains sont concernés ?

Ceux qui proposent le plugin AI Assistant avec la prise en charge de MCP : IntelliJ IDEA, PyCharm, PhpStorm, WebStorm, entre autres. Le réglage se trouve au même endroit dans chacun.

### JetBrains AI Assistant est-il testé par l’équipe Ondes PRO ?

Non. AI Assistant implémente le protocole MCP standard que respecte notre serveur. Seul Claude a été vérifié de bout en bout par notre équipe ; pour AI Assistant, la partie authentification dépend de ce que votre version prend en charge.