Pidgeon

npx add-mcp 'https://pidgeon.ai/api/mcp'

Un agent peut gérer directement une boîte de réception Pidgeon : la lire, y répondre, y créer des adresses. Pidgeon parle le Model Context Protocol via la même API que celle décrite dans cette documentation — un adaptateur de protocole, rien de plus.

Il existe deux façons de s’y connecter, et elles utilisent le même serveur. La version hébergée ne nécessite aucune installation ; le package l’exécute sur votre machine.

Hébergé, sous forme d’URL

claude mcp add --transport http pidgeon https://pidgeon.ai/api/mcp

Le premier appel répond 401, et le client vous redirige vers Pidgeon pour vous connecter. Vous choisissez ce qu’il peut faire — lire, lire et envoyer, ou accès complet — et ce à quoi il peut accéder : une seule adresse, ou toutes les adresses si vous possédez le compte. Ce choix devient une clé API, et le client conserve un jeton associé. Elle apparaît sous Developers → API keys → Connected apps, et la déconnexion à cet endroit prend effet au prochain appel du client.

Les connecteurs personnalisés de Claude, ChatGPT, Grok, Cursor, Codex et VS Code utilisent la même URL et la même méthode de connexion. Chaque requête reçoit une réponse indépendante : le serveur ne conserve aucune session, car il n’a pas d’état propre à maintenir.

Pour un agent sans personne pour se connecter, envoyez plutôt une clé :

claude mcp add --transport http pidgeon https://pidgeon.ai/api/mcp \
--header "Authorization: Bearer $PIDGEON_API_KEY"

x-api-key fonctionne aussi. Instructions détaillées pour Cursor, Codex (qui lit du TOML, pas du JSON) et VS Code ; Windsurf et Gemini CLI utilisent la même URL et le même en-tête.

Dans Grok

Dans Grok, accédez à Connectors → Custom, collez https://pidgeon.ai/api/mcp, puis connectez-vous sur l’écran de consentement ; aucune clé n’est nécessaire (instructions détaillées). Muse de Meta est en cours d’examen par Meta.

Dans Cursor

Ajouter Pidgeon à Cursor depuis sa fiche sur cursor.directory, qui fournit le serveur hébergé et la compétence.

Vous pouvez aussi ajouter le serveur manuellement, dans ~/.cursor/mcp.json (ou .cursor/mcp.json pour un seul projet). L’URL suffit ; Cursor vous connecte lors du premier appel :

{
"mcpServers": {
  "pidgeon": {
    "url": "https://pidgeon.ai/api/mcp"
  }
}
}

Pour un agent sans personne pour se connecter, ajoutez "headers": { "Authorization": "Bearer ${env:PIDGEON_API_KEY}" } à côté de l’URL, et Cursor le récupérera depuis votre environnement.

Codex, VS Code et Gemini CLI

Pour Codex, VS Code et Gemini CLI, une seule commande écrit le serveur dans le fichier propre au client :

npx -y @pidgeon-ai/mcp init --client codex    # ~/.codex/config.toml
npx -y @pidgeon-ai/mcp init --client vscode   # .vscode/mcp.json
npx -y @pidgeon-ai/mcp init --client gemini   # .gemini/settings.json

Si aucune clé n’est définie, la commande écrit uniquement l’URL, et le client vous connecte. Si PIDGEON_API_KEY est défini, elle vérifie d’abord la clé, puis demande au client de la lire depuis cette variable (Codex, Gemini CLI) ou de la demander une seule fois (VS Code), afin que la clé ne soit jamais enregistrée dans le fichier. Elle ajoute le contenu à l’existant, commentaires compris, copie tout fichier modifié vers <file>.bak, ne fait rien lors d’une deuxième exécution et ne remplace une entrée pidgeon différente qu’avec --force. --scope user ou --scope project sélectionne l’autre fichier ; --print n’écrit rien.

Ou installé, sous forme de package

PIDGEON_API_KEY=pgn_live_… npx -y @pidgeon-ai/mcp init

Cette commande vérifie la clé auprès de l’API avant d’écrire quoi que ce soit, et vous indique les adresses auxquelles elle donne accès — la seule question à laquelle un bloc de JSON ne peut pas répondre, et celle qui, autrement, se manifeste lorsqu’un modèle reçoit discrètement une erreur que vous ne voyez jamais. Elle écrit ensuite .mcp.json dans le répertoire courant et affiche ce qu’elle a écrit. Elle ne remplace jamais une entrée existante : --force s’en charge, et --print affiche la configuration sans rien écrire, ce qui est utile si votre client conserve la sienne ailleurs.

La clé est référencée depuis l’environnement au lieu d’être écrite dans le fichier ; la configuration peut donc être validée dans le dépôt sans que l’identifiant y soit exposé :

