Conectar agentes de IA a TrekMail mediante MCP

El servidor MCP de TrekMail permite que los clientes de IA compatibles administren tu infraestructura de correo electrónico mediante lenguaje natural. Su catálogo abarca dominios, buzones, marca y equipos de White Label, Drive, correo electrónico, calendario, migraciones, soporte, facturación y servicios relacionados a través de la misma API de TrekMail.

El catálogo completo no se carga en todas las conversaciones. TrekMail crea tools/list a partir de la credencial activa: se omiten las herramientas ajenas a sus ámbitos, así como las excluidas por el conjunto de herramientas seleccionado, el modo de solo lectura, los límites de transporte o un ajuste de seguridad local. Por tanto, una credencial de correo con ámbitos limitados anuncia una lista compacta de herramientas de correo.

Elige cómo quieres conectarte

Las rutas 1 a 3 usan OAuth 2.1: la primera vez que te conectas, el navegador abre la página de consentimiento de TrekMail, revisas los permisos solicitados y el cliente obtiene un token limitado a tu cuenta. No se copia ningún token tm_live_ de larga duración en el cliente. Puedes revocar cualquier conexión en Agentes de IA y API → Tokens → Aplicaciones conectadas en cualquier momento.

Qué obtienes

• Un conjunto de herramientas específico de la conexión, filtrado antes del registro según los permisos y ajustes de seguridad de la conexión actual.
• OAuth 2.1 + registro dinámico de clientes: tu cliente de IA se registra, te guía por una página de consentimiento en el navegador y obtiene un token con ámbitos definidos. No es necesario copiar y pegar tokens de larga duración para las rutas web, de escritorio o CLI.
• Arquitectura de doble token: un token de operaciones separado para la infraestructura y otro de mensajes para todas las operaciones de webmail. Al conectarte mediante OAuth, los tokens de mensajes se generan automáticamente para cada buzón según sea necesario.
• Idempotencia automática en las operaciones que la requieren, para que un reintento no repita la misma operación.
• Eliminación en dos pasos: eliminar un buzón exige intención y confirmación explícitas; después, el buzón pasa a Eliminados recientemente para poder recuperarlo.
• Controles de seguridad para autoalojamiento: un administrador que ejecute su propio servidor MCP stdio puede exigir aprobación para acciones de eliminación, envío y migración.
• Registro de auditoría completo: todas las operaciones de API y MCP quedan registradas durante 90 días.

Antes de empezar

• Todos los planes pueden conectar agentes.
  • Nano: herramientas de Email Verifier. Añadir Drive Storage también proporciona al agente las capacidades de Drive que la cuenta tenga autorizadas, como explorar, cargar, compartir, restaurar y purgar.
  • Starter: Drive y Email Verifier completos, además de acceso de solo lectura al resto de áreas (dominios, buzones, migraciones, tickets y más). Usa el panel para las acciones de escritura que Starter no ofrece mediante API, como crear migraciones, responder tickets o cambiar la respuesta automática.
  • Pro / Agency: acceso completo de lectura y escritura en todas las familias.
  • Prueba o complemento White Label: añade herramientas de marca, clientes/equipos y actividad mientras el derecho esté activo. Sin él, se omiten esos esquemas. Durante el periodo de gracia tras cancelar, solo el propietario recibe las herramientas de lectura.
• ¿Es tu primera vez? El botón Iniciar recorrido de la página Agentes de IA y API explica cómo conectar un agente, los pasos para cada cliente, los tokens manuales, las aplicaciones conectadas y el registro de auditoría.
• Para las rutas OAuth (1, 2, 3) no necesitas crear un token manualmente. El cliente lo crea mediante el flujo de autorización del navegador. Para la ruta stdio autoalojada (4), crea primero un token tm_live_ en el panel.

1. Cliente MCP remoto (recomendado)

Usa esta ruta cuando tu cliente de IA admita servidores MCP remotos y autorización mediante navegador.

Atajo: la pestaña Conectar agente de la página Agentes de IA y API pregunta qué cliente usas y luego muestra la ruta exacta de ese cliente, la ruta del menú o el archivo de configuración, junto con un fragmento listo para usar que ya incluye tu dirección. Si tu cliente aparece allí, sigue esas instrucciones en lugar de los pasos genéricos que figuran a continuación.

