> Pour un agent : la carte de la documentation d'Escouade Mail est sur https://escouade.io/mail/docs/llms.txt ; chaque page existe en Markdown, à la même adresse suffixée `.md`.

# Connecteur pour assistants en ligne

> Le connecteur branche l'assistant d'un humain à son espace, sans clé à copier. Son adresse : `https://mail.escouade.io/mcp`. L'humain se connecte avec son compte Escouade, choisit son espace et autorise. Sans espace, il ouvre le sien sur la même page. C'est par là qu'il relit et valide les brouillons de son agent.

## Deux adresses, un seul serveur

| Adresse | Pour qui | Sans clé ni jeton |
|---|---|---|
| `https://api.subagent.fr/mcp` | Un agent, avec sa clé `sak_…` dans un en-tête. | Le serveur ne montre qu'un outil : `sign_up`. |
| `https://mail.escouade.io/mcp` | L'assistant en ligne d'un humain : Claude, ChatGPT, ou tout assistant qui branche un serveur MCP par OAuth. | Le serveur demande une connexion : l'assistant ouvre la page d'autorisation. |
| `https://api.subagent.fr/connect` | Les connecteurs branchés avant le 20 octobre 2026 : ils y restent, sans rien changer. | Le même parcours, au nom d'Escouade Mail. |

Les outils, leurs paramètres et leurs réponses sont les mêmes aux trois adresses.

## Avant de brancher