{
"mcpServers": {
  "pidgeon": {
    "command": "npx",
    "args": ["-y", "@pidgeon-ai/mcp"],
    "env": { "PIDGEON_API_KEY": "${PIDGEON_API_KEY}" }
  }
}
}

Claude Desktop, ou tout autre client MCP, utilise le même bloc. Pour exécuter directement le serveur, ce qui est surtout utile pour observer son démarrage :

PIDGEON_API_KEY=pgn_live_… npx -y @pidgeon-ai/mcp

PIDGEON_BASE_URL le dirige vers un environnement autre que la production, ce qui n’est utile que si vous exécutez Pidgeon vous-même.

La clé constitue l’intégralité du contrôle d’accès

Cela transmet une clé API à un modèle — une clé que vous avez créée ou que vous lui avez accordée en vous connectant. Rien dans le package ne décide de ce qui est accessible : les limites propres à la clé et les adresses auxquelles elle donne accès déterminent tout, côté serveur, exactement comme pour n’importe quel autre appelant. Il n’existe pas ici de deuxième ensemble de règles susceptible d’être mal configuré.

Donnez-lui donc la clé la plus limitée dont l’agent a besoin. Une clé créée à read ne peut jamais envoyer de messages, même si elle dispose d’un accès très large à une boîte de réception — consultez Authentification pour comprendre la portée d’une clé et savoir comment la restreindre. Un agent chargé uniquement du tri doit disposer d’une clé qui ne permet que la lecture ; ainsi, la question de savoir s’il pourrait envoyer quelque chose d’embarrassant ne dépend pas de l’invite.

La portée d’une clé est un instantané des adresses auxquelles elle a accès ; une adresse créée après la clé n’y figure donc pas.

Ce qu’il expose

Les 42 outils, lus depuis la liste du serveur lui-même afin que cette page ne puisse pas être en retard sur lui :

Outil	Fonction	Point de terminaison
list_addresses	Les adresses auxquelles cet identifiant peut accéder.	GET /identities
create_address	Créer une adresse qu’un agent pourra utiliser.	POST /identities
get_address	Une adresse, par identifiant.	GET /identities/{id}
list_threads	Les conversations d’une adresse, de la plus récente à la plus ancienne.	GET /threads
get_thread	Une conversation, par identifiant.	GET /threads/{id}
list_messages	Les messages d’une conversation, du plus ancien au plus récent — le texte à lire avant de répondre.	GET /messages
search_messages	Recherche en texte intégral dans toutes les adresses accessibles à cet identifiant, classée par pertinence.	GET /messages/search
send_message	Envoyer un message depuis une adresse pour laquelle cet identifiant dispose du droit d’envoi.	POST /messages
get_message	Un message, par identifiant, avec son corps, les en-têtes conservés et les preuves fournies par les enregistrements du domaine expéditeur — authentication.spf\, .dkim\, .dmarc\, où null signifie que l’information n’a pas été signalée, et non qu’elle a échoué.	GET /messages/{id}
await_message	Attend l’arrivée d’un message à une adresse — par exemple après l’envoi d’un formulaire d’inscription — puis le renvoie avec extracted.codes\ et extracted.links\ : les codes de vérification et les liens de confirmation apparaissent probablement en premier.	GET /messages/await
reply_to_message	Les destinataires, l’objet et le fil de discussion sont extraits du message auquel vous répondez ; vous n’avez donc qu’à fournir le texte.	POST /messages/{id}/reply
forward_message	Transférer un message à une personne à qui il n’était pas adressé, avec ses pièces jointes, depuis l’adresse qui l’a reçu.	POST /messages/{id}/forward
create_draft	Rédiger un message sans l’envoyer, pour qu’une personne le lise et l’envoie — à utiliser lorsqu’on vous demande de préparer des réponses pour approbation.	POST /drafts
get_draft_approval	État d’un envoi en attente, selon son draft\_id\ : pending\ jusqu’à ce qu’une personne l’approuve ou le rejette dans le tableau de bord, puis approved\ (il a été envoyé, et message\_id\ est le message), rejected\, ou expired\ après 24 heures sans décision.	GET /drafts/{id}/approval
list_drafts	Tous les brouillons d’une adresse, du plus récent au plus ancien, avec leurs destinataires et leur corps — pour pouvoir reprendre un brouillon et le terminer.	GET /drafts
get_draft	Un brouillon par identifiant : son expéditeur, ses destinataires, son objet, son texte et ses pièces jointes.	GET /drafts/{id}
update_draft	Modifie les champs transmis et laisse les autres inchangés ; null\ efface l’objet ou le texte.	PATCH /drafts/{id}
delete_draft	Supprime un brouillon et annule son envoi s’il était programmé.	DELETE /drafts/{id}
read_attachment	Le texte d’une pièce jointe — un CSV, un journal, du JSON, un fichier de calendrier ou un PDF, un document Word .docx\ ou un fichier Excel .xlsx\.	GET /attachments/{id}/text
update_thread	Qui est responsable d’une conversation et où elle en est.	PATCH /threads/{id}
update_message	Ajouter une étoile à un message ou le déplacer vers archive\, spam\ ou trash\.	PATCH /messages/{id}
list_send_rules	La liste d’autorisation et de blocage d’une adresse, ainsi que la politique d’envoi qui lui est associée.	GET /identities/{id}/send-rules
list_receive_rules	Les règles qui déterminent ce qui arrive à une adresse — rejet, spam, corbeille, archivage ou boîte de réception, par expéditeur ou par domaine — et son receive\_policy\.	GET /identities/{id}/receive-rules
list_folders	Tous les dossiers d’une adresse avec leur nombre d’éléments.	GET /mailboxes
list_folder	Un dossier d’une adresse, du plus récent au plus ancien, avec une conversation par ligne — là où list\_threads\ indique quelles conversations existent, celui-ci indique où elles sont classées et à quoi elles ressemblent dans une liste.	GET /mailboxes/{folder}
list_changes	Tout ce qui a changé dans une boîte de réception depuis un sync\_cursor\, y compris les nouveaux messages, afin qu’un agent de longue durée n’ait pas à relire un dossier pour trouver un seul nouveau message.	GET /mailboxes/changes
list_events	Tous les événements de toutes les adresses accessibles à cet identifiant — messages reçus, envoyés, distribués, rejetés ou classés.	GET /events
list_labels	Les libellés appartiennent à une adresse, et non à l’espace de travail ; un même nom sur trois adresses correspond donc à trois libellés avec trois identifiants.	GET /labels
create_label	Un libellé sur une adresse.	POST /labels
apply_label	Le libellé doit appartenir à la même adresse que la conversation — list\_labels\ pour cette adresse vous donne le bon identifiant.	POST /threads/{id}/labels
remove_label	Supprime un libellé d’une conversation.	DELETE /threads/{id}/labels
list_pods	Un pod est un conteneur pour l’un de vos propres clients : il regroupe des adresses et des domaines, et **les messages envoyés depuis celui-ci bénéficient de leur propre réputation d’expéditeur**, afin qu’un client ne puisse pas nuire à la délivrabilité d’un autre.	GET /pods
create_pod	Un conteneur pour l’un de vos clients, avec sa propre réputation d’expéditeur.	POST /pods
get_metrics	Messages envoyés, distribués, rejetés, refusés, signalés comme indésirables, reçus et classés comme spam sur une période de days\ — comptabilisés à partir du journal des événements, ce qui inclut les résultats signalés ultérieurement par le fournisseur.	GET /metrics
get_calendar	Le calendrier d’une adresse, selon le id\ de l’adresse : son fuseau horaire par défaut et le nombre d’événements qu’il contient.	GET /identities/{id}/calendar
update_calendar	Le fuseau horaire attribué à un événement créé sans fuseau horaire, sous la forme d’un nom IANA tel que Europe/Lisbon\.	PATCH /identities/{id}/calendar
get_agenda	Le contenu du calendrier d’une adresse entre after\ et before\ (dates-heures ISO 8601), dans l’ordre de début, avec chaque occurrence d’un événement récurrent affichée séparément.	GET /identities/{id}/calendar/agenda
get_calendar_event	Un événement par eventId\ dans le calendrier de l’adresse id\ : ses horaires, sa description, son lieu, sa récurrence et ses participants avec leurs réponses.	GET /identities/{id}/calendar/events/{eventId}
create_calendar_event	Ajoute un événement au calendrier de l’adresse id\.	POST /identities/{id}/calendar/events
update_calendar_event	Modifie un événement du calendrier : les champs transmis, en laissant les autres inchangés.	PATCH /identities/{id}/calendar/events/{eventId}
delete_calendar_event	Supprime un événement du calendrier de l’adresse id\.	DELETE /identities/{id}/calendar/events/{eventId}
respond_to_invitation	Répond à une invitation à une réunion reçue par e-mail, à partir du id\ du message : accepted\, declined\ ou tentative\, avec un comment\ facultatif.	POST /messages/{id}/invitation/respond

Chacun correspond au point de terminaison indiqué à côté dans la référence, avec les mêmes refus. Un outil interdit par la clé échoue comme l’API, avec la phrase que l’API aurait utilisée.

La recherche couvre toutes les adresses accessibles à la clé, sauf si vous en indiquez une ; chaque résultat précise l’adresse dans laquelle il a été trouvé.

Ce que ce n’est pas

Ce n’est pas un environnement d’exécution d’agent, et il ne prend aucune décision. Pidgeon n’a pas d’avis sur le modèle que vous exécutez ni sur ce qu’il est autorisé à conclure — c’est la même position que celle adoptée par Threads and hand-off pour le reste du produit. Si l’agent est bloqué, transmettre la conversation à une personne relève du statut du fil de discussion, et non d’une fonctionnalité de ce package.