1. Abre los ajustes de MCP, integraciones o conectores en tu cliente.
2. Elige Añadir servidor MCP remoto o Añadir conector personalizado. La etiqueta exacta depende del cliente.
3. Introduce:
   • Nombre: TrekMail
   • URL del servidor MCP remoto: https://trekmail.net/mcp
4. Confirma la conexión. El navegador abrirá la página de autorización de TrekMail.
5. Inicia sesión, revisa los permisos solicitados y aprueba el acceso. Vuelve al cliente cuando el navegador confirme la conexión.

La primera autorización emite un token de duración limitada. Los clientes compatibles lo renuevan automáticamente. Para desconectarte, usa la acción de desconexión del cliente o revoca la aplicación desde Tokens → Aplicaciones conectadas en TrekMail.

2. Cliente CLI o de escritorio

Para un cliente que acepte un comando stdio, usa el siguiente puente independiente del cliente:

npx -y mcp-remote https://trekmail.net/mcp

Configura ese comando como servidor MCP en tu cliente. La primera conexión abre el navegador para la autorización.

Algunos clientes también proporcionan su propio comando para añadir un servidor MCP remoto. Es igualmente válido; usa https://trekmail.net/mcp como URL del servidor y sigue las indicaciones del cliente.

Ejemplo específico: Claude Code

claude mcp add trekmail https://trekmail.net/mcp -t http

Ejemplo específico: Claude Desktop

Edita el archivo de configuración (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json) y añade:

{
  "mcpServers": {
    "trekmail": {
      "url": "https://trekmail.net/mcp",
      "transport": "http"
    }
  }
}

Reinicia Claude Desktop. La primera vez que menciones TrekMail en un chat, se abrirá la ventana emergente de OAuth.

Ejemplo específico: Cursor

Cursor no tiene una pantalla para servidores remotos. Lee ~/.cursor/mcp.json (o .cursor/mcp.json dentro de un proyecto):

{
  "mcpServers": {
    "trekmail": {
      "url": "https://trekmail.net/mcp"
    }
  }
}

Ejemplo específico: Windsurf

Windsurf lee ~/.codeium/windsurf/mcp_config.json. Ten en cuenta que la clave es serverUrl, no url: un servidor remoto configurado con url se ignora:

{
  "mcpServers": {
    "trekmail": {
      "serverUrl": "https://trekmail.net/mcp"
    }
  }
}

Guarda el archivo y reinicia el cliente para que detecte el cambio. La primera conexión abre el navegador para aprobar el acceso.

3. mcp-remote (CLI)

mcp-remote resulta útil para pruebas o para clientes MCP que no sean de Anthropic y todavía no admitan directamente servidores OAuth remotos. Es un pequeño puente de Node entre stdio y HTTP remoto.

npx -y mcp-remote https://trekmail.net/mcp

La primera ejecución abre el navegador para OAuth. Después, el token se almacena en caché en ~/.mcp-auth/ y se utiliza automáticamente.

Puedes conectarlo a cualquier cliente MCP stdio apuntándolo al comando mcp-remote en lugar de a un punto de entrada local de Node.

4. Stdio autoalojado (Claude Desktop / Docker / npm)

Si quieres usar tokens tm_live_ estáticos en lugar de OAuth (por ejemplo, para servidores sin supervisión, instancias privadas de TrekMail o despliegues en contenedores), clona y ejecuta el paquete MCP stdio en tu propio host.

Crea primero un token de API en la página Agentes de IA y API → Tokens. Para leer o enviar correo, crea también un token de mensajes mediante la API usando el token de operaciones (consulta las instrucciones de la pestaña Conectar agente).

Instalar el servidor MCP

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install
npm run build

Claude Desktop (stdio)

Añade lo siguiente al archivo de configuración MCP de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["./trekmail-mcp/build/index.js"],
      "env": {
        "TREKMAIL_BASE_URL": "https://trekmail.net",
        "TREKMAIL_API_TOKEN": "tm_live_your_token",
        "TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
        "TREKMAIL_ALLOW_SENDING": "false",
        "TREKMAIL_ALLOW_MIGRATION": "false"
      }
    }
  }
}

Actualiza la ruta de args para que apunte al lugar donde clonaste el repositorio. Sustituye los tokens por los tuyos. Puedes omitir TREKMAIL_MESSAGE_TOKEN si solo necesitas herramientas de infraestructura, u omitir TREKMAIL_API_TOKEN si solo necesitas herramientas de mensajes. Se requiere al menos un token.

Claude Code (stdio)

Añade lo siguiente a los ajustes MCP de Claude Code (.claude/settings.json o la configuración del proyecto):

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["./trekmail-mcp/build/index.js"],
      "env": {
        "TREKMAIL_BASE_URL": "https://trekmail.net",
        "TREKMAIL_API_TOKEN": "tm_live_your_token",
        "TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
        "TREKMAIL_ALLOW_SENDING": "false",
        "TREKMAIL_ALLOW_MIGRATION": "false"
      }
    }
  }
}

Docker

Si prefieres Docker, crea la imagen desde el repositorio y ejecútala:

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
docker build -t trekmail-mcp .

docker run -i \
  -e TREKMAIL_BASE_URL=https://trekmail.net \
  -e TREKMAIL_API_TOKEN=tm_live_your_token \
  -e TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
  -e TREKMAIL_ALLOW_SENDING=false \
  -e TREKMAIL_ALLOW_MIGRATION=false \
  trekmail-mcp

npm local (desarrollo)

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install && npm run build

TREKMAIL_BASE_URL=https://trekmail.net \
TREKMAIL_API_TOKEN=tm_live_your_token \
TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
TREKMAIL_ALLOW_SENDING=false \
TREKMAIL_ALLOW_MIGRATION=false \
npm start

Variables de entorno de stdio

Estos controles se aplican únicamente al proceso MCP stdio autoalojado que ejecutas. No activan ni desactivan ninguna función del producto TrekMail.

Herramientas de Drive para agentes

Con un token de operaciones que incluya ámbitos de Drive, el servidor MCP proporciona herramientas para espacios, uso, exploración, cargas, archivos, carpetas, Papelera, operaciones masivas, enlaces públicos para compartir, gestión de contraseñas de dispositivos de sincronización y estado del complemento Drive. La conexión muestra las herramientas que permiten sus ámbitos.

Para un agente dedicado exclusivamente a Drive, configura TREKMAIL_API_TOKEN y concede solo los ámbitos que necesite el flujo de trabajo. Si ejecutas stdio autoalojado, mantén desactivadas las acciones destructivas salvo que el agente ejecute una tarea revisada de purga o vaciado de papelera. Comprar, redimensionar y cancelar el complemento Drive no son herramientas MCP; los agentes pueden leer su estado y precio, pero los cambios de facturación permanecen en el panel.

Consulta Descripción general de las herramientas MCP de Drive y Conectar agentes de IA a TrekMail Drive.

Herramientas disponibles

El servidor MCP ofrece estas herramientas a los agentes conectados. Las herramientas se registran de forma condicional según los tokens proporcionados.

Las herramientas que un agente puede ver realmente dependen de tres factores, todos aplicados antes de que responda tools/list:

1. Los ámbitos de tu token. Nunca se registra una herramienta cuya capacidad no esté incluida en tu token.
2. Los controles de seguridad locales de stdio. Al ejecutar el servidor stdio autoalojado, su administrador puede exigir aprobación para acciones de escritura, envío o migración. En cambio, MCP alojado usa los ámbitos aprobados durante OAuth.
3. TREKMAIL_READ_ONLY=true, que elimina todas las herramientas de escritura sin importar los ámbitos ni los indicadores.

Así, una conexión autoalojada puede limitarse deliberadamente aunque su token tenga ámbitos más amplios. MCP alojado sigue limitado a los permisos aprobados durante OAuth.

Herramientas de dominio (token de operaciones)

Consulta Alias de dominio mediante API y MCP para conocer el comportamiento por plan, los estados de respuesta, la eliminación segura y las reglas de enrutamiento de solo recepción.

Herramientas de White Label (token de operaciones)

El conjunto de herramientas white_label contiene 20 herramientas y aparece únicamente cuando lo permiten el derecho de la cuenta, la membresía actual y los ámbitos de la credencial. La marca se configura por dominio; las demás herramientas administran la configuración, los clientes, el acceso del equipo y la actividad. Para escribir se requiere White Label activo. Durante el periodo de gracia de cancelación, solo el propietario conserva las herramientas de lectura.

Un agente puede ejecutar la configuración de marca de principio a fin: establecer la marca, copiar los dns_records devueltos, publicarlos con apply_cloudflare_dns y después verificar y consultar el estado. Las llamadas que cambian el acceso quedan limitadas por la membresía activa y el límite de dominios del solicitante, aunque el token haya pedido ámbitos más amplios. Consulta la Guía de API y MCP para la marca White Label y Administrar equipos de White Label con API y MCP.

Herramientas de DNS (token de operaciones)

Herramientas de buzón (token de operaciones)

Herramientas de buzones compartidos (token de operaciones)

Un buzón compartido es una bandeja de equipo (support@, sales@) que los miembros abren en Webmail mediante su propia cuenta de buzón normal y, si está habilitado, mediante acceso IMAP/SMTP nativo delegado. No permite iniciar sesión directamente con contraseña. El acceso es uniforme, todos pueden leer y can_send es el único control (con capacidad de respuesta o solo lectura). No hay roles de miembro.

Ciclo de vida de buzones compartidos (token de operaciones)

Las tres herramientas del ciclo de vida y las tres herramientas de escritura de miembros cambian el acceso. Un administrador de stdio alojado localmente puede exigir TREKMAIL_ALLOW_DESTRUCTIVE=true para que estén disponibles; list_shared_mailbox_members es de solo lectura y siempre está disponible.

Después de crear, convertir o cambiar la membresía, llama a get_mail_client_setup con el ID del buzón de un miembro normal. Lee shared_mailboxes.items[], espera a que native_access_ready=true y comprueba send_as_ready antes de configurar el envío. La respuesta proporciona las rutas exactas de Inbox/Sent/Archive/Junk y los indicadores de operación; SMTP no guarda la copia compartida en Sent. Un error reintentable native_access_sync_failed al eliminar o actualizar permisos o al convertir significa que el servicio conservó deliberadamente el estado anterior.

Herramientas de Sieve (token de operaciones)

Herramientas de eliminación (token de operaciones)

Herramientas de migración (token de operaciones)

Herramientas de tickets (token de operaciones)

Herramientas de SMTP/enrutamiento de dominio (token de operaciones)

SMTP se configura por dominio: cada dominio apunta al envío administrado de la plataforma o a un perfil SMTP guardado (tu propio proveedor, reutilizable en varios dominios), y un único valor predeterminado para toda la cuenta decide con qué comienzan los dominios nuevos.

Las herramientas de escritura y prueba anteriores cambian ajustes o realizan una prueba de conexión. Un administrador de stdio alojado localmente puede exigir TREKMAIL_ALLOW_DESTRUCTIVE=true para que estén disponibles; get_domain_smtp, list_domain_smtp_profiles, get_domain_smtp_test_status y get_account_smtp_default son de solo lectura y siempre están disponibles.

Herramientas SMTP heredadas (obsoletas)

Estas herramientas de cuenta se mantienen por compatibilidad con versiones anteriores, pero ya no controlan el enrutamiento por dominio: usa en su lugar las herramientas de enrutamiento de dominio anteriores.

Herramientas de métricas de spam (token de operaciones)

Herramientas de cuenta (token de operaciones)

Gestión de tokens de mensajes (token de operaciones)

Herramientas de mensajes (token de mensajes)

El token de mensajes habilita 62 herramientas que abarcan toda la superficie de webmail, incluidas las cuentas externas conectadas. Las herramientas se organizan por área funcional.

OAuth alojado y stdio local identifican el buzón de forma diferente. En MCP HTTP alojado, cada esquema de herramienta de mensajes incluye un mailbox_id obligatorio; el servidor lo usa para generar un token de corta duración para ese buzón. En MCP stdio local, TREKMAIL_MESSAGE_TOKEN ya está vinculado a un buzón, por lo que esas mismas herramientas no aceptan mailbox_id. Una bandeja conectada constituye un segundo nivel de selección: pasa external_account_id además de mailbox_id en MCP alojado, o además del token de mensajes vinculado en stdio.

Siete de las 62 herramientas de mensajes administran cuentas conectadas y cinco administran identidades de remitente y la política de respuesta. Usa ambas familias para el flujo de trabajo al estilo Gmail en el que un agente lee una bandeja de Gmail conectada, pero envía desde una dirección empresarial autorizada mediante una ruta de dominio o un perfil SMTP guardado. Consulta Direcciones Enviar como mediante API y MCP.

Mensajes principales

Si el buzón tiene un CC predeterminado o CCO predeterminado configurado en Ajustes → Perfil, se añade a lo que envían send_message y schedule_message, igual que con el correo escrito en la aplicación web; una dirección que ya figure en el mensaje no se añade dos veces. Pasa apply_default_recipients: false para omitirlo en un solo mensaje. Esto no afecta al correo enviado mediante un cliente de escritorio o teléfono por SMTP, que nunca pasa por la API. | report_spam | Marcar un mensaje como spam, moverlo a Correo no deseado y entrenar el filtro | | report_ham | Marcar un mensaje de Correo no deseado como legítimo, moverlo a Bandeja de entrada y entrenar el filtro | | bulk_action | Aplicar una acción (leer, destacar, eliminar, mover o marcar como spam) a un máximo de 50 mensajes a la vez |

Carpetas

Archivos adjuntos

Borradores

Ambas herramientas devuelven el uid y el uidvalidity del borrador. Conserva la pareja junta: update_draft necesita la época para impedir que un UID antiguo y reutilizado elimine otro mensaje después de recrear la carpeta Borradores. Un borrador encontrado con list_messages debe abrirse primero con read_message, que devuelve su uidvalidity actual. Una actualización devuelve una pareja nueva y el UID anterior deja de funcionar. En un servidor sin UIDPLUS, ambos valores pueden ser null aunque se haya guardado un borrador nuevo; actualiza Borradores y abre el borrador antes de modificarlo.

Ambas también aceptan un idempotency_key opcional. Si lo omites, cada llamada se trata como nueva, por lo que guardar dos veces el mismo borrador genera dos borradores. Pasa la misma clave al reintentar una llamada que quizá ya se haya completado y obtendrás el primer resultado en lugar de un duplicado.

Envío programado

Contactos

Grupos de contactos

Calendario

Ayudantes de redacción

Estas herramientas preparan los datos para responder o reenviar. No envían nada. Pasa los datos devueltos directamente a send_message o save_draft.

Identidades (direcciones remitentes)

Plantillas

Remitentes bloqueados

Herramientas de Email Verifier (token de operaciones)

Las herramientas de Email Verifier están disponibles en todos los planes, incluido Nano. La única limitación es tu saldo de créditos.

Herramientas de Cloudflare (token de operaciones)

Las herramientas de Cloudflare están disponibles en los planes Pro y Agency.

Controles de seguridad para stdio autoalojado

Cuando ejecutas personalmente el servidor MCP stdio, TREKMAIL_ALLOW_DESTRUCTIVE controla si ese proceso local permite eliminar y realizar otras acciones de escritura. Establécelo en true solo si confías en que el agente gestione la eliminación de buzones. Este ajuste no cambia la disponibilidad de funciones en TrekMail alojado.

Incluso con las operaciones destructivas habilitadas, la eliminación siempre requiere dos pasos y el agente debe establecer confirm: true de forma explícita. Consulta Medidas de seguridad e intenciones de eliminación para obtener más información.

Controles de seguridad para el envío

Las herramientas send_message y schedule_message tienen dos controles de seguridad independientes que deben superarse:

1. Control de entorno: debe establecerse TREKMAIL_ALLOW_SENDING=true al iniciar el servidor MCP.
2. Control por llamada: el agente debe pasar confirm_send=true como parámetro en cada llamada.

Este diseño de doble control impide envíos accidentales de correo desde un proceso autoalojado. Establece TREKMAIL_ALLOW_SENDING=false cuando el agente solo deba leer mensajes. list_scheduled funciona sin este control; solo se aplica a la creación o el envío de mensajes programados.

Controles de seguridad para migraciones

Las herramientas de escritura de migración (start_migration, retry_migration, delete_migration, delete_bulk_migration, update_bulk_migration_job_password, test_migration_connection, preview_bulk_migration, start_bulk_migration, retry_bulk_migration) tienen dos controles de seguridad independientes:

1. Control de entorno: debe establecerse TREKMAIL_ALLOW_MIGRATION=true al iniciar el servidor MCP.
2. Control por llamada: cada herramienta exige su propio parámetro de confirmación (confirm_start=true, confirm_retry=true o confirm_delete=true).

cancel_migration, cancel_bulk_migration y resume_bulk_migration siempre están disponibles independientemente del control de entorno autoalojado porque son operaciones de seguridad o reanudación. Aun así, requieren parámetros de confirmación por llamada.

Las herramientas de migración de solo lectura (list_migrations, get_migration, list_bulk_migrations, get_bulk_migration) funcionan sin ningún control.

Soluciones rápidas

• El agente no puede conectarse: comprueba que la ruta build/index.js sea correcta y que ejecutaste npm run build después de clonar.
• Errores de "Missing bearer token": comprueba que esté configurado al menos uno de TREKMAIL_API_TOKEN o TREKMAIL_MESSAGE_TOKEN.
• Las herramientas de solo lectura funcionan, pero las escrituras fallan: tu token pertenece a un plan Starter. Las escrituras de Drive funcionan en Starter (toda la superficie de Drive). Para otras escrituras, aprovisionar buzones, iniciar migraciones o responder tickets, cambia a Pro o usa el panel.
• Las herramientas de eliminación devuelven errores en stdio autoalojado: establece TREKMAIL_ALLOW_DESTRUCTIVE=true en el entorno de ese proceso MCP. Se aplica a la eliminación y otras acciones de escritura, incluidos mensajes, carpetas, contactos, calendario, identidades, plantillas, remitentes bloqueados y mensajes programados.
• Una herramienta de envío de stdio autoalojado devuelve "Sending is disabled": establece TREKMAIL_ALLOW_SENDING=true en el entorno de ese proceso MCP.
• La herramienta de envío devuelve "Send not confirmed": el agente debe pasar confirm_send=true en cada llamada a send_message o schedule_message.
• No aparecen herramientas de mensajes: comprueba que TREKMAIL_MESSAGE_TOKEN esté configurado con un token tm_msg_ válido.
• Las herramientas de escritura de migración de stdio autoalojado devuelven errores: establece TREKMAIL_ALLOW_MIGRATION=true en el entorno de ese proceso MCP.
• 503 al iniciar una migración: el servidor ha alcanzado su capacidad de migración. Vuelve a intentarlo en unos minutos.
• Falla la descarga de adjuntos: los adjuntos se devuelven como base64. Los adjuntos grandes (hasta 25 MB) pueden tardar unos segundos. download_all_attachments devuelve un ZIP codificado en base64 con todos los adjuntos.
• El borrador desapareció después de actualizarlo: update_draft elimina el borrador anterior y añade uno de sustitución, por lo que el borrador obtiene una identidad UID nueva. Usa tanto uid como uidvalidity de la respuesta para cualquier acción posterior; la pareja que pasaste ya no identifica el sustituto.
• Una copia de cada mensaje llega a un lugar que no indicaste: el buzón tiene un CC predeterminado o CCO predeterminado configurado en Ajustes → Perfil. Se aplica a lo que envía este buzón, incluso mediante la API. Bórralo allí o pasa apply_default_recipients: false para omitirlo en un mensaje.
• No se encuentra el evento del calendario: los eventos se limitan al buzón específico. Confirma que el token de mensajes se emitió para el buzón correcto.