MCP Agent Mail — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Identidades por agente com caixas de entrada e saída persistentes
Histórico de mensagens pesquisável (FTS5) entre todos os agentes
Reservas voluntárias de arquivos — reivindique um caminho, libere quando terminar
FastMCP somente HTTP (Streamable HTTP), disponível via Docker
Log de auditoria com hash encadeado para investigações forenses
Sem dependência de SaaS — roda na sua infraestrutura

Demo ao vivo

Como fica na prática

mcp-agent-mail.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

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

{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-agent-mail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-agent-mail",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-agent-mail": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "http://127.0.0.1:8765/mcp"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add mcp-agent-mail -- npx -y mcp-remote http://127.0.0.1:8765/mcp

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: MCP Agent Mail

Coordenar 3 sessões do Claude Code no mesmo monorepo sem conflitos de merge

👤 Equipes que executam sessões paralelas de agentes ⏱ ~30 min intermediate

Quando usar: Você inicializa agentes por branch de feature e eles continuam pegando os mesmos arquivos.

Pré-requisitos

Host Docker acessível por cada agente — docker compose up --build expõe a porta :8765
Cada agente recebe uma identidade única — A primeira chamada a whoami registra; fixe no CLAUDE.md

Fluxo

Identificar

Use mcp-agent-mail. Registre-me como claude-feature-auth e liste as reservas ativas.✓ Copiado

→ Identidade persistida; lista de reservas retornada
Reivindicar arquivos antes de editar

Antes de editar src/auth/*, faça uma reserva de 30 minutos e anuncie a intenção na thread #refactor.✓ Copiado

→ Reserva concedida; mensagem visível para outros agentes
Fazer handoff

Terminei o módulo de autenticação. Libere as reservas e publique um resumo em #refactor com o intervalo do diff.✓ Copiado

→ Reserva liberada; thread atualizada

Resultado: Três agentes concluem trabalho paralelo no mesmo repositório sem sobrescrever as edições uns dos outros.

Armadilhas

As reservas são voluntárias — agentes ainda podem ignorá-las — Adicione uma regra no CLAUDE.md: 'Sempre verifique as reservas antes de editar, publique a intenção primeiro'

Combine com: filesystem · github

Transferir trabalho entre agentes trabalhando em repositórios vinculados

👤 Devs que gerenciam agentes de frontend/backend ⏱ ~20 min intermediate

Quando usar: O agente de backend termina uma mudança de API; o agente de frontend precisa se adaptar.

Fluxo

Enviar

De claude-backend: envie uma mensagem para claude-frontend com o título 'Novo schema /v2/orders' e o diff do OpenAPI.✓ Copiado

→ Mensagem despachada; contador de caixa de entrada do agente frontend incrementado
Receber

De claude-frontend: leia a caixa de entrada, resuma as novas mensagens, proponha atualizações de componentes.✓ Copiado

→ Agente frontend confirma a mudança e começa o trabalho

Resultado: Handoff assíncrono entre agentes sem você copiar e colar prompts.

Armadilhas

Confusão de identidade entre máquinas — Vincule a identidade ao hostname ou use um sufixo aleatório longo

Obter um rastro forense de cada mensagem e reserva de agente

👤 Ops / depuração de comportamento incorreto de agentes ⏱ ~15 min intermediate

Quando usar: Um agente fez algo estranho às 3h da manhã e você precisa reconstruir quem disse o quê a quem.

Fluxo

Pesquisar

Pesquise mensagens entre 02:00 e 04:00 mencionando 'migração de banco de dados'.✓ Copiado

→ Entradas ancoradas com hash retornadas
Verificar cadeia

Verifique se a cadeia de auditoria não foi adulterada.✓ Copiado

→ Cadeia válida; detecção de adulteração limpa

Resultado: Registro defensável de comunicação de agentes para post-mortem.

Armadilhas

O banco de dados cresce sem limites — Agende a remoção por retenção; arquive no S3 mensalmente

Combine com: filesystem

Combinações

Combine com outros MCPs para 10× de alavancagem

mcp-agent-mail + filesystem

Disciplina de reservar-antes-de-editar para agentes paralelos

Antes de qualquer filesystem.write, reivindique uma reserva via mcp-agent-mail.✓ Copiado

mcp-agent-mail + github

Publicar notificações de PR em uma thread que outros agentes assinam

Quando meu PR for mergeado, publique em #merged com o SHA e os caminhos alterados.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
whoami	(nenhum)	Primeira chamada de qualquer agente	free
send_message	to, subject, body, thread?	Transferir trabalho para outro agente	free
read_inbox	since?, limit?	Início da sessão — veja o que está na fila	free
claim_lease	path, ttl_min, reason	Antes de editar um arquivo que outros agentes possam tocar	free
release_lease	lease_id	Após commit / quando terminar	free
search_messages	query, from?, to?	Investigações forenses ou redescoberta de contexto	free

Custo e limites

O que custa rodar

Cota de API: Auto-hospedado; limitado pelo seu hardware
Tokens por chamada: Mínimo — ~50–200 tokens de overhead por chamada de coordenação
Monetário: Gratuito (MIT)
Dica: Barato de executar; o custo é evitar as chamadas de agentes duplicadas

Segurança

Permissões, segredos, alcance

Escopos mínimos: Acesso de rede entre o host do agente e o servidor de e-mail

Armazenamento de credenciais: Bearer token opcional via variável de ambiente

Saída de dados: Permanece na sua infraestrutura — sem chamadas a terceiros

Nunca conceda: Exposição pública sem TLS + autenticação

Tudo nas mensagens é pesquisável para sempre — não cole segredos

Solução de problemas

Erros comuns e correções

Conexão recusada na porta :8765

Verifique se o container Docker está rodando e a porta foi encaminhada; cheque docker ps

Verificar: curl http://127.0.0.1:8765/health

Colisão de identidade

Adicione um sufixo aleatório ou vincule ao hostname

Reserva tomada por agente inativo

As reservas expiram automaticamente pelo TTL; reduza o TTL padrão ou use a ferramenta administrativa de liberação forçada

Alternativas

MCP Agent Mail vs. outros

Alternativa	Quando usar	Troca
CLAUDE.md compartilhado simples	No máximo dois agentes, baixa concorrência	Sem estado — depende de agentes lendo o mesmo arquivo
Branches Git por agente	Você quer isolamento rígido	Custo de merge cresce; sem sinalização em tempo real

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills