Boîte mail pour Claude Code, Cursor et Windsurf via MCP

Un serveur, sept clients

Le serveur est un unique endpoint HTTPS qui parle le Model Context Protocol en Streamable HTTP : un POST portant du JSON-RPC, une réponse JSON, aucun flux maintenu ouvert. Il n’y a rien à installer, rien à exécuter en local et rien à quoi s’inscrire pour les domaines publics — l’URL est toute la configuration :

Endpoint MCPhttps://grabmail.io/mcpCopier

Chaque client MCP accepte un serveur HTTP distant, mais chacun garde sa configuration dans un fichier différent, avec un nom de clé légèrement différent. Les sections ci-dessous donnent la ligne exacte pour chacun. Les formats sont ceux en vigueur en septembre 2026 ; la documentation propre à chaque client fait référence si l’un d’eux a changé depuis.

Vérifiez qu’il répond, depuis un shell

Avant de toucher à un quelconque client, prouvez que le serveur est là et voyez ce qu’il propose. Comme le transport est du simple HTTP, un seul curl suffit :

$ curl -s -X POST https://grabmail.io/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

"create_inbox"
"list_domains"
"list_messages"
"read_message"
"wait_for_message"
"delete_message"

Si ça fonctionne, chaque client ci-dessous fonctionnera aussi, et un client qui échoue ensuite est un problème de configuration dans le client plutôt qu’un problème côté serveur. Si ça ne fonctionne pas, vérifiez que votre réseau autorise le HTTPS sortant vers grabmail.io — c’est toute son empreinte.

Claude Code

Une seule commande, depuis n’importe quel répertoire. Elle enregistre le serveur pour votre utilisateur, il est donc disponible dans chaque projet :

$ claude mcp add --transport http grabmail https://grabmail.io/mcp

Pour le partager avec une équipe via le dépôt à la place, limitez sa portée au projet. Cela écrit un .mcp.json à la racine, qui est versionné et que les coéquipiers sont invités à approuver :

$ claude mcp add --transport http --scope project grabmail https://grabmail.io/mcp

{
  "mcpServers": {
    "grabmail": {
      "type": "http",
      "url": "https://grabmail.io/mcp"
    }
  }
}

Redémarrez Claude Code, lancez /mcp, et grabmail apparaît avec ses six outils. Le serveur répond aussi à l’appel initialize du protocole par un court paragraphe d’instructions, que Claude Code transmet au modèle — l’agent arrive donc déjà en sachant qu’il doit donner l’alias et attendre sur l’adresse.

Claude Desktop

Les serveurs distants s’ajoutent via l’application plutôt que via le fichier de configuration :

1. Paramètres → Connectors → Add custom connector.
2. Collez https://grabmail.io/mcp comme URL, et donnez-lui un nom.
3. Démarrez une nouvelle conversation, et les outils apparaissent sous le connecteur.

Sur une version qui n’accepte que des serveurs locaux dans claude_desktop_config.json, reliez l’endpoint distant avec mcp-remote, qui s’exécute comme un processus local et redirige vers l’URL :

{
  "mcpServers": {
    "grabmail": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://grabmail.io/mcp"]
    }
  }
}

Cursor

Cursor lit .cursor/mcp.json dans le projet (ou ~/.cursor/mcp.json pour tous les projets). Un serveur distant est une url :

{
  "mcpServers": {
    "grabmail": {
      "url": "https://grabmail.io/mcp"
    }
  }
}

Ouvrez Cursor Settings → MCP pour le voir apparaître et activer ses outils. En mode Agent, le modèle les appelle de lui-même ; dans le chat, vous pouvez les demander par leur nom.

Windsurf

Windsurf conserve ses serveurs dans ~/.codeium/windsurf/mcp_config.json, et la clé pour un serveur distant est serverUrl plutôt que url — le seul endroit où la forme diffère :

{
  "mcpServers": {
    "grabmail": {
      "serverUrl": "https://grabmail.io/mcp"
    }
  }
}

Cascade liste le serveur après un rafraîchissement depuis le panneau MCP. On peut atteindre le même fichier depuis Windsurf Settings → Cascade → MCP servers → View raw config.

VS Code

Le mode agent de VS Code lit .vscode/mcp.json dans l’espace de travail, ou le fichier au niveau utilisateur qu’écrit MCP: Add Server dans la palette de commandes. Les serveurs se trouvent sous servers, pas mcpServers, et un serveur distant déclare son transport :

{
  "servers": {
    "grabmail": {
      "type": "http",
      "url": "https://grabmail.io/mcp"
    }
  }
}

Un petit lien « Start » apparaît au-dessus de l’entrée dans l’éditeur ; ensuite, les outils apparaissent dans le sélecteur d’outils du chat, et le mode agent les appelle sans qu’on le lui demande.

Codex CLI et Gemini CLI

Codex CLI garde sa configuration en TOML dans ~/.codex/config.toml. Un serveur distant est une table avec une url :

[mcp_servers.grabmail]
url = "https://grabmail.io/mcp"

Gemini CLI lit ~/.gemini/settings.json (ou .gemini/settings.json dans le projet), et la clé pour un serveur Streamable HTTP est httpUrl :

{
  "mcpServers": {
    "grabmail": {
      "httpUrl": "https://grabmail.io/mcp"
    }
  }
}

Une version de l’un ou l’autre qui n’accepte que des serveurs locaux peut atteindre l’endpoint via le même pont mcp-remote que celui montré pour Claude Desktop : command = "npx", args = ["-y", "mcp-remote", "https://grabmail.io/mcp"].

Les six outils

Quel que soit le client, le modèle voit les six mêmes outils, avec les mêmes noms. Il n’y a aucun état à gérer entre les appels, et aucun d’eux n’a besoin d’un argument que le précédent n’a pas renvoyé.

create_inbox

Invente une adresse fraîche et la renvoie avec son alias et un next_step précisant lequel utiliser où. Rien n’est réservé côté serveur, donc ça ne peut pas échouer. Prend un prefix lisible, optionnel.

wait_for_message

Bloque jusqu’à ce qu’un message arrive à l’adresse, pendant 25 secondes maximum, puis le renvoie en entier — sujet, expéditeur, texte brut, HTML. Filtrez avec subject_contains ou from_contains ; passez since_id pour ignorer ce qui était déjà là. Après une attente silencieuse, il répond timed_out et demande à être rappelé.

read_message

Un message en entier, par id. Rarement nécessaire, parce que l’attente renvoie déjà le message complet.

list_messages

Tout ce qui attend à une adresse, le plus récent en premier, immédiatement — y compris quand il n’y a rien.

list_domains

Les domaines publics que chacun peut utiliser, pour le cas où un formulaire vient d’en refuser un.

delete_message

Supprime un message maintenant plutôt que dans 5 jours. Idempotent, donc un agent qui réessaie ne coûte rien.

La boucle d’inscription en quatre appels

C’est la séquence dont presque toutes les tâches ont besoin, et le client ne la change pas :

1. create_inbox. Reviennent une adresse, un alias, et la note précisant lequel est lequel.
2. L’alias va dans le formulaire. Le site obtient une adresse fonctionnelle qui atteint la boîte et ne peut pas servir à l’ouvrir.
3. wait_for_message sur l’adresse, immédiatement après l’envoi, avec subject_contains réglé sur un mot que portera l’e-mail de confirmation. Ça bloque ; l’agent ne boucle pas.
4. Le code sort du message que l’attente a renvoyé. Il n’y a généralement plus aucun autre appel.

Sign up for a trial at https://app.example.com/signup with a fresh GrabMail inbox.
Use the ALIAS in the form, wait for the confirmation code with wait_for_message
on the ADDRESS, enter it, and tell me the resulting login.

Ce qu’il faut mettre dans les instructions propres à l’agent

Le serveur indique au modèle comment l’utiliser au moment de la connexion, mais un modèle qui a lu les quatre mêmes règles dans ses propres instructions de projet les suit à chaque fois plutôt que la plupart du temps. Ajoutez ceci à CLAUDE.md, .cursor/rules, .windsurfrules, AGENTS.md ou GEMINI.md — celui que lit votre client :

## Email

- To receive email, use the `grabmail` MCP server. Call `create_inbox` once per task.
- Put the **alias** it returns into forms; poll the **address** it returns with `wait_for_message`.
- Call `wait_for_message` right after submitting a form, with `subject_contains` set to a word
  you expect ("code", "verify", "confirm"). If it returns `timed_out`, call it again — up to
  three times — before concluding the mail was not sent.
- Never reuse an inbox across tasks. Never send anything confidential to one: it is public.

Les deux règles les plus importantes sont celles qu’un agent se trompe sans qu’on les lui dise : mettre l’alias dans le formulaire et interroger l’adresse, et traiter timed_out comme « rappeler », pas comme « le courrier n’a jamais été envoyé ». Une boîte qu’un agent IA peut lire détaille les deux en profondeur, y compris pourquoi l’attente se termine avant le courrier.

Quand ça ne fonctionne pas

Avant de considérer que c’est terminé

• Le curl ci-dessus liste six outils depuis votre machine.
• Le serveur apparaît dans le panneau MCP du client après un redémarrage, outils activés.
• Le paragraphe d’instructions se trouve dans le fichier que lit votre client.
• Un prompt de test a mené une inscription à bien : alias dans le formulaire, attente sur l’adresse, code récupéré.
• Rien de confidentiel ne sera jamais envoyé vers l’une de ces boîtes — elles sont publiques.

C’est toute la configuration. Le même serveur fonctionne depuis n’importe quel framework qui parle MCP, et pour les agents construits sans MCP — une simple fonction outil dans LangChain, l’OpenAI Agents SDK, ou votre propre boucle — l’e-mail pour les agents IA montre la version REST des quatre mêmes étapes.

Questions