Conectar agentes de IA a TrekMail mediante MCP

Elegir y editar permisos de la aplicación

En la aprobación OAuth, elige Solo lectura o permisos individuales. Enviar y cambiar/eliminar mensajes son permisos separados. Leer mensajes incluye contactos, calendarios, plantillas y remitentes bloqueados; los permisos necesarios de cuenta y búsqueda de buzones se incluyen automáticamente. Para White Label, usa la dirección MCP de tu panel de marca.

Abre los detalles de una clave API o aplicación conectada, elige Editar acceso, revisa los cambios y confirma. La clave API conserva su secreto. Reducir permisos, recursos o caducidad también limita los tokens de buzón existentes y cancela envíos que no hayan empezado. Las conexiones OAuth nuevas pueden limitarse al instante; ampliar acceso requiere una nueva aprobación. Editar una conexión antigua la desconecta y guarda la selección para reconectar. Los tokens de mensajes solo permiten quitar permisos o acortar su duración.

Conectar desde el directorio de Claude

TrekMail está publicado como conector Community en el directorio de Claude.

Abre TrekMail en Claude, selecciona Connect, inicia sesión en TrekMail y aprueba los permisos que necesitas. No hace falta un token de API ni una URL de servidor personalizada.

Si tu espacio de trabajo de Claude restringe los conectores, pide al administrador que habilite TrekMail. Puedes revocar el acceso en TrekMail: AI Agents & API → Tokens → Connected apps.

Tu propia marca White Label: usa la dirección MCP de tu panel de marca y pon al conector el nombre de tu marca. Añádelo como custom connector; la página pública de TrekMail inicia sesión en TrekMail y no sustituye la conexión de tu marca.

Acciones disponibles: cada conexión respeta tu plan, tu rol y los permisos aprobados. La referencia de abajo también cubre la API general y el MCP local. En las conexiones del directorio, los ajustes de contraseñas y credenciales se abren en una página autenticada del panel mediante una herramienta get_*_setup_link; no envíes secretos por chat. Crear o sustituir una contraseña de aplicación en los perfiles de los directorios de ChatGPT/OpenAI y Claude devuelve un enlace seguro al panel en lugar del secreto. Las compras y los cambios de suscripción se hacen en el panel.

ChatGPT: hasta que esté disponible la instalación desde el directorio público, usa la conexión personalizada de la guía oficial. Activa Developer mode, añade la URL MCP de tu panel en Plugins y autentícate; después instala el plugin personal y úsalo en un chat Work. Las instrucciones de instalación pública se añadirán tras la publicación.

Primera consulta y solución de problemas

• Muestra mis dominios.
• Muestra los archivos de mi Drive.

Si Claude bloquea el conector, pide al administrador de tu espacio que lo habilite. ¿Cancelaste el inicio de sesión o revocaste el acceso? Abre de nuevo los pasos de conexión.

Otros métodos de conexión

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": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://trekmail.net/mcp"]
    }
  }
}

Reinicia Claude Desktop. Cuando se inicie el puente local, sigue la autorización en el navegador.

Ejemplo específico: Cursor

Configura Cursor con un archivo JSON:

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

Ejemplo específico: Windsurf

En Cascade, abre … → Open MCP config file y añade esta entrada. Esta configuración es para Cascade; otros agentes pueden usar otro archivo.

{
  "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)

Los buzones nuevos creados por agentes, incluidos los creados en bloque y mediante invitaciones, siguen Configuración de la cuenta > Buzones nuevos > Las apps de correo necesitan contraseñas de aplicación, activado por defecto. Cambiar este ajuste no modifica los buzones existentes. Las contraseñas de aplicación son para las apps de correo; los tokens de la API de mensajes siguen funcionando de forma independiente. Para los permisos, la entrega de contraseñas y los cambios de modo, consulta Contraseñas de aplicación por API y MCP.

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 64 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 64 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

send_message responde en cuanto el mensaje se acepta, antes de que se envíe realmente, así que comprueba que salió con get_message_delivery; un error sending_limit_exceeded indica qué límite se alcanzó y cuándo se renueva (resets_at), y el agente no debe volver a intentarlo antes de esa hora. get_message_delivery funciona con cualquier token de mensajes del mismo buzón, no solo con el que envió el mensaje, así que los tokens de corta duración del MCP alojado, o un token renovado, pueden seguir consultando envíos anteriores; un request_id desconocido devuelve 404.

get_mailbox_sending_limits indica en remaining_today a cuántos destinatarios más puede enviar hoy este buzón. Cuando el límite más bajo es el total diario de la cuenta, limit_today es null, y remaining_today también lo es hasta que ese total se agota (entonces vale 0). Un token de operaciones consulta el total de la cuenta con get_sending_limits.

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.

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.
• La herramienta de envío devuelve sending_limit_exceeded: se agotó un límite de envío. El error indica cuál (dimension) y cuándo se renueva (resets_at); no vuelvas a intentarlo antes de esa hora. Si el límite es el número de destinatarios de un solo mensaje, divide el mensaje. get_mailbox_sending_limits muestra a cuántos destinatarios más puede enviar hoy el buzón; su remaining_today es null mientras el límite más bajo sea el total diario de la cuenta y quede parte de él, y un token de operaciones consulta ese total con get_sending_limits. Límites de envío de TrekMail según el plan explica cada límite. Un mensaje que send_message ya aceptó aún puede rechazarse al salir de la cola; en ese caso, get_message_delivery lo muestra como failed con los mismos detalles. Un mensaje cuyo envío falló (por un límite de envío, por ejemplo) puede enviarse de nuevo más tarde con el mismo contenido, porque la API ya no devuelve para ese envío la respuesta de aceptación anterior. Si reintentas un envío que sigue pendiente o que ya se entregó, recibes la respuesta original.
• 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.