Como um agente de IA envia e lê e-mail por MCP

Duas formas de conectar

O servidor hospedado em https://api.mepmail.dev/mcp fala Streamable HTTP e entra com OAuth, então nenhuma chave é colada na configuração do cliente.

O pacote npm @mepmail/mcp fala stdio e chega à sua instância com uma chave de equipe ou uma chave de agente, para clientes que iniciam servidores a partir de um arquivo de configuração.

Os nomes e o formato do resultado são iguais nos dois, então um prompt escrito para um funciona no outro; o servidor hospedado também expõe as ferramentas que gerenciam domínios, webhooks, templates e disparos.

Opção 1: o servidor hospedado, com OAuth

1. No Claude Code, rode o comando abaixo, depois use /mcp e escolha mepmail para entrar. Acrescente --scope user para valer em todos os projetos.
2. No Cursor, coloque a URL no .cursor/mcp.json do projeto ou no ~/.cursor/mcp.json, para todos os projetos.
3. No VS Code, coloque no .vscode/mcp.json com type http e a URL.
4. No Claude Desktop, adicione um conector personalizado em Configurações → Conectores, ou faça a ponte com o mcp-remote até o endpoint HTTP.
5. Na tela de consentimento, escolha a equipe em que o cliente pode agir e desmarque as permissões que você não quer conceder. Nada é copiado nem colado.

claude mcp add --transport http mepmail https://api.mepmail.dev/mcp

Opção 2: o pacote local

O pacote pede Node.js 20 ou mais novo e roda com npx, sem OAuth e sem etapa no navegador: o bloco de configuração é a instalação inteira.

Use MEPMAIL_API_KEY para as ferramentas de envio, uma chave de equipe que começa com ms_, e MEPMAIL_MAIL_TOKEN para as ferramentas de caixa, uma chave de agente que começa com mmb_ para uma caixa ou mmt_ para várias. Pelo menos uma das duas.

MEPMAIL_BASE_URL aponta para outra instância; sem ela, o pacote fala com o MepMail Cloud.

{
  "mcpServers": {
    "mepmail": {
      "command": "npx",
      "args": ["-y", "@mepmail/mcp"],
      "env": {
        "MEPMAIL_API_KEY": "ms_...",
        "MEPMAIL_MAIL_TOKEN": "mmb_..."
      }
    }
  }
}

Ler e responder mensagens

1. mailbox_list_accounts lista as caixas que a credencial alcança, com as permissões de cada uma.
2. mailbox_list_messages devolve uma página, da mais nova para a mais antiga: passe o nextCursor recebido como cursor até hasMore ser falso e filtre no servidor com query, from, subject, unread, after e before. Uma página curta nunca prova que uma mensagem não existe.
3. mailbox_read_message devolve cabeçalhos, texto, a revisão e os dados dos anexos.
4. mailbox_save_draft cria ou edita um rascunho em texto puro sem enviar, e mailbox_send_draft envia.
5. Sem a permissão de envio, mailbox_send_draft manda um pedido de aprovação para você, que fica esperando no painel.
6. No servidor hospedado, as mesmas ferramentas de caixa respondem em https://api.mepmail.dev/mcp/correio com uma chave de agente, sem OAuth.

Enviar e-mail transacional

send_email envia ou agenda uma mensagem, send_email_batch leva até 100 numa chamada, e update_email e cancel_email cuidam de uma mensagem agendada.

Para repetir um envio com segurança, passe um idempotency_key: mantenha a mesma chave e os mesmos argumentos ao repetir o mesmo envio, e use uma chave nova para uma operação nova. As chaves são da equipe e duram 24 horas, e uma repetição concluída devolve o resultado original.

O domínio de envio precisa estar verificado antes: um remetente não verificado falha em send_email do mesmo jeito que falha em POST /emails.

list_emails e get_email mostram o estado e o último evento, delivered, bounced ou complained.

Permissões, e por que o agente pede

Cada ferramenta exige um escopo, como emails:send, mail:read ou mail:draft. As permissões que você desmarca nunca são concedidas, e o cliente não vê as ferramentas correspondentes.

Enviar sem pedir é uma marcação separada: com o envio direto desligado, todo envio te manda um pedido de aprovação, e marcar caixas não liga isso sozinho.

As autorizações ficam em Configurações → Aplicativos conectados, onde você revoga as suas. A revogação vale na próxima renovação do token do cliente, em até uma hora, e quem sai da equipe perde o acesso na hora.

O resultado das ferramentas vem em um envelope untrusted_data: assuntos, remetentes e corpos foram escritos por terceiros, e o agente é instruído a tratá-los como dados, nunca como instruções.

As chamadas MCP dividem o limite por minuto da API.

Antes de apontar o agente para uma caixa real

1. Verifique o domínio de envio e leia os registros dele com get_domain antes de investigar qualquer outra coisa.
2. Crie a caixa e a chave de agente em Correio → Configurações → Agentes: mmb_ para uma caixa, mmt_ para várias.
3. Comece com leitura e rascunhos: o agente lê, prepara a resposta e pede sua aprovação antes de enviar.
4. Confira a autorização em Configurações → Aplicativos conectados e envie uma mensagem para o seu próprio endereço.
5. Mantenha o alcance nas caixas que você marcou: uma credencial de equipe só chega às caixas que mailbox_list_accounts devolve.