Documentación MCP
Conecta tu agente a QMailing
QMailing entrega un servidor Model Context Protocol alojado — Claude, Cursor, Continue y cualquier otro agente compatible con MCP pueden leer tu buzón, enviar correo, gestionar buzones y reaccionar a eventos a través de doce herramientas con scope. Sin npm install, sin proceso local — solo un token Bearer y una URL de servidor.
https://qmailing.com/mcp¿Qué es QMailing MCP?
https://qmailing.com/mcp es un servidor MCP streamable-HTTP alojado por QMailing. Cualquier cliente compatible con MCP (Claude Desktop, conectores Claude.ai, Cursor, Continue, agentes personalizados) puede conectarse, autenticarse con un token Bearer OAuth y llamar a doce herramientas mapeadas 1:1 con la superficie REST de QMailing.
Para quién: indie makers, freelancers y agencias que manejan varios dominios de marca y quieren que su asistente IA clasifique correo entrante, redacte respuestas, registre webhooks y gestione buzones — sin una sola línea de código pegamento.
Lo que no es: una API de envío transaccional como SendGrid. QMailing es un SaaS completo de buzón — cada herramienta opera sobre buzones reales que posees. El servidor MCP es la superficie para agentes; las mismas operaciones funcionan por REST en /api/v1/pub/* con el mismo token.
Conectar a Claude
Tres pasos. La emisión del token ocurre en el dashboard de QMailing, la conexión en los ajustes de Claude.
- 1. Pasa a PLUS — las herramientas básicas de solo lectura (
list_mailboxes,get_mailbox) están disponibles en FREE con un tope de 25 peticiones diarias; todo lo demás requiere PLUS o superior. - 2. Emite un token OAuth — ve a Ajustes → Desarrolladores → pulsa Connect to Claude. Elige los scopes que quieres dar al agente (el asistente sugiere un default sensato por caso de uso).
- 3a. Claude Desktop / Claude.ai: abre Ajustes → Connectors → Add custom connector. Pega la URL del servidor abajo y el token del paso 2.
- 3b. Cursor / Continue / cliente personalizado: añade una entrada HTTP MCP server apuntando a la URL abajo con el header estándar
Authorization: Bearer …. Streamable HTTP transport (no stdio, no SSE).
- URL del servidor
- https://qmailing.com/mcp
- Transport
- Streamable HTTP (revisión de protocolo MCP 2025-06-18)
Verificar la conexión
Pregúntale al agente: «Show me my mailboxes». Debería llamar a qmailing_list_mailboxes y devolver la lista. Si ves 401 — token incorrecto o revocado. 402 — herramienta por encima de tu plan. 403 — el token no porta el scope requerido. Matriz completa en Resolución de problemas.
Scopes OAuth
Los tokens reciben scopes en la emisión. Cada herramienta exige uno o más scopes; la llamada del agente se rechaza con 403 antes de ejecutar código si falta un scope. Emite un token de solo lectura si solo quieres triar sin enviar.
| Scope | Permite | Herramientas |
|---|---|---|
| mailbox:read | Listar e inspeccionar tus buzones | list_mailboxes, get_mailbox |
| mailbox:write | Crear nuevos buzones en dominios que posees | create_mailbox |
| domain:read | Listar dominios y leer la checklist DNS | list_domains, get_dns_records |
| domain:write | Reservado para futuros endpoints de gestión de dominios | — |
| email:read | Leer correos, descargar adjuntos | list_emails, get_email, get_attachment |
| email:send | Enviar correo saliente a través de tus buzones | send_email |
| webhook:manage | Registrar, listar y revocar endpoints webhook | list_webhooks, register_webhook, delete_webhook |
Herramientas disponibles
Doce herramientas, un servidor. Cada herramienta porta un JSON-Schema para sus argumentos y un bloque de annotations (título, hints read-only / destructive) que el agente usa para decidir si pedir confirmación antes de llamar. Abajo: prompts de ejemplo agrupados por intención de usuario.
Buzones
List Mailboxes
mailbox:readqmailing_list_mailboxes
Devuelve cada buzón que posees con direcciones, estado, contadores de mensajes y uso de almacenamiento.
Prompt de ejemplo: «What mailboxes do I have?»
Get Mailbox
mailbox:readqmailing_get_mailbox
Un solo buzón por UUID — ajustes de reenvío, contadores, pertenencia a grupos.
Prompt de ejemplo: «Show me the settings for sales@my-startup.com.»
Create Mailbox
mailbox:writeqmailing_create_mailbox
Provisionar un nuevo buzón en un dominio que posees. Local-part + display name y reenvío opcionales.
Prompt de ejemplo: «Create a mailbox sales@my-startup.com that forwards to me.»
Dominios y DNS
List Domains
domain:readqmailing_list_domains
Tus vinculaciones de dominio personalizado con estado de verificación MX / SPF / DKIM / DMARC y ownership-claim.
Prompt de ejemplo: «Which of my domains haven't verified DKIM yet?»
Get DNS Records
domain:readqmailing_get_dns_records
Checklist DNS para un dominio personalizado — host + valor + tipo + estado de verificación actual por registro.
Prompt de ejemplo: «Show me the DNS records I still need to add for acme.dev.»
Correo
List Emails
email:readqmailing_list_emails
Listado paginado dentro de un buzón + carpeta (INBOX, SENT, DRAFTS, TRASH, STARRED, SPAM).
Prompt de ejemplo: «Show me unread emails from support@acme.dev.»
Get Email
email:readqmailing_get_email
Un solo correo por UUID con headers completos, cuerpo parseado (HTML + texto) y metadatos de adjuntos.
Prompt de ejemplo: «What did Alice say in her last reply?»
Get Attachment
email:readqmailing_get_attachment
Obtener un solo adjunto por email-id + índice. Devuelve filename + content-type + size + bytes Base64 (cap 5 MB inline).
Prompt de ejemplo: «Download the invoice PDF from Alice's last email.»
Send Email
email:sendqmailing_send_email
Enviar un correo saliente desde uno de tus buzones. Cuerpos plain-text + HTML, to/cc/bcc, reply threading.
Prompt de ejemplo: «Send a reply to john@example.com confirming the meeting at 3pm.»
Webhooks
List Webhooks
webhook:manageqmailing_list_webhooks
Tus endpoints webhook registrados, activos y revocados, los más recientes primero.
Prompt de ejemplo: «Show me my webhook endpoints.»
Register Webhook
webhook:manageqmailing_register_webhook
Registrar un endpoint HTTP para recibir notificaciones de eventos. El secret de firma se devuelve UNA VEZ.
Prompt de ejemplo: «Register a webhook for email.received events at https://my-server.com/qmailing.»
Delete Webhook
webhook:manageqmailing_delete_webhook
Revocar un endpoint webhook. Idempotente — endpoints ya revocados devuelven éxito.
Prompt de ejemplo: «Revoke the webhook from yesterday.»
Planes y límites
Doce herramientas, cuatro niveles. FREE basta para evaluar la integración; PLUS desbloquea todas las operaciones read + write excepto webhooks; PRO+ desbloquea webhooks para automation inbound.
| Herramienta | FREE | PLUS | PRO | PRO_MAX |
|---|---|---|---|---|
| list_mailboxes | ✓ | ✓ | ✓ | ✓ |
| get_mailbox | ✓ | ✓ | ✓ | ✓ |
| create_mailbox | — | ✓ | ✓ | ✓ |
| list_domains | — | ✓ | ✓ | ✓ |
| get_dns_records | — | ✓ | ✓ | ✓ |
| list_emails | — | ✓ | ✓ | ✓ |
| get_email | — | ✓ | ✓ | ✓ |
| get_attachment | — | ✓ | ✓ | ✓ |
| send_email | — | ✓ | ✓ | ✓ |
| list_webhooks | — | — | ✓ | ✓ |
| register_webhook | — | — | ✓ | ✓ |
| delete_webhook | — | — | ✓ | ✓ |
429 Too Many Requests con Retry-After en segundos. PLUS y superiores levantan el tope diario; el throttle por-token de 300 peticiones/min en la capa transport sigue activo.Resolución de problemas
Cada respuesta de error sigue RFC-7807 problem+json — una URL type estable, status, title, detail más un campo code para branching. El agente muestra detail como mensaje al usuario.
| Estado | Cuándo lo ves | Solución |
|---|---|---|
| 401 | Token ausente, malformado, expirado o revocado. | Vuelve a emitirlo desde Ajustes → Desarrolladores y actualiza el connector. |
| 402 | La herramienta requiere un plan superior al de la cuenta. | Sube de plan — la respuesta lleva upgradeUrl y el nombre requiredPlan. |
| 403 | Token autenticado pero sin el scope requerido. | Vuelve a emitir un token con el scope que falta, o cambia a uno que ya lo lleve. |
| 429 | FREE superó 25 peticiones/día o un token superó 300 peticiones/minuto. | Espera los segundos Retry-After. Sube a PLUS para levantar el tope diario. |
Privacidad y seguridad
Los tokens OAuth están ligados a una sola cuenta y a un solo cliente (Claude, Cursor o personalizado). Los tokens se guardan en servidor como hashes bcrypt — el valor en claro qm_live_… se muestra exactamente una vez en la emisión. Revocables en cualquier momento desde el dashboard; la revocación se honra en la siguiente petición, sin caché.
Cada llamada a herramienta pasa tres puertas independientes antes de la lógica de negocio: (a) el plan del token debe permitir la herramienta pedida, (b) el set de scopes del token debe cubrir los requisitos declarados, (c) el recurso tocado debe pertenecer al usuario autenticado. Fallo de cualquiera → error RFC-7807 antes de ejecutar call().
Mira la política de privacidad para sub-processors, detalles de OAuth sign-in y retención. El servidor MCP loguea metadatos de petición (timestamp, nombre de herramienta, código de estado) durante 30 días — los bodies de petición y resultados de herramientas nunca se persisten en logs.