Conectar agentes de IA à TrekMail via MCP

O servidor MCP da TrekMail permite que clientes de IA compatíveis gerenciem sua infraestrutura de email por meio de linguagem natural. O catálogo abrange domínios, caixas de email, identidade visual e equipes White Label, Drive, email, calendário, migrações, suporte, cobrança e serviços relacionados pela mesma API da TrekMail.

O catálogo completo não é carregado em todas as conversas. A TrekMail cria tools/list com base na credencial ativa: ferramentas fora dos escopos são omitidas, assim como aquelas excluídas por um conjunto de ferramentas selecionado, modo somente leitura, limites de transporte ou uma configuração de segurança local. Portanto, uma credencial de email com escopo restrito anuncia uma lista compacta de ferramentas de email.

Escolha como você quer se conectar

Os caminhos 1-3 usam OAuth 2.1: na primeira conexão, o navegador abre a página de consentimento da TrekMail, você analisa as permissões solicitadas e o cliente recebe um token limitado à sua conta. Nenhum token tm_live_ de longa duração é copiado para o cliente. Revogue qualquer conexão quando quiser em Agentes de IA e API → Tokens → Aplicativos conectados.

O que você recebe

• Um conjunto de ferramentas específico para a conexão, filtrado antes do registro conforme as permissões e configurações de segurança da conexão atual.
• OAuth 2.1 + registro dinâmico de cliente: seu cliente de IA registra a si mesmo, orienta você por uma página de consentimento no navegador e recebe um token com escopo. Não é preciso copiar e colar tokens de longa duração nos caminhos web, desktop ou CLI.
• Arquitetura de dois tokens: token de operações separado para infraestrutura e token de mensagens para todas as operações do webmail. Na conexão via OAuth, os tokens de mensagens são emitidos automaticamente por caixa conforme necessário.
• Idempotência automática nas operações que exigem esse recurso, para que uma nova tentativa não repita a mesma operação.
• Exclusão em duas etapas: excluir uma caixa exige intenção e confirmação explícitas; depois, a caixa é movida para Excluídos recentemente e pode ser recuperada.
• Controles de segurança para hospedagem própria: o administrador que executa o próprio servidor MCP stdio pode exigir aprovação para ações de exclusão, envio e migração.
• Registro de auditoria completo: todas as operações de API e MCP são registradas e mantidas por 90 dias.

Antes de começar

• Todos os planos podem conectar agentes.
  • Nano: ferramentas do Verificador de Email. Ao adicionar o Armazenamento do Drive, o agente também recebe os recursos do Drive aos quais a conta tem direito, incluindo navegação, upload, compartilhamento, restauração e exclusão definitiva.
  • Starter: Drive completo, Verificador de Email completo e acesso somente leitura nas demais áreas (domínios, caixas de email, migrações, tickets e outras). Use o painel para ações de gravação que o Starter não disponibiliza pela API, como criar migrações, responder a tickets ou alterar a resposta automática.
  • Pro / Agency: acesso completo de leitura e gravação em todas as famílias.
  • Avaliação ou add-on White Label: adiciona ferramentas de identidade visual, clientes/equipe e atividade enquanto o benefício estiver ativo. Sem ele, esses esquemas são omitidos. Durante a tolerância de cancelamento, apenas o proprietário recebe as ferramentas de leitura.
• É sua primeira vez? O botão Iniciar tour na página Agentes de IA e API apresenta a conexão de um agente, as etapas por cliente, tokens manuais, aplicativos conectados e o registro de auditoria.
• Nos caminhos OAuth (1, 2, 3), você não precisa criar um token manualmente. O cliente o cria pelo fluxo de autorização no navegador. No caminho stdio hospedado por você (4), primeiro crie um token tm_live_ no painel.

1. Cliente MCP remoto (recomendado)

Use este caminho quando seu cliente de IA oferecer suporte a servidores MCP remotos e autorização pelo navegador.

Atalho: a guia Conectar agente da página Agentes de IA e API pergunta qual cliente você usa e depois mostra o caminho exato desse cliente, o menu ou o arquivo de configuração e um trecho pronto com seu endereço já incluído. Se o cliente estiver na lista, siga essas instruções em vez das etapas genéricas abaixo.

1. Abra as configurações de MCP, integrações ou conectores no cliente.
2. Escolha Adicionar servidor MCP remoto ou Adicionar conector personalizado. O nome exato depende do cliente.
3. Informe:
   • Nome: TrekMail
   • URL do servidor MCP remoto: https://trekmail.net/mcp
