Hay una diferencia real entre una API que un agente puede llamar y una API que un agente sabe cómo llamar. Un endpoint REST exige que el modelo tenga en contexto la URL base, la forma del header de autenticación, el cuerpo JSON y el esquema de respuesta, y que acierte las cuatro cosas de una. Una definición de herramienta se las entrega gratis, desde el protocolo.
Ese es todo el argumento a favor de MCP aquí. Una bandeja es una superficie lo bastante pequeña como para que la lista de herramientas sea la documentación.
Cómo conectarlo
apumail publica un descriptor MCP en /.well-known/mcp.json. Para un cliente
que lee descriptores, basta con apuntarlo al origen:
https://api.apumail.com/.well-known/mcp.jsonSin paso de instalación, sin paquete que descargar, sin clave que crear antes: las
herramientas de bandeja que requieren autenticación usan el token que devuelve create_inbox.
Las 9 herramientas
Se dividen en tres grupos, y esa agrupación es el modelo mental:
Obtener una dirección
create_inbox: crea una bandeja con slug aleatorio y devuelve la dirección y su token. Sin autenticación. Este es el punto de entrada.get_inbox: metadatos de la bandeja y estado del TTL.
Recibir
list_mails: todo lo que hay en la bandeja en este momento.read_mail: un mensaje, cuerpo completo, sanitizado.wait_for_mail: la importante. Bloquea hasta que llega un correo. Es lo que evita que el agente queme una ida y vuelta al modelo por cada sondeo.extract_latest_otp: el código del mensaje más reciente, ya extraído del lado del servidor.
Enviar
send_mail: responde desde la misma dirección. Elfromse fuerza a la bandeja autenticada, así que un token filtrado no puede suplantar a nadie.
Además, wait_for_sms y extract_latest_sms_otp en el plan
pago, que hacen exactamente lo mismo que sus equivalentes de email: la misma forma de espera/extracción,
con números de teléfono en vez de direcciones.
Cómo se ve el flujo como herramientas
El baile del registro que eran tres llamadas curl en el post sobre OTP se reduce a esto:
create_inbox→ el agente obtienevivid-llama-4a2c@apumail.com- el agente escribe esa dirección en el formulario en que está trabajando
wait_for_mail→ bloquea y responde cuando llega la confirmaciónextract_latest_otp→"482910"
Nada de eso requiere razonamiento específico de apumail. El modelo no necesita saber qué
es apumail: necesita saber que existe una herramienta llamada wait_for_mail,
cosa que el protocolo ya le dijo.
Cuándo prescindir de MCP
Con honestidad: si estás escribiendo una suite de pruebas, usa la API REST. MCP se gana
su lugar cuando quien llama es un modelo que decide qué hacer a continuación. Cuando quien
llama es tu pipeline de CI ejecutando un script conocido, los endpoints son más simples y
no hay protocolo de por medio. Ambos usan el mismo backend, así que mezclarlos está bien:
crea la bandeja por REST en un fixture, pásale la dirección al agente y deja que haga
wait_for_mail por MCP.
El descriptor es la documentación
Si quieres leer la superficie antes de conectar nada, tres URLs responden todo:
- /.well-known/mcp.json: el descriptor MCP
- /openapi.json: OpenAPI 3.1 para el lado REST
- /llms.txt: lo mismo en Markdown, escrito para que un modelo lo lea de principio a fin