Documentación

Tu agente tiene una bandeja de entrada
en cuatro pasos.

Conecta cualquier cuenta de correo, pega una URL en un cliente MCP con OAuth y autoriza. Los clientes sin OAuth usan una clave de API en su lugar. Referencia completa de herramientas y guía de conexión más abajo.

Inicio rápido OAuth (claude.ai)Referencia de herramientas Soporte de proveedores

Inicio rápido

En marcha en minutos.

No se requiere SDK. MCPEmails habla MCP estándar sobre HTTP, así que encaja en cualquier agente compatible con MCP.

01Regístrate y conecta una bandeja

Crea tu cuenta y conecta Gmail

Regístrate en mcpemails.com, luego ve a Panel → Bandejas → Conectar bandeja. Elige Gmail, Outlook, iCloud, Fastmail o cualquier bandeja IMAP, después completa el flujo de OAuth o pega una contraseña de aplicación. Tu bandeja queda lista en menos de un minuto.

Conecta tu bandeja de entrada →

02Crea una clave de API

Genera un token bearer para tu agente

En Panel → Claves de API, haz clic en «Crear clave». Ponle nombre, selecciona los alcances que necesita tu agente (read:email y/o send:email) y copia la clave. Solo se muestra una vez.

# Your key looks like this:
mcpe_live_AbCdEfGhIjKlMnOpQrStUvWxYz123456

03Añade MCPEmails a tu agente

Pega el endpoint MCP en tu cliente

Elige la pestaña de tu cliente más abajo. Los clientes MCP con soporte de OAuth 2.0 (claude.ai, Claude Desktop, Cursor y otros) solo pegan la URL y autorizan, sin necesidad de clave de API. Los clientes sin OAuth, además del acceso por scripts, usan la clave de API del paso 02.

json

# OAuth-capable clients (claude.ai, Claude Desktop, Cursor…)
# No API key required. Paste the URL, click Connect, authorize.
#
# Example: claude.ai
#   1. Go to claude.ai → Customize → Connectors
#   2. Click "Add connector" and paste this URL:
#
#        https://www.mcpemails.com/api/mcp
#
#   3. Click Connect and sign in with your mcpemails account.
#   4. All six tools are live immediately.
#
# Claude Desktop and Cursor follow the same OAuth flow when
# the server URL is configured in their MCP settings.

04Haz tu primera llamada

Pídele a tu agente que revise tu bandeja

Sin copiar y pegar UUIDs de bandejas. Tu agente llama primero a list_inboxes para descubrir cada bandeja conectada y su UUID, y luego le preguntas: «Revisa mi bandeja y resume los últimos 5 mensajes no leídos.»

# The agent calls list_inboxes first, so no hardcoded UUIDs.
# System prompt (optional, for multi-inbox setups):
You have access to email via MCPEmails.
Start by calling list_inboxes to discover available inboxes.

Endpoint

Una URL, MCP estándar.

Todo el tráfico va a un único endpoint Streamable HTTP. Autentícate con un token bearer de tu panel.

POSThttps://www.mcpemails.com/api/mcp

Envía un cuerpo de petición JSON-RPC 2.0. Métodos admitidos: initialize, tools/list, tools/call.

Transporte: Streamable HTTP (MCP 2025-06-18)

Autenticación: Authorization: Bearer <api-key>

Límites de tasa: 100 pet/min · 1.000/h · 10.000/día por clave

Formato de respuesta: JSON-RPC 2.0

Handshake de inicialización

bash

curl -X POST https://www.mcpemails.com/api/mcp \
  -H "Authorization: Bearer mcpe_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "clientInfo": { "name": "my-agent", "version": "1.0" },
      "capabilities": {}
    }
  }'

Conexión OAuth

Cero configuración para clientes con OAuth.

Los clientes MCP que admiten OAuth 2.0 (claude.ai, Claude Desktop, Cursor y otros) se conectan automáticamente mediante código de autorización + PKCE. Sin clave de API, sin archivo de configuración. Pega la URL y haz clic en Conectar.

Paso 1: Ve a claude.ai → Personalizar → Conectores → Añadir conector

Paso 2: Pega https://www.mcpemails.com/api/mcp como la URL del servidor

Paso 3: Haz clic en Conectar. MCPEmails abre una pantalla de autorización

Paso 4: Inicia sesión con tu cuenta de mcpemails y aprueba el acceso

Listo: Las seis herramientas están activas. claude.ai actualiza los tokens automáticamente

Cómo funciona internamente

claude.ai se registra a sí mismo mediante el Registro dinámico de clientes RFC 7591, así que nunca pre-registras un ID de cliente.

La autorización usa Código de autorización OAuth 2.0 + PKCE (RFC 7636), así que nunca se transmite ningún secreto de cliente.

Los tokens se limitan exactamente a los permisos que apruebas: read:email y/o send:email.

¿Usas un cliente sin soporte de OAuth? Crea una clave de API en Panel → Claves de API y pásala como token bearer. Las conexiones por clave de API y por OAuth usan el mismo endpoint MCP y las mismas seis herramientas.

Referencia de herramientas

Seis herramientas. Todas las operaciones de correo que tu agente necesita.

Empieza con list_inboxes para descubrir las bandejas disponibles y sus UUIDs. Las cinco herramientas restantes toman cada una un inbox_id devuelto por esa llamada. Haz clic en «Mostrar ejemplo» para ver una petición y respuesta completas.

list_inboxesread:email list_inboxread:email read_emailread:email search_emailsread:email send_emailsend:email reply_to_emailsend:email

list_inboxesread:email

Devuelve todas las bandejas a las que la clave de API o el token de OAuth actuales pueden acceder. Llama a esto primero para descubrir los valores de inbox_id, así nunca copias y pegas UUIDs del panel.

Sin parámetros. Llama con un objeto de argumentos vacío: {}

list_inboxread:email

Lista resúmenes de correos de una bandeja conectada, los más nuevos primero. Admite paginación, selección de carpeta y filtrado de no leídos.

Parámetro	Tipo	Obligatorio	Descripción
`inbox_id`	string (uuid)	obligatorio	UUID de la bandeja a listar. Llama primero a list_inboxes para descubrir los IDs de bandeja disponibles.
`limit`	integer	opcional	Máximo de resultados a devolver. Predeterminado 20, máximo 100.
`offset`	integer	opcional	Desplazamiento de paginación basado en cero. Predeterminado 0.
`folder`	string	opcional	Carpeta a listar. Predeterminado "INBOX". Otros valores: "SENT", "DRAFTS", "TRASH".
`unread_only`	boolean	opcional	Devolver solo mensajes no leídos. Predeterminado false.

read_emailread:email

Obtiene el contenido completo de un solo correo por ID, incluido el cuerpo en texto plano, HTML saneado opcional y datos de adjuntos opcionales.

Parámetro	Tipo	Obligatorio	Descripción
`inbox_id`	string (uuid)	obligatorio	UUID de la bandeja que contiene el correo. Llama a list_inboxes para obtener los IDs de bandeja disponibles.
`message_id`	string	obligatorio	ID de mensaje del proveedor de list_inbox o search_emails.
`include_html`	boolean	opcional	Incluir el cuerpo HTML saneado. Predeterminado false.
`include_attachments`	boolean	opcional	Incluir datos de adjuntos en base64. Predeterminado false.
`mark_as_read`	boolean	opcional	Marcar el mensaje como leído tras obtenerlo. Predeterminado false.

search_emailsread:email

Busca en una bandeja usando la sintaxis de consulta nativa del proveedor. Gmail admite operadores de búsqueda de Gmail; Outlook usa $search; las bandejas de Fastmail e IMAP usan búsqueda de texto.

Parámetro	Tipo	Obligatorio	Descripción
`inbox_id`	string (uuid)	obligatorio	UUID de la bandeja en la que buscar. Llama a list_inboxes para obtener los IDs de bandeja disponibles.
`query`	string	obligatorio	Consulta de búsqueda. Para Gmail: "from:alice@example.com after:2026/01/01". Para Outlook: consultas en lenguaje natural o KQL.
`limit`	integer	opcional	Máximo de resultados. Predeterminado 20, máximo 100.
`offset`	integer	opcional	Desplazamiento de paginación. Predeterminado 0.
`include_folders`	array	opcional	Restringir la búsqueda a estos nombres de carpeta. Predeterminado: buscar en todas las carpetas.

send_emailsend:email

Envía un correo nuevo desde una bandeja conectada. Admite texto plano, cuerpo HTML opcional, CC/CCO y adjuntos (hasta 10 MB en total).

Parámetro	Tipo	Obligatorio	Descripción
`inbox_id`	string (uuid)	obligatorio	UUID de la bandeja desde la que enviar. Llama a list_inboxes para obtener los IDs de bandeja disponibles.
`to`	array[string]	obligatorio	Direcciones de correo de los destinatarios. Máximo 50.
`subject`	string	obligatorio	Línea de asunto del correo. Máximo 998 caracteres.
`body`	string	obligatorio	Cuerpo del correo en texto plano.
`cc`	array[string]	opcional	Destinatarios en CC. Predeterminado [].
`bcc`	array[string]	opcional	Destinatarios en CCO. Predeterminado [].
`html_body`	string	opcional	Versión HTML del cuerpo (multipart/alternative). Quien llama es responsable de un HTML seguro.
`reply_to`	string	opcional	Dirección del encabezado Reply-To.
`attachments`	array	opcional	Adjuntos de archivo. Cada elemento: { filename, mime_type, data (base64) }. Máximo 20 elementos, 10 MB en total.

reply_to_emailsend:email

Envía una respuesta a un correo existente. Los encabezados de hilo (In-Reply-To, References) se establecen automáticamente. Admite responder a todos y adjuntos.

Parámetro	Tipo	Obligatorio	Descripción
`inbox_id`	string (uuid)	obligatorio	UUID de la bandeja que contiene el mensaje original. Llama a list_inboxes para obtener los IDs de bandeja disponibles.
`message_id`	string	obligatorio	ID de mensaje del proveedor del correo al que se responde.
`body`	string	obligatorio	Cuerpo de la respuesta en texto plano.
`html_body`	string	opcional	Versión HTML opcional de la respuesta.
`reply_all`	boolean	opcional	Responder a todos los destinatarios originales (Para + Cc). Predeterminado false.
`attachments`	array	opcional	Adjuntos de archivo. Mismo esquema que send_email. Máximo 20 elementos.

Códigos de error

Códigos de error y guía de reintentos.

Los fallos de autenticación, alcance y límite de tasa devuelven un objeto error JSON-RPC con un código numérico. Los fallos de ejecución de herramientas (bandeja no encontrada, error del proveedor, etc.) devuelven un result normal con isError: true y un mensaje legible en content[0].text.

Código	Tipo	Cuándo ocurre	Reintentable
`-32001`	JSON-RPC error	Clave de API ausente, malformada, revocada o caducada. También se devuelve cuando la clave de API carece del alcance requerido para la herramienta llamada.	No
`-32601`	JSON-RPC error	Método JSON-RPC desconocido (p. ej. llamar a un método distinto de initialize, tools/list, tools/call)	No
`-32602`	JSON-RPC error	Nombre de herramienta desconocido, o parámetro ausente / inválido en tools/call	No
`-32029`	JSON-RPC error	Límite de tasa por clave o cuota diaria del plan superados. Revisa data.error_code: "rate_limit_exceeded" vs "quota_exceeded". Revisa data.retry_after (segundos) antes de reintentar.
`isError: true`	Tool result	La herramienta se ejecutó pero encontró un error (bandeja no encontrada, mensaje no encontrado, fallo de autenticación del proveedor, destinatario inválido, adjunto demasiado grande, 5xx del proveedor). La descripción del error está en content[0].text.	No

Ejemplo de respuesta de error de ejecución

json

// Tool execution error: inbox not found
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "Inbox not found or not accessible." }],
    "isError": true
  }
}

// Rate limit error: JSON-RPC error object with data
{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32029,
    "message": "Rate limit exceeded",
    "data": {
      "error_code": "rate_limit_exceeded",
      "window": "per_minute",
      "limit": 100,
      "used": 100,
      "retry_after": 34
    }
  }
}

Límites de tasa

Límites de tasa y cuotas.

Ventanas móviles por clave

100 pet / min · 1.000 / h · 10.000 / día

Aplicados por clave de API independientemente del plan. Cuando se superan, el servidor devuelve el código de error -32029 con data.error_code: "rate_limit_exceeded" y un campo data.retry_after (segundos). Respeta ese valor antes de reintentar.

Tope por minuto del plan

Gratis 60 / min · Solo 300 / min · Team 1.000 / min

El uso es ilimitado; este es un límite de ráfaga de uso justo por espacio de trabajo (agregado entre todas tus claves de API). Cuando se supera, las llamadas devuelven data.error_code: "rate_limit_exceeded" con data.window: "per_minute" y una cuenta atrás data.retry_after (segundos). Mejora tu plan para un tope más alto.

Reintentar de forma segura

Respeta siempre retry_after; nunca reintentes envíos a ciegas

Para errores rate_limit_exceeded, espera data.retry_after segundos antes de reintentar. Usa retroceso exponencial para provider_error. No reintentes automáticamente send_email ante provider_error, ya que el mensaje puede haber sido aceptado por el proveedor.

¿Listo para conectar tu bandeja de entrada?

Empieza en el plan Gratis: ilimitado, sin tarjeta. Mejora a Solo o Team para límites de ráfaga más altos y funciones de equipo.

Empieza gratis Ver precios

Tu agente tiene una bandeja de entradaen cuatro pasos.