4. Confirme a conexão. Seu navegador abre a página de autorização da TrekMail.
5. Entre na conta, analise as permissões solicitadas e aprove o acesso. Volte ao cliente quando o navegador confirmar a conexão.

A primeira autorização emite um token com prazo limitado. Clientes compatíveis o renovam automaticamente. Para desconectar, use a ação de desconexão do cliente ou revogue o aplicativo em Tokens → Aplicativos conectados na TrekMail.

2. Cliente CLI ou desktop

Para um cliente que aceita um comando stdio, use a ponte neutra abaixo:

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

Configure esse comando como servidor MCP no cliente. A primeira conexão abre seu navegador para autorização.

Alguns clientes também fornecem um comando próprio para adicionar um servidor MCP remoto. Essa opção também é válida: use https://trekmail.net/mcp como URL do servidor e siga as instruções do cliente.

Exemplo específico: Claude Code

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

Exemplo específico: Claude Desktop

Edite seu arquivo de configuração (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json) e adicione:

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

Reinicie o Claude Desktop. Na primeira vez que você mencionar a TrekMail em uma conversa, a janela do OAuth será aberta.

Exemplo específico: Cursor

O Cursor não tem uma tela para servidor remoto. Ele lê ~/.cursor/mcp.json (ou .cursor/mcp.json dentro de um projeto):

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

Exemplo específico: Windsurf

O Windsurf lê ~/.codeium/windsurf/mcp_config.json. Observe que a chave é serverUrl, e não url: um servidor remoto configurado com url é ignorado:

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

Salve o arquivo e reinicie o cliente para que ele carregue a alteração. A primeira conexão abre seu navegador para aprovar o acesso.

3. mcp-remote (CLI)

Útil para testes ou para clientes MCP que não são da Anthropic e ainda não oferecem suporte direto a servidores OAuth remotos, o mcp-remote é uma pequena ponte Node entre stdio e HTTP remoto.

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

A primeira execução abre o navegador para OAuth. Depois disso, o token fica armazenado em cache em ~/.mcp-auth/ e é usado automaticamente.

Você pode integrar essa opção a qualquer cliente MCP stdio apontando-o para o comando mcp-remote em vez de um ponto de entrada Node local.

4. Stdio com hospedagem própria (Claude Desktop / Docker / npm)

Se você prefere tokens tm_live_ estáticos em vez de OAuth, por exemplo para servidores autônomos, instâncias privadas da TrekMail ou implantações em contêiner, clone e execute o pacote MCP stdio em seu próprio host.

Primeiro, crie um token de API na página Agentes de IA e API → Tokens. Para ler e enviar emails, crie também um token de mensagens pela API usando seu token de operações. Consulte as instruções na guia Conectar agente.

Instalar o servidor MCP

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

Claude Desktop (stdio)

Adicione o conteúdo abaixo ao arquivo de configuração MCP do 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"
      }
    }
  }
}

Atualize o caminho em args para apontar para o local em que você clonou o repositório. Substitua os tokens pelos seus. Você pode omitir TREKMAIL_MESSAGE_TOKEN se precisar apenas das ferramentas de infraestrutura ou omitir TREKMAIL_API_TOKEN se precisar apenas das ferramentas de mensagens. É necessário fornecer pelo menos um token.

Claude Code (stdio)

Adicione isto às configurações MCP do Claude Code (.claude/settings.json ou configuração no nível do projeto):

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

Se você prefere Docker, crie a imagem do repositório e execute-a:

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 (desenvolvimento)

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

Variáveis de ambiente do stdio

Esses controles se aplicam somente ao processo MCP stdio com hospedagem própria que você executa. Eles não ativam nem desativam um recurso do produto TrekMail.

Ferramentas do Drive para agentes

Com um token de operações que inclua escopos do Drive, o servidor MCP fornece ferramentas para espaços, uso, navegação, uploads, arquivos, pastas, Lixeira, operações em massa, links públicos de compartilhamento, gerenciamento de senhas de dispositivos de sincronização e status do Drive Add-on. Sua conexão vê as ferramentas permitidas pelos escopos dela.

Para um agente exclusivo do Drive, defina TREKMAIL_API_TOKEN e conceda apenas os escopos necessários ao fluxo de trabalho. Se você executar stdio com hospedagem própria, mantenha as ações destrutivas desativadas, a menos que o agente esteja executando uma tarefa revisada de exclusão definitiva ou esvaziamento da lixeira. Compra, redimensionamento e cancelamento do Drive Add-on não são ferramentas MCP; os agentes podem consultar o status e os preços do add-on, mas alterações de cobrança permanecem no painel.

