Caixa de e-mail para Claude Code, Cursor e Windsurf via MCP

Um servidor, sete clientes

O servidor é um único endpoint HTTPS que fala o Model Context Protocol via Streamable HTTP: um POST carregando JSON-RPC, uma resposta JSON, nenhum stream mantido aberto. Não há nada para instalar, nada para rodar localmente e nada para se cadastrar nos domínios públicos — a URL é a configuração inteira:

Endpoint MCPhttps://grabmail.io/mcpCopiar

Todo cliente MCP aceita um servidor HTTP remoto, mas cada um mantém sua configuração em um arquivo diferente, com um nome de chave um pouco diferente. As seções abaixo dão a linha exata para cada um. Os formatos são os vigentes em setembro de 2026; a documentação de cada cliente é a autoridade caso algum tenha mudado desde então.

Confira se ele responde, a partir de um shell

Antes de mexer em qualquer cliente, prove que o servidor está lá e veja o que ele oferece. Como o transporte é HTTP simples, um curl já basta:

$ curl -s -X POST https://grabmail.io/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

"create_inbox"
"list_domains"
"list_messages"
"read_message"
"wait_for_message"
"delete_message"

Se isso funcionar, todo cliente abaixo também vai funcionar, e um cliente que falhar depois disso é um problema de configuração no cliente, não um problema do servidor. Se não funcionar, confira se a sua rede permite saída HTTPS para grabmail.io — essa é toda a superfície envolvida.

Claude Code

Um comando, a partir de qualquer diretório. Ele registra o servidor para o seu usuário, então ele fica disponível em todo projeto:

$ claude mcp add --transport http grabmail https://grabmail.io/mcp

Para compartilhar com um time através do repositório em vez disso, restrinja o escopo ao projeto. Isso escreve um .mcp.json na raiz, que é versionado e para o qual os colegas de equipe recebem um pedido de aprovação:

$ claude mcp add --transport http --scope project grabmail https://grabmail.io/mcp

{
  "mcpServers": {
    "grabmail": {
      "type": "http",
      "url": "https://grabmail.io/mcp"
    }
  }
}

Reinicie o Claude Code, rode /mcp, e grabmail aparece listado com suas seis ferramentas. O servidor também responde à chamada initialize do protocolo com um parágrafo curto de instruções, que o Claude Code repassa ao modelo — então o agente já chega sabendo que deve entregar o alias e esperar pelo endereço.

Claude Desktop

Servidores remotos são adicionados através da aplicação, não do arquivo de configuração:

1. Vá em Settings → Connectors → Add custom connector.
2. Cole https://grabmail.io/mcp como a URL e dê um nome a ele.
3. Inicie uma nova conversa e as ferramentas aparecem sob o conector.

Em uma versão que só aceita servidores locais em claude_desktop_config.json, faça a ponte até o endpoint remoto com mcp-remote, que roda como um processo local e encaminha para a URL:

{
  "mcpServers": {
    "grabmail": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://grabmail.io/mcp"]
    }
  }
}

Cursor

O Cursor lê .cursor/mcp.json no projeto (ou ~/.cursor/mcp.json para todos os projetos). Um servidor remoto é uma url:

{
  "mcpServers": {
    "grabmail": {
      "url": "https://grabmail.io/mcp"
    }
  }
}

Abra Cursor Settings → MCP para vê-lo listado e habilitar suas ferramentas. No modo agente, o modelo as chama sozinho; no chat, você pode pedir por elas pelo nome.

Windsurf

O Windsurf mantém seus servidores em ~/.codeium/windsurf/mcp_config.json, e a chave para um servidor remoto é serverUrl em vez de url — o único lugar onde o formato muda:

{
  "mcpServers": {
    "grabmail": {
      "serverUrl": "https://grabmail.io/mcp"
    }
  }
}

O Cascade lista o servidor depois de um refresh a partir do painel MCP. O mesmo arquivo pode ser acessado em Windsurf Settings → Cascade → MCP servers → View raw config.

VS Code

O modo agente do VS Code lê .vscode/mcp.json no workspace, ou o arquivo no nível do usuário que MCP: Add Server na paleta de comandos escreve. Os servidores ficam sob servers, não mcpServers, e um remoto declara seu transporte:

{
  "servers": {
    "grabmail": {
      "type": "http",
      "url": "https://grabmail.io/mcp"
    }
  }
}

Um pequeno link “Start” aparece acima da entrada no editor; depois disso, as ferramentas aparecem no seletor de ferramentas do chat, e o modo agente as chama sem precisar ser pedido.

Codex CLI and Gemini CLI

O Codex CLI mantém sua configuração em TOML em ~/.codex/config.toml. Um servidor remoto é uma tabela com uma url:

[mcp_servers.grabmail]
url = "https://grabmail.io/mcp"

O Gemini CLI lê ~/.gemini/settings.json (ou .gemini/settings.json no projeto), e a chave para um servidor Streamable HTTP é httpUrl:

{
  "mcpServers": {
    "grabmail": {
      "httpUrl": "https://grabmail.io/mcp"
    }
  }
}

Uma versão de qualquer um dos dois que só aceita servidores locais pode alcançar o endpoint através da mesma ponte mcp-remote mostrada para o Claude Desktop: command = "npx", args = ["-y", "mcp-remote", "https://grabmail.io/mcp"].

As seis ferramentas

Seja qual for o cliente, o modelo vê as mesmas seis ferramentas com os mesmos nomes. Não há estado para gerenciar entre chamadas, e nenhuma delas precisa de um argumento que a anterior não tenha retornado.

create_inbox

Inventa um endereço novo e o retorna com seu alias e um next_step dizendo qual usar onde. Nada é reservado do lado do servidor, então isso nunca pode falhar. Aceita um prefix legível opcional.

wait_for_message

Bloqueia até uma mensagem chegar no endereço, por até 25 segundos, e então a retorna completa — assunto, remetente, texto puro, HTML. Filtre com subject_contains ou from_contains; passe since_id para ignorar o que já estava lá. Depois de uma espera silenciosa, ela responde timed_out e pede para ser chamada de novo.

read_message

Uma mensagem completa pelo id. Raramente necessária, porque a espera já retorna a mensagem inteira.

list_messages

Tudo o que está esperando em um endereço, mais recente primeiro, imediatamente — inclusive quando não há nada.

list_domains

Os domínios públicos que qualquer um pode usar, para quando um formulário acabou de recusar um deles.

delete_message

Remove uma mensagem agora em vez de daqui a 5 dias. Idempotente, então um agente que tenta de novo não custa nada.

O loop de cadastro em quatro chamadas

Essa é a sequência de que quase toda tarefa precisa, e o cliente não muda isso:

1. create_inbox. Voltam um endereço, um alias, e a nota dizendo qual é qual.
2. O alias vai para o formulário. O site recebe um endereço funcional que chega até a caixa de entrada e não pode ser usado para abri-la.
3. wait_for_message no endereço, imediatamente depois de enviar, com subject_contains definido para uma palavra que o e-mail de confirmação vai carregar. Ela bloqueia; o agente não entra em loop.
4. O código sai da mensagem que a espera retornou. Geralmente não há nenhuma chamada adicional.

Sign up for a trial at https://app.example.com/signup with a fresh GrabMail inbox.
Use the ALIAS in the form, wait for the confirmation code with wait_for_message
on the ADDRESS, enter it, and tell me the resulting login.

O que colocar nas próprias instruções do agente

O servidor diz ao modelo como usá-lo no momento da conexão, mas um modelo que já leu as mesmas quatro regras nas próprias instruções do projeto as segue sempre, em vez de na maioria das vezes. Adicione isto a CLAUDE.md, .cursor/rules, .windsurfrules, AGENTS.md ou GEMINI.md — o que quer que o seu cliente leia:

## Email

- To receive email, use the `grabmail` MCP server. Call `create_inbox` once per task.
- Put the **alias** it returns into forms; poll the **address** it returns with `wait_for_message`.
- Call `wait_for_message` right after submitting a form, with `subject_contains` set to a word
  you expect ("code", "verify", "confirm"). If it returns `timed_out`, call it again — up to
  three times — before concluding the mail was not sent.
- Never reuse an inbox across tasks. Never send anything confidential to one: it is public.

As duas regras mais importantes são as que um agente erra se não for avisado: colocar o alias no formulário e fazer polling no endereço, e tratar timed_out como “chame de novo”, não como “o e-mail nunca foi enviado”. Uma caixa de entrada que um agente de IA consegue ler detalha as duas em profundidade, incluindo por que a espera retorna antes do e-mail.

Quando não funciona

Antes de considerar concluído

• O curl acima lista seis ferramentas a partir da sua máquina.
• O servidor aparece no painel MCP do cliente depois de um reinício, com as ferramentas habilitadas.
• O parágrafo de instruções está no arquivo que o seu cliente lê.
• Um prompt de teste completou um cadastro: alias no formulário, espera no endereço, código extraído da mensagem.
• Nada confidencial jamais será enviado para uma dessas caixas de entrada — elas são públicas.

Essa é a configuração inteira. O mesmo servidor funciona a partir de qualquer framework que fale MCP, e para agentes construídos sem MCP — uma função de ferramenta simples em LangChain, no OpenAI Agents SDK ou no seu próprio loop — e-mail para agentes de IA mostra a versão REST dos mesmos quatro passos.

Perguntas