# Utiliser Gheima avec l'IA

> Connectez Claude, Cursor, VS Code ou tout client MCP à votre compte, et donnez la doc en Markdown aux agents de code.

Source: https://gheima.ma/fr/docs/ai-assistants

Gheima fonctionne avec les assistants IA et les agents de code de trois façons : un serveur MCP hébergé qui permet à un assistant de voir votre compte et d'agir dessus, chaque page de la doc en Markdown, et une CLI dont la sortie --json et les codes de sortie sont pensés pour les scripts.

### Connecter un assistant (MCP)

Ajoutez https://gheima.ma/mcp comme serveur MCP distant. La première fois, votre navigateur ouvre une connexion Gheima où vous choisissez lecture seule ou lecture et écriture. L'assistant reçoit une clé API limitée à ce choix. Elle apparaît dans Paramètres → Clés API sous le nom MCP: <nom de l'app>, et la révoquer déconnecte l'assistant.

```bash
claude mcp add --transport http gheima https://gheima.ma/mcp
```

Claude Code. Dans Claude sur le web ou sur ordinateur : Paramètres → Connecteurs → Ajouter un connecteur personnalisé, puis collez l'URL.

```json
{ "mcpServers": { "gheima": { "url": "https://gheima.ma/mcp" } } }
```

Cursor : ~/.cursor/mcp.json

```json
{ "servers": { "gheima": { "type": "http", "url": "https://gheima.ma/mcp" } } }
```

VS Code : .vscode/mcp.json

> Note: Seul un propriétaire ou un admin peut connecter un assistant, car la connexion crée une clé API.

### L'exécuter en local

Le même serveur tourne sur votre machine en stdio, avec la clé enregistrée par gheima login. Utilisez-le si vous voulez que l'assistant lise des identifiants, ce que le serveur hébergé ne fait jamais.

```json
{ "mcpServers": { "gheima": { "command": "npx", "args": ["-y", "@gheima/mcp"] } } }
```

> Note: En local, les outils qui modifient quelque chose sont refusés sauf si vous lancez le serveur avec GHEIMA_MCP_ALLOW_WRITES=1. Lire des identifiants (afficher le mot de passe d'une base, exécuter du SQL) demande aussi GHEIMA_MCP_ALLOW_SECRETS=1, et une confirmation à chaque appel.

### Ce que l'assistant peut faire

- Voir les services, les déploiements, les logs et les métriques, et expliquer un déploiement échoué.
- Déployer, redémarrer, mettre en pause, reprendre et dimensionner un service.
- Lister les bases de données, prendre des snapshots et parcourir les buckets.
- Consulter et lancer les tâches cron.
- Vérifier la consommation, la facture en cours, les domaines, les alertes et le journal d'audit.
- Atteindre toutes les autres opérations de l'API via un outil général. Supprimer, renouveler ou réinitialiser quoi que ce soit demande une confirmation explicite.

Le serveur propose aussi des prompts prêts à l'emploi (Pourquoi mon déploiement a échoué ?, Comment va mon service ?, Combien coûtera ce mois-ci ?) et sert cette doc à l'assistant, pour qu'il vérifie comment une chose fonctionne avant d'agir.

> Note: Tout ce que fait un assistant est enregistré dans le journal d'audit sous la surface MCP, pour distinguer ses actions des vôtres.

### La doc pour les modèles

- `/llms.txt`: Un index de toutes les pages de la doc, avec un résumé d'une ligne.
- `/llms-full.txt`: Toute la doc dans un seul fichier texte.
- `/docs/<page>.md`: N'importe quelle page de la doc en Markdown. Ajoutez /fr ou /ar avant /docs pour le français ou l'arabe.
- `Accept: text/markdown`: Demandez une page avec cet en-tête pour obtenir le même Markdown à son URL habituelle.
- `/api/v1/openapi.json`: La spécification OpenAPI 3.1 de l'API REST.

### Dire à votre agent de code comment vous déployez

Les agents de code lisent AGENTS.md à la racine d'un dépôt. gheima agents affiche une courte section Gheima pour ce fichier : le service vers lequel ce dossier se déploie, comment déployer et lire les logs, et les codes de sortie. Ajoutez --write pour l'ajouter à AGENTS.md. Elle est ajoutée une seule fois, entre des marqueurs, donc relancer la commande ne fait que la mettre à jour.

```bash
gheima link my-app
gheima agents --write
```

Lancez-la dans le dossier lié. Claude Code lit CLAUDE.md : ajoutez-y une ligne @AGENTS.md pour partager le même fichier.

### Découverte pour les agents

- `/.well-known/mcp/server-card.json`: Comment joindre le serveur MCP hébergé.
- `/.well-known/oauth-protected-resource`: Où un client MCP se connecte (RFC 9728).
- `/.well-known/api-catalog`: Des liens vers la spécification de l'API et sa doc (RFC 9727).
- `/.well-known/agent-skills/index.json`: Une compétence qui apprend à un agent de code à déployer sur Gheima.

---

All docs: https://gheima.ma/fr/docs.md