Consulte Visão geral das ferramentas MCP do Drive e Conectar agentes de IA ao TrekMail Drive.

Ferramentas disponíveis

O servidor MCP disponibiliza estas ferramentas aos agentes conectados. Elas são registradas condicionalmente conforme os tokens fornecidos.

As ferramentas que um agente realmente pode ver são determinadas por três fatores, todos aplicados antes da resposta de tools/list:

1. Os escopos do seu token. Uma ferramenta cuja capacidade não está presente no token nunca é registrada.
2. Controles de segurança locais do stdio. Quando você executa o servidor stdio com hospedagem própria, o administrador pode exigir aprovação para ações de gravação, envio ou migração. O MCP hospedado usa, em vez disso, os escopos aprovados durante o OAuth.
3. TREKMAIL_READ_ONLY=true, que remove todas as ferramentas de gravação, independentemente de escopos e sinalizadores.

Assim, uma conexão com hospedagem própria pode ser limitada intencionalmente mesmo quando o token tem escopos mais amplos. O MCP hospedado permanece limitado às permissões aprovadas durante o OAuth.

Ferramentas de domínio (token de operações)

Consulte Aliases de domínio via API e MCP para saber sobre o comportamento dos planos, estados de resposta, remoção segura e regras de roteamento somente para recebimento.

Ferramentas White Label (token de operações)

O conjunto white_label contém 20 ferramentas e só aparece quando o benefício da conta, a associação atual e os escopos da credencial permitem. A identidade visual é configurada por domínio; as demais ferramentas gerenciam configuração, clientes, acesso da equipe e atividade. É necessário ter o White Label ativo para gravar. Durante a tolerância de cancelamento, apenas o proprietário mantém as ferramentas de leitura.

Um agente pode executar toda a configuração da marca: definir a marca, copiar os dns_records retornados, publicá-los com apply_cloudflare_dns e então verificar e conferir o status. Chamadas que alteram o acesso são limitadas pela associação ativa e pelo limite de domínios do chamador, mesmo que o token tenha solicitado escopos mais amplos. Consulte o Guia de identidade visual White Label com API e MCP e Gerenciar equipes White Label com API e MCP.

Ferramentas de DNS (token de operações)

Ferramentas de caixa de email (token de operações)

Ferramentas de caixa compartilhada (token de operações)

Uma caixa compartilhada é uma caixa de entrada de equipe (support@, sales@) que os membros abrem pela própria conta de caixa comum no Webmail e, quando ativado, pelo acesso IMAP/SMTP nativo delegado. Ela não tem acesso direto por senha. O acesso é uniforme, todos podem ler e can_send é a única opção (pode responder ou é somente leitura). Não há funções de membro.

Ciclo de vida da caixa compartilhada (token de operações)

As três ferramentas de ciclo de vida e as três ferramentas de gravação de membros alteram o acesso. Um administrador de stdio hospedado localmente pode exigir TREKMAIL_ALLOW_DESTRUCTIVE=true antes que elas fiquem disponíveis; list_shared_mailbox_members é somente leitura e está sempre disponível.

Depois de criar, converter ou alterar uma associação, chame get_mail_client_setup com o ID de uma caixa de membro comum. Consulte shared_mailboxes.items[], aguarde native_access_ready=true e verifique send_as_ready antes de configurar o envio. A resposta fornece os caminhos exatos de Entrada/Enviados/Arquivo/Spam e os sinalizadores de operação; o SMTP não salva a cópia enviada da caixa compartilhada. Um erro repetível native_access_sync_failed ao remover ou atualizar uma permissão ou fazer uma conversão significa que o serviço manteve deliberadamente o estado anterior.

Ferramentas Sieve (token de operações)

Ferramentas de exclusão (token de operações)

Ferramentas de migração (token de operações)

Ferramentas de ticket (token de operações)

Ferramentas de SMTP/roteamento de domínio (token de operações)

O SMTP é configurado por domínio: cada domínio aponta para o envio gerenciado da plataforma ou para um perfil SMTP salvo (seu próprio provedor, reutilizável entre domínios), e um único padrão para toda a conta determina a configuração inicial dos novos domínios.

As ferramentas de gravação e teste acima alteram configurações ou fazem um teste de conexão. Um administrador de stdio hospedado localmente pode exigir TREKMAIL_ALLOW_DESTRUCTIVE=true antes que elas fiquem disponíveis; get_domain_smtp, list_domain_smtp_profiles, get_domain_smtp_test_status e get_account_smtp_default são somente leitura e estão sempre disponíveis.

Ferramentas SMTP legadas (obsoletas)

Essas ferramentas no nível da conta permanecem para compatibilidade com versões anteriores, mas não controlam mais o roteamento por domínio: use as ferramentas de roteamento de domínio acima.

Ferramentas de métricas de spam (token de operações)

Ferramentas de conta (token de operações)

Gerenciamento de tokens de mensagens (token de operações)

Ferramentas de mensagens (token de mensagens)

O token de mensagens libera 62 ferramentas que abrangem toda a interface do webmail, incluindo contas externas conectadas. As ferramentas são organizadas por área de recurso.

O OAuth hospedado e o stdio local identificam a caixa de formas diferentes. No MCP HTTP hospedado, todo esquema de ferramenta de mensagens inclui um mailbox_id obrigatório; o servidor o utiliza para emitir um token de curta duração para essa caixa. No MCP stdio local, TREKMAIL_MESSAGE_TOKEN já está vinculado a uma caixa, portanto as mesmas ferramentas não aceitam mailbox_id. Uma caixa de entrada conectada é um segundo nível de seleção: passe external_account_id além de mailbox_id no MCP hospedado ou além do token de mensagens vinculado no stdio.

Sete das 62 ferramentas de mensagens gerenciam contas conectadas, e cinco gerenciam identidades de remetente e a política de resposta. Use as duas famílias no fluxo semelhante ao Gmail em que um agente lê uma caixa conectada do Gmail, mas envia usando um endereço comercial autorizado por uma rota de domínio ou perfil SMTP salvo. Consulte Endereços Enviar como via API e MCP.

Mensagens principais

Se a caixa tiver um CC padrão ou CCO padrão definido em Configurações → Perfil, ele será adicionado ao que send_message e schedule_message envia, exatamente como no email escrito no aplicativo web; um endereço já presente na mensagem não é adicionado duas vezes. Passe apply_default_recipients: false para deixá-lo de fora de uma única mensagem. Isso não afeta emails enviados por um cliente de email no computador ou celular via SMTP, pois eles nunca passam pela API. | report_spam | Denunciar uma mensagem como spam, movê-la para Spam e treinar o filtro | | report_ham | Marcar uma mensagem em Spam como legítima, movê-la para Entrada e treinar o filtro | | bulk_action | Aplicar uma ação (ler, marcar com estrela, excluir, mover, spam) a até 50 mensagens de uma vez |

Pastas

Anexos

Rascunhos

Ambas retornam o uid e o uidvalidity do rascunho. Mantenha esse par unido: update_draft exige a época para que um UID antigo e reutilizado nunca possa excluir outra mensagem após a recriação da pasta Rascunhos. Um rascunho encontrado com list_messages deve ser aberto primeiro com read_message, que retorna seu uidvalidity atual. Uma atualização retorna um par novo, e o UID antigo deixa de funcionar. Em um servidor sem UIDPLUS, ambos os valores podem ser null mesmo que um novo rascunho tenha sido salvo; atualize a pasta Rascunhos e abra o rascunho antes de alterá-lo.

Ambas também aceitam um idempotency_key opcional. Se você não o informar, cada chamada será tratada como nova, então salvar o mesmo rascunho duas vezes criará dois rascunhos. Passe a mesma chave ao repetir uma chamada que talvez já tenha sido concluída, e você receberá o primeiro resultado em vez de uma duplicata.

Envio agendado

Contatos

Grupos de contatos

Calendário

Auxiliares de composição

Essas ferramentas preparam os dados para uma resposta ou encaminhamento. Elas não enviam nada. Passe os dados retornados diretamente para send_message ou save_draft.

Identidades (endereços de remetente)

Modelos

Remetentes bloqueados

Ferramentas do Verificador de Email (token de operações)

As ferramentas do Verificador de Email estão disponíveis em todos os planos, inclusive o Nano. A única limitação é seu saldo de créditos.

Ferramentas do Cloudflare (token de operações)

As ferramentas do Cloudflare estão disponíveis nos planos Pro e Agency.

Controles de segurança para stdio com hospedagem própria

Quando você executa o servidor MCP stdio por conta própria, TREKMAIL_ALLOW_DESTRUCTIVE controla se o processo local permite exclusões e outras ações de gravação. Defina-o como true apenas se confiar que o agente lidará corretamente com a exclusão de caixas. Essa configuração não altera a disponibilidade de recursos na TrekMail hospedada.

Mesmo com operações destrutivas ativadas, a exclusão sempre exige duas etapas, e o agente deve definir explicitamente confirm: true. Consulte Barreiras de segurança e intenções de exclusão para ver os detalhes.

Barreiras de segurança para envio

As ferramentas send_message e schedule_message têm duas barreiras de segurança independentes, e ambas precisam ser atendidas:

1. Barreira de ambiente: TREKMAIL_ALLOW_SENDING=true deve estar definido ao iniciar o servidor MCP.
2. Barreira por chamada: o agente deve passar confirm_send=true como parâmetro em cada chamada.

Esse projeto com duas barreiras evita o envio acidental de emails por um processo com hospedagem própria. Defina TREKMAIL_ALLOW_SENDING=false quando o agente só puder ler mensagens. list_scheduled funciona sem esse controle; ele se aplica apenas à criação ou ao envio de mensagens agendadas.

Barreiras de segurança para migrações

As ferramentas de gravação de migração (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) têm duas barreiras de segurança independentes:

1. Barreira de ambiente: TREKMAIL_ALLOW_MIGRATION=true deve estar definido ao iniciar o servidor MCP.
2. Barreira por chamada: cada ferramenta exige seu próprio parâmetro de confirmação (confirm_start=true, confirm_retry=true ou confirm_delete=true).

cancel_migration, cancel_bulk_migration e resume_bulk_migration estão sempre disponíveis, independentemente do controle de ambiente da hospedagem própria, porque são operações de segurança ou retomada. Elas ainda exigem parâmetros de confirmação por chamada.

As ferramentas de migração somente leitura (list_migrations, get_migration, list_bulk_migrations, get_bulk_migration) funcionam sem nenhuma barreira.

Soluções rápidas

• O agente não consegue se conectar: verifique se o caminho build/index.js está correto e se você executou npm run build depois de clonar.
• Erros "Missing bearer token": confira se pelo menos um entre TREKMAIL_API_TOKEN e TREKMAIL_MESSAGE_TOKEN está definido.
• As ferramentas somente leitura funcionam, mas a gravação falha: seu token está em um plano Starter. As gravações do Drive funcionam no Starter, com todos os recursos do Drive. Para outras gravações, provisionamento de caixas, início de migrações ou respostas a tickets, faça upgrade para o Pro ou use o painel.
• As ferramentas de exclusão retornam erros no stdio com hospedagem própria: defina TREKMAIL_ALLOW_DESTRUCTIVE=true no ambiente desse processo MCP. Isso se aplica a exclusões e outras ações de gravação, incluindo mensagens, pastas, contatos, calendário, identidades, modelos, remetentes bloqueados e mensagens agendadas.
• Uma ferramenta de envio do stdio com hospedagem própria retorna "Sending is disabled": defina TREKMAIL_ALLOW_SENDING=true no ambiente desse processo MCP.
• A ferramenta de envio retorna "Send not confirmed": o agente deve passar confirm_send=true em cada chamada de send_message ou schedule_message.
• Nenhuma ferramenta de mensagens aparece: verifique se TREKMAIL_MESSAGE_TOKEN está definido com um token tm_msg_ válido.
• As ferramentas de gravação de migração do stdio com hospedagem própria retornam erros: defina TREKMAIL_ALLOW_MIGRATION=true no ambiente desse processo MCP.
• Erro 503 ao iniciar uma migração: o servidor atingiu a capacidade de migrações. Tente novamente em alguns minutos.
• Falha ao baixar um anexo: os anexos são retornados como Base64. Anexos grandes, de até 25 MB, podem levar alguns segundos. download_all_attachments retorna um ZIP de todos os anexos codificado em Base64.
• O rascunho desapareceu após a atualização: update_draft exclui o rascunho antigo e acrescenta um substituto, então o rascunho recebe uma nova identidade UID. Use tanto uid quanto uidvalidity da resposta em qualquer operação posterior; o par informado anteriormente não identifica mais o substituto.
• Uma cópia de todas as mensagens chega a um endereço que você não informou: a caixa tem um CC padrão ou CCO padrão definido em Configurações → Perfil. Ele se aplica ao que essa caixa envia, inclusive pela API. Remova-o nessa tela ou passe apply_default_recipients: false para deixá-lo de fora de uma mensagem.
• Evento do calendário não encontrado: os eventos pertencem a uma caixa específica. Confirme se o token de mensagens foi emitido para a caixa correta.