# Brancher un agent IA

Un agent IA peut lire tes projets, tes déploiements, tes journaux de build et tes domaines, et préparer une mise en production. Deux façons de faire : l’[assistant de la console](/host/docs/guides/utiliser-l-assistant/), ou ton propre agent par le serveur MCP de Host.

## L’adresse du serveur

```text
https://app.hgdc.ch/host/mcp
```

La page **Clés d’API** de ton organisation la donne, avec les configurations prêtes à copier (encart **Connecter un agent IA**).

## Avec ton compte HGDC

Un agent qui sait se connecter (OAuth) ouvre une page HGDC : tu choisis l’organisation et l’accès, **lecture** ou **lecture et écriture**. Aucune clé à copier. Tu retires l’accès dans Account, **Applications connectées**.

## Avec une clé d’API

Crée une clé avec les seules portées utiles : `host:read` pour un agent qui lit, `host:deploy` pour qu’il puisse aussi mettre en production. Voir [Créer et révoquer une clé d’API](/host/docs/guides/cle-d-api/). Une clé de projet, posée dans un dépôt par l’app GitHub, n’ouvre pas le serveur MCP.

### Claude Code

```sh
claude mcp add --transport http host https://app.hgdc.ch/host/mcp --header "Authorization: Bearer hgdc_host_…"
```

### Cursor

Dans `.cursor/mcp.json` :

```json
{
  "mcpServers": {
    "host": {
      "url": "https://app.hgdc.ch/host/mcp",
      "headers": { "Authorization": "Bearer hgdc_host_…" }
    }
  }
}
```

### VS Code

Dans `.vscode/mcp.json`. VS Code te demande la clé une fois et la garde :

```json
{
  "inputs": [
    { "type": "promptString", "id": "host-key", "description": "Clé d'API Host", "password": true }
  ],
  "servers": {
    "host": {
      "type": "http",
      "url": "https://app.hgdc.ch/host/mcp",
      "headers": { "Authorization": "Bearer ${input:host-key}" }
    }
  }
}
```

## Ce que l’agent peut faire

| Outil                                                                                      | Portée de la clé |
| ------------------------------------------------------------------------------------------ | ---------------- |
| Lister les projets et les déploiements, lire un déploiement                                | `host:read`      |
| Lire le journal de build (si un admin l’a activé dans **Réglages**, section **Assistant**) | `host:read`      |
| Lister les domaines et leurs enregistrements DNS                                           | `host:read`      |
| Lister les noms des variables, jamais leurs valeurs                                        | `host:env_read`  |
| Redéployer, mettre en production, revenir en arrière, annuler un build                     | `host:deploy`    |
| Ajouter, vérifier, retirer un domaine                                                      | `host:domains`   |
| Supprimer une variable                                                                     | `host:env_write` |

Avec la connexion HGDC, l’accès **lecture** ouvre les outils de lecture, **lecture et écriture** ouvre tout.

L’agent ne voit que les outils que permet sa clé. Ceux qui changent la production sont annoncés à ton agent comme destructifs : il doit te demander avant de les lancer. Par MCP, il n’y a pas de carte **Confirmer** comme dans la console.

## Si ça ne marche pas

- **403 `insufficient_scope` sur le serveur MCP** : la connexion est valable, mais elle ne donne pas accès à Host (jeton sans portée de Host, ou clé de dépôt, qui n’ouvre pas le MCP). Reconnecte l’agent avec ton compte HGDC, ou crée une clé d’équipe. Quand la portée est connue, l’en-tête `WWW-Authenticate` la nomme.

## Bonnes pratiques

- Une clé par agent, avec un nom clair et une expiration courte pour un essai.
- Commence par `host:read`. Ajoute `host:deploy` quand tu lui fais confiance.
- Un journal de build peut contenir n’importe quel texte : c’est une donnée, pas une consigne pour l’agent.
- Une clé qui fuit : révoque-la dans **Clés d’API**. Elle est refusée tout de suite.