- **Il faut un compte Escouade**, à une adresse e-mail hors d'Escouade Mail. Un ancien utilisateur y entre avec la même adresse : il retrouve son espace.
- **Avec un espace vérifié**, l'humain le retrouve. C'est l'adresse que l'agent a donnée en `human_email`, et qui a reçu le code de vérification. Voir [Démarrer](https://escouade.io/mail/docs/demarrer.md).
- **Sans espace**, l'humain ouvre le sien sur la page de connexion. Il ne faut pas d'agent pour s'inscrire.

## Brancher son assistant

1. **Ajouter le connecteur.** Dans son assistant, l'humain ajoute un connecteur, ou serveur MCP distant, et colle l'adresse `https://mail.escouade.io/mcp`. Le geste exact dépend de l'assistant : [Claude](https://escouade.io/mail/docs/brancher/claude.md), [ChatGPT](https://escouade.io/mail/docs/brancher/chatgpt.md).
2. **Ouvrir la page d'Escouade Mail.** L'assistant ouvre une page d'Escouade Mail, sur `mail.escouade.io`.
3. **Se connecter avec son compte Escouade.** « Continuer avec Escouade » : le compte prouve l'adresse, une seule fois pour toutes les applications d'Escouade. C'est la connexion d'Escouade : Google et Microsoft ne la remplacent pas. En secours, si le compte ne répond pas par exemple, la page propose aussi l'adresse e-mail et un code à 6 chiffres (cinq essais, dix minutes) : l'e-mail s'ouvre dans le même navigateur, « Continuer la connexion ».
4. **Choisir l'espace et autoriser.** La page montre l'application qui demande l'accès, l'adresse où elle repart, l'espace concerné et ce que l'application pourra faire. L'humain autorise, ou refuse. Sans espace, il ouvre le sien : voir ci-dessous.

À savoir :

- **Par l'e-mail, la page répond la même chose à toute adresse**, qu'elle soit connue ou non. Un e-mail part à l'humain d'un espace vérifié. Il part aussi à une adresse sans espace, dans les limites des inscriptions, et jamais à une boîte d'Escouade Mail.
- **Le bouton de l'e-mail ne vaut que dans le navigateur qui a lancé la connexion.** Ouvert ailleurs, ou transféré à quelqu'un, il n'ouvre rien : il reste le code, à recopier sur la page.
- **Le navigateur est reconnu trente jours.** Une fois l'adresse prouvée, la connexion suivante dans ce navigateur s'ouvre directement à l'autorisation : les étapes 2 et 3 sautent. « Ce n'est pas votre adresse ? En changer », au bas de la page, l'oublie. Reconnaître un navigateur ne donne aucun accès : chaque application reste à autoriser.
- **La demande vaut 15 minutes.** Passé ce délai, il faut la relancer depuis l'assistant.
- **Le nom de l'application vient d'elle-même.** Seule l'adresse de retour dit où va l'accès. Quand cette adresse n'est pas celle d'un service reconnu, la page le dit.
- **Aucune clé n'est affichée ni copiée.** L'assistant reçoit des jetons, dont le serveur ne garde que l'empreinte.

## Ouvrir un espace sans agent

Quand l'adresse est prouvée et qu'aucun espace ne lui est rattaché, la page propose d'en ouvrir un.

1. **Choisir le nom de la première boîte.** La page en propose un, tiré de l'adresse de l'humain ; il peut le changer. L'adresse sera `nom@subagentmail.fr`. Le nom fait 3 à 32 caractères : minuscules, chiffres, point, tiret ou souligné.
2. **Lire ce que l'application pourra faire**, et l'adresse où elle repart.
3. **Choisir « Ouvrir mon espace et autoriser ».** L'espace s'ouvre et l'assistant y est branché, du même geste.

- **L'espace s'ouvre déjà vérifié** : l'adresse de l'humain vient d'être prouvée. Il n'y a pas de second code.
- **Il n'a pas de clé d'agent.** L'assistant y lit et y écrit par le connecteur, avec ce que l'humain a autorisé.
- **La boîte reçoit dès son ouverture.** Pour écrire à d'autres que l'humain, il faut un forfait : l'assistant en donne le lien, avec `subscribe`. Voir [Prix et paiement](https://escouade.io/offre).
- **Les contrôles sont ceux de `sign_up`** : le format du nom, les noms réservés, les noms déjà pris, les limites d'inscription. La page dit pourquoi un nom est refusé. Voir [Limites](https://escouade.io/mail/docs/limites.md#inscription).
- **Un agent qui travaille seul ouvre son propre espace**, avec `sign_up`, à l'adresse `https://api.subagent.fr/mcp`. Pour avoir un agent et valider depuis son assistant, l'humain laisse l'agent s'inscrire d'abord avec son e-mail, puis retrouve cet espace à la connexion.

## Ce que l'humain accorde

La page d'autorisation liste ce que l'application pourra faire, d'après les permissions qu'elle demande.

| Permission | Ce que la page en dit |
|---|---|
| `read` | Lire vos boîtes, vos fils et vos messages. |
| `send` | Écrire et répondre depuis vos boîtes, dans les règles d'envoi de l'espace. |
| `approve` | Valider ou annuler les brouillons en attente : ce que vous validez dans l'assistant part. |
| `manage_inboxes` | Créer et supprimer des boîtes. |

Un assistant qui ne demande rien de précis demande les quatre. Avec `approve`, l'humain valide les brouillons (`approve_message`), lève un blocage manuel (`remove_suppression`) et résilie le forfait (`cancel_subscription`). La clé de l'agent ne porte pas cette permission. Voir [Clés et permissions](https://escouade.io/mail/docs/cles.md#humain).

Dans le journal d'un message, l'accès de l'assistant porte le nom de l'application et l'e-mail de l'humain : « Claude (marie@exemple.fr) », par exemple.

## Retirer l'accès

L'accès dure tant que l'humain ne le retire pas. Pour y mettre fin, il déconnecte le connecteur dans son assistant. Rebrancher le même assistant reprend la même connexion, avec les permissions du nouveau consentement.

## Ce que dit le serveur à l'agent

Un agent n'a pas `approve`. Quand il laisse un brouillon, la réponse lui dit où son humain le valide :

```text
Brouillon msg_7f2a91c4e8b34d0fa6c25e1b9d3f7a48 dans le fil thr_0e5a7c2b9f1d48e6a3c7b5d0e2f9a814 : de agent@exemple.fr à nadia.morel@exemple.com, « Rendez-vous de jeudi ». Il attend une validation humaine : votre humain (m•••@exemple.fr) branche son assistant (Claude, ChatGPT…) à l’adresse https://mail.escouade.io/mcp, s’y connecte avec cet e-mail, puis relit le brouillon et le valide ou le corrige. Dites-le-lui : aucun avis ne lui est envoyé. Rien ne part avant.
```

Pour un agent :

- **Donnez cette adresse à votre humain**, pas la vôtre : `https://api.subagent.fr/mcp` est l'adresse des agents.
- **Ne lui demandez ni sa clé, ni son compte, ni son code de connexion.** Il se connecte sur la page d'Escouade Mail, pas dans la conversation.
- **Prévenez-le vous-même** qu'un brouillon attend : le serveur ne lui envoie aucun avis.

Le parcours complet : [Valider les envois d'un agent](https://escouade.io/mail/docs/guide-validation.md).

## Pour qui construit un client

| Sujet | Ce que fait le serveur |
|---|---|
| Protocole | OAuth 2.1, avec PKCE (`S256`) obligatoire. Les jetons sont opaques. |
| Découverte | Sans jeton, `https://mail.escouade.io/mcp` répond 401 avec l'adresse de la métadonnée de la ressource (RFC 9728) : `https://mail.escouade.io/.well-known/oauth-protected-resource/mcp`. Le serveur d'autorisation se décrit à `https://mail.escouade.io/.well-known/oauth-authorization-server` (RFC 8414). Chaque adresse a son émetteur : celle d'Escouade Mail, `https://mail.escouade.io` ; l'ancienne, `https://api.subagent.fr` (ressource `https://api.subagent.fr/connect`). Une ressource d'une adresse n'est pas reçue à l'autre. |
| Enregistrement | Dynamique (RFC 7591) : `https://mail.escouade.io/oauth/register`. |
| Autorisation et jetons | `https://mail.escouade.io/oauth/authorize`, `https://mail.escouade.io/oauth/token`. Types de demande : `authorization_code` et `refresh_token`. |
| Révocation | `https://mail.escouade.io/oauth/revoke` (RFC 7009). |
| Portées | `send`, `read`, `approve`, `manage_inboxes` : les permissions d'une clé. Voir [Clés et permissions](https://escouade.io/mail/docs/cles.md#permissions). |
| Durées | Un jeton d'accès vaut une heure. Un jeton de renouvellement vaut 30 jours. |

Le reste du protocole MCP est celui de `https://api.subagent.fr/mcp` : voir [Serveur MCP](https://escouade.io/mail/docs/mcp.md).