Existe uma diferença real entre uma API que um agente pode chamar e uma API que um agente sabe como chamar. Um endpoint REST exige que o modelo mantenha no contexto a URL base, o formato do header de autenticação, o corpo JSON e o schema da resposta, e que acerte as quatro coisas de primeira. Uma definição de ferramenta entrega tudo isso de graça, pelo protocolo.
Esse é todo o argumento a favor do MCP aqui. Uma caixa de entrada é uma superfície pequena o suficiente para que a lista de ferramentas seja a documentação.
Como conectar
O apumail publica um descritor MCP em /.well-known/mcp.json. Para um cliente
que lê descritores, basta apontá-lo para a origem:
https://api.apumail.com/.well-known/mcp.jsonSem etapa de instalação, sem pacote para baixar, sem chave para criar antes: as ferramentas
de caixa que exigem autenticação usam o token que o create_inbox devolve.
As 9 ferramentas
Elas se dividem em três grupos, e esse agrupamento é o modelo mental:
Obter um endereço
create_inbox: cria uma caixa com slug aleatório e retorna o endereço e o token dele. Sem autenticação. Este é o ponto de entrada.get_inbox: metadados da caixa e estado do TTL.
Receber
list_mails: tudo o que está na caixa neste momento.read_mail: uma mensagem, corpo completo, sanitizado.wait_for_mail: a importante. Bloqueia até um e-mail chegar. É o que impede o agente de queimar uma ida e volta ao modelo a cada polling.extract_latest_otp: o código da mensagem mais recente, já extraído no lado do servidor.
Enviar
send_mail: responde a partir do mesmo endereço. Ofromé forçado para a caixa autenticada, então um token vazado não consegue se passar por ninguém.
Além disso, wait_for_sms e extract_latest_sms_otp no plano
pago, que fazem exatamente o mesmo que suas equivalentes de e-mail: o mesmo formato de espera/extração,
com números de telefone em vez de endereços.
Como o fluxo fica em ferramentas
A dança do cadastro que eram três chamadas curl no post sobre OTP se resume a isto:
create_inbox→ o agente recebevivid-llama-4a2c@apumail.com- o agente digita esse endereço no formulário em que está trabalhando
wait_for_mail→ bloqueia e retorna quando a confirmação chegaextract_latest_otp→"482910"
Nada disso exige raciocínio específico do apumail. O modelo não precisa saber o que
o apumail é: precisa saber que existe uma ferramenta chamada wait_for_mail,
o que o protocolo já contou a ele.
Quando dispensar o MCP
Sendo honesto: se você está escrevendo uma suíte de testes, use a API REST. O MCP se paga
quando quem chama é um modelo decidindo o que fazer em seguida. Quando quem chama é o seu
pipeline de CI rodando um script conhecido, os endpoints são mais simples e não há protocolo
no meio. Os dois usam o mesmo backend, então misturá-los não tem problema: crie a caixa via
REST numa fixture, passe o endereço ao agente e deixe ele fazer wait_for_mail via MCP.
O descritor é a documentação
Se você quiser ler a superfície antes de conectar qualquer coisa, três URLs respondem tudo:
- /.well-known/mcp.json: o descritor MCP
- /openapi.json: OpenAPI 3.1 para o lado REST
- /llms.txt: a mesma coisa em Markdown, escrita para um modelo ler do início ao fim