Pidgeon

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

Un agente puede gestionar directamente una bandeja de entrada de Pidgeon: leerla, responder desde ella y crear direcciones en ella. Pidgeon habla Model Context Protocol a través de la misma API que describe esta documentación: un adaptador de protocolo y nada más.

Hay dos formas de conectarse, y ambas usan el mismo servidor. La versión alojada no requiere instalación; el paquete lo ejecuta en tu máquina.

Alojado, es decir, una URL

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

La primera llamada responde 401, y el cliente te lleva a Pidgeon para iniciar sesión. Eliges qué puede hacer —leer, leer y enviar, o acceso completo— y a qué puede acceder: una dirección o todas las direcciones si eres propietario de la cuenta. Esa elección se convierte en una clave de API, y el cliente conserva un token para ella. Aparece en Developers → API keys → Connected apps, y al desconectarla allí se termina la conexión en la siguiente llamada del cliente.

Los conectores personalizados de Claude, ChatGPT, Grok, Cursor, Codex y VS Code usan la misma URL y el mismo método de inicio de sesión. Cada solicitud se responde por separado: el servidor no mantiene ninguna sesión, porque no tiene estado propio que conservar.

Para un agente que no tenga a nadie disponible para iniciar sesión, envía una clave en su lugar:

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

x-api-key también funciona. Instrucciones paso a paso para Cursor, Codex (que lee TOML, no JSON) y VS Code; Windsurf y Gemini CLI usan la misma URL y el mismo encabezado.

En Grok

En Grok, ve a Connectors → Custom, pega https://pidgeon.ai/api/mcp e inicia sesión en la pantalla de consentimiento; no hace falta una clave (instrucciones paso a paso). Muse de Meta está en revisión con Meta.

En Cursor

Añade Pidgeon a Cursor desde su ficha en cursor.directory, que incluye el servidor alojado y la skill.

O añade el servidor manualmente en ~/.cursor/mcp.json (o en .cursor/mcp.json para un proyecto). Solo necesita la URL; Cursor te pedirá que inicies sesión en la primera llamada:

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

Para un agente que no tenga a nadie disponible para iniciar sesión, añade "headers": { "Authorization": "Bearer ${env:PIDGEON_API_KEY}" } junto a la URL, y Cursor lo completará a partir de tu entorno.

Codex, VS Code y Gemini CLI

Para Codex, VS Code y Gemini CLI, un comando escribe el servidor en el archivo propio del cliente:

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 no hay ninguna clave configurada, escribe solo la URL y el cliente te pedirá que inicies sesión. Si PIDGEON_API_KEY está configurada, primero comprueba la clave y luego hace que el cliente la lea de esa variable (Codex, Gemini CLI) o te la solicite una vez (VS Code), para que la clave nunca quede en el archivo. Añade contenido a lo que ya existe, incluidos los comentarios, hace una copia del archivo que modifica en <file>.bak, no hace nada la segunda vez y solo reemplaza una entrada pidgeon distinta si se usa --force. --scope user o --scope project selecciona el otro archivo; --print no escribe nada.

O instalado, es decir, un paquete

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

Comprueba la clave con la API antes de escribir nada e indica a qué direcciones puede acceder: la única pregunta que un bloque de JSON no puede responder y que, de otro modo, solo se manifiesta cuando un modelo recibe silenciosamente un error que nunca ves. Luego escribe .mcp.json en el directorio actual e imprime lo que escribió. Nunca reemplaza una entrada que ya esté ahí: --force lo hace, y --print muestra la configuración sin escribir nada, que es lo que necesitas si tu cliente guarda la suya en otro lugar.

La clave se referencia desde el entorno en lugar de escribirse en el archivo, así que puedes confirmar la configuración en el repositorio sin exponer la credencial:

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

Claude Desktop o cualquier otro cliente MCP usa el mismo bloque. Para ejecutar el servidor directamente, lo que resulta útil sobre todo para ver cómo se inicia:

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

PIDGEON_BASE_URL lo dirige a un entorno distinto del de producción, algo útil únicamente si ejecutas Pidgeon por tu cuenta.

La clave es todo el control de acceso

Esto entrega una clave de API a un modelo: una que creaste o que concediste al iniciar sesión. Nada en el paquete decide a qué se puede acceder: el límite propio de la clave y las direcciones que se le concedieron lo determinan todo, en el servidor, exactamente igual que para cualquier otro cliente. Aquí no hay un segundo conjunto de reglas que puedas configurar mal.

Así que dale la clave más limitada que necesite el agente. Una clave creada en read nunca podrá enviar, por generoso que sea el acceso que se le conceda a una bandeja de entrada; consulta Autenticación para saber qué implica el alcance de una clave y cómo limitarlo. Un agente que solo clasifica mensajes debería tener una clave que solo permita leer; así, la posibilidad de que envíe algo vergonzoso no dependerá de las instrucciones.

El alcance de una clave es una instantánea de las direcciones que se le concedieron, así que no incluye las direcciones creadas después de la clave.

Qué ofrece

Las 42 herramientas, leídas de la lista del propio servidor para que esta página no quede desactualizada:

Herramienta	Función	Endpoint
list_addresses	Las direcciones a las que puede acceder esta credencial.	GET /identities
create_address	Crear una dirección para que la use un agente.	POST /identities
get_address	Una dirección, por id.	GET /identities/{id}
list_threads	Conversaciones de una dirección, de la más reciente a la más antigua.	GET /threads
get_thread	Una conversación, por id.	GET /threads/{id}
list_messages	Los mensajes de una conversación, del más antiguo al más reciente: el texto que hay que leer antes de responder.	GET /messages
search_messages	Búsqueda de texto completo en todas las direcciones a las que puede acceder esta credencial, ordenada por relevancia.	GET /messages/search
send_message	Enviar desde una dirección desde la que esta credencial tenga permiso para enviar.	POST /messages
get_message	Un mensaje, por id, con su cuerpo, los encabezados que conservamos y lo que demostraron los registros del dominio remitente: authentication.spf\, .dkim\, .dmarc\; null significa que no se informó, no que falló.	GET /messages/{id}
await_message	Espera hasta que llegue un mensaje a una dirección —por ejemplo, después de enviar un formulario de registro— y lo devuelve con extracted.codes\ y extracted.links\: primero, los códigos de verificación y los enlaces de confirmación más probables.	GET /messages/await
reply_to_message	Los destinatarios, el asunto y el hilo se obtienen del mensaje al que se responde, así que tú solo aportas las palabras.	POST /messages/{id}/reply
forward_message	Reenvía un mensaje a alguien a quien no iba dirigido, con sus archivos adjuntos, desde la dirección que lo recibió.	POST /messages/{id}/forward
create_draft	Escribe un mensaje sin enviarlo, para que una persona lo lea y lo envíe; úsalo cuando te pidan preparar respuestas para su aprobación.	POST /drafts
get_draft_approval	Indica el estado de un envío retenido, según su draft\_id\: pending\ hasta que una persona lo apruebe o rechace en el panel; después, approved\ (se envió y message\_id\ es el mensaje), rejected\ o expired\ si nadie decide en 24 horas.	GET /drafts/{id}/approval
list_drafts	Todos los borradores de una dirección, del más reciente al más antiguo, con sus destinatarios y el cuerpo, para que puedas volver a uno y terminarlo.	GET /drafts
get_draft	Un borrador por id: remitente, destinatarios, asunto, texto y archivos adjuntos.	GET /drafts/{id}
update_draft	Cambia los campos que indiques y deja el resto como está; null\ borra el asunto o el texto.	PATCH /drafts/{id}
delete_draft	Elimina un borrador y cancela su envío si estaba programado.	DELETE /drafts/{id}
read_attachment	El texto de un archivo adjunto: un CSV, un registro, JSON, un archivo de calendario o un PDF, un documento de Word .docx\ o una hoja de cálculo de Excel .xlsx\.	GET /attachments/{id}/text
update_thread	Quién es responsable de una conversación y en qué estado está.	PATCH /threads/{id}
update_message	Destaca un mensaje o muévelo a archive\, spam\ o trash\.	PATCH /messages/{id}
list_send_rules	La lista de permitidos y bloqueados de una dirección, y la política de envío asociada.	GET /identities/{id}/send-rules
list_receive_rules	Las reglas que determinan qué llega a una dirección —rechazar, marcar como spam, enviar a la papelera, archivar o dejar en la bandeja de entrada, por remitente o dominio— y su receive\_policy\.	GET /identities/{id}/receive-rules
list_folders	Todas las carpetas de una dirección y sus recuentos.	GET /mailboxes
list_folder	Una carpeta de una dirección, de la más reciente a la más antigua, con una conversación por fila: donde list\_threads\ indica qué conversaciones existen, esto indica dónde están archivadas y cómo aparecen en una lista.	GET /mailboxes/{folder}
list_changes	Todo lo que se movió en una bandeja de entrada desde un sync\_cursor\, incluidas las llegadas, para que un agente de larga duración no tenga que volver a leer una carpeta para encontrar un mensaje nuevo.	GET /mailboxes/changes
list_events	Todos los eventos de todas las direcciones a las que puede acceder esta credencial: correo recibido, enviado, entregado, rebotado y archivado.	GET /events
list_labels	Las etiquetas pertenecen a una dirección, no al espacio de trabajo; por eso, el mismo nombre en tres direcciones corresponde a tres etiquetas con tres ids.	GET /labels
create_label	Una etiqueta de una dirección.	POST /labels
apply_label	La etiqueta debe pertenecer a la misma dirección que la conversación; list\_labels\ de esa dirección te da el id correcto.	POST /threads/{id}/labels
remove_label	Quita una etiqueta de una conversación.	DELETE /threads/{id}/labels
list_pods	Un pod es un contenedor para uno de tus propios clientes: contiene direcciones y dominios, y **el correo enviado desde él tiene su propia reputación de envío**, para que un cliente no perjudique la entregabilidad de otro.	GET /pods
create_pod	Un contenedor para uno de tus clientes, con su propia reputación de envío.	POST /pods
get_metrics	Enviados, entregados, rebotados, rechazados, denunciados, recibidos y marcados como spam durante un período de days\: se cuentan a partir del registro de eventos, por lo que incluye resultados que el proveedor informó posteriormente.	GET /metrics
get_calendar	El calendario de una dirección, según la id\ de la dirección: su zona horaria predeterminada y cuántos eventos contiene.	GET /identities/{id}/calendar
update_calendar	La zona horaria que se asigna a un evento creado sin una, como un nombre IANA del tipo Europe/Lisbon\.	PATCH /identities/{id}/calendar
get_agenda	Lo que hay en el calendario de una dirección entre after\ y before\ (fechas y horas ISO 8601), ordenado por hora de inicio, con cada fecha de un evento recurrente en una fila propia.	GET /identities/{id}/calendar/agenda
get_calendar_event	Un evento por eventId\ en el calendario de la dirección id\: sus horarios, descripción, ubicación, recurrencia y asistentes con sus respuestas.	GET /identities/{id}/calendar/events/{eventId}
create_calendar_event	Añade un evento al calendario de la dirección id\.	POST /identities/{id}/calendar/events
update_calendar_event	Cambia un evento del calendario: modifica los campos que indiques y deja el resto como está.	PATCH /identities/{id}/calendar/events/{eventId}
delete_calendar_event	Elimina un evento del calendario de la dirección id\.	DELETE /identities/{id}/calendar/events/{eventId}
respond_to_invitation	Responde a una invitación a una reunión recibida por correo, usando el id\ del mensaje: accepted\, declined\ o tentative\, con un comment\ opcional.	POST /messages/{id}/invitation/respond

Cada herramienta corresponde al endpoint que aparece junto a ella en la referencia, con las mismas denegaciones. Si la clave no permite usar una herramienta, esta falla igual que la API, con el mensaje que habría devuelto la API.

La búsqueda abarca todas las direcciones a las que puede acceder la clave, salvo que indiques una, y cada resultado señala en qué dirección se encontró.

Lo que no es

No es un entorno de ejecución de agentes ni toma decisiones. Pidgeon no tiene ninguna preferencia sobre qué modelo ejecutas ni sobre lo que puede concluir; es la misma postura que adopta Threads and hand-off respecto al resto del producto. Si el agente se atasca, pasar la conversación a una persona es un estado del hilo, no una función de este paquete.