Saltar al contenido

MCP y asistentes de IA

Conecta claude.ai, Claude Desktop, Claude Code, Codex, Cursor, VS Code u otro cliente MCP a tu cuenta de Vemudo con OAuth (sin claves) o con una clave de API.

Por Equipo Vemudo · Actualizado el

Vemudo tiene un servidor del Model Context Protocol (se abre en una pestaña nueva) que deja a un asistente de IA (Claude, Codex, Cursor, Copilot en VS Code...) trabajar con tu cuenta de Vemudo: consultarla, enviar emails y, si se lo permites, gestionarla. Puedes pedirle cosas como «¿cuántos emails rebotaron esta semana?», «¿qué campañas tengo programadas?» o «crea una clave de prueba solo de lectura para mi CI».

Hay dos formas de conectarlo:

  • Con OAuth (recomendado): en tu cliente solo pones la URL https://api.vemudo.com/mcp. Al conectar se abre el navegador, entras en Vemudo y eliges organización, entorno y permisos. No copias ninguna clave y tienes acceso a todas las herramientas, incluidas las de escritura y las de claves de API.
  • Con una clave de API: la clave va en la cabecera Authorization del MCP remoto. Solo da las 21 herramientas de consulta y envío.

Conectar con OAuth (recomendado)

El servidor MCP remoto implementa la autorización de MCP con OAuth 2.1: descubrimiento automático del servidor de autorización, registro dinámico del cliente y PKCE. No tienes que crear nada en el panel antes de conectar. El proceso es el mismo en todos los clientes:

  1. Añades el servidor en tu cliente con la URL https://api.vemudo.com/mcp.
  2. Al conectar, el cliente abre el navegador en Vemudo. Si no tienes sesión, entras como siempre (con tu segundo factor si lo tienes activado).
  3. Vemudo te enseña qué cliente pide acceso, a qué dirección volverá y te deja elegir la organización, el entorno (test o live) y los permisos. El nombre del cliente lo declara el propio cliente y Vemudo no lo verifica: comprueba que eres tú quien ha iniciado la conexión.
  4. Al aceptar vuelves al cliente y la conexión queda lista.

El entorno live solo se puede elegir si la organización está activa y tiene un dominio verificado. Cada organización admite hasta 10 conexiones activas a la vez.

claude.ai y Claude Desktop

En claude.ai la URL se añade como conector personalizado (custom connector). Según la documentación de Anthropic, con un plan individual (Free, Pro, Max) se hace así:

  1. Abre Customize > Connectors (en la interfaz en español, los nombres de los menús pueden aparecer traducidos).
  2. Pulsa Add y después Add custom connector.
  3. Escribe un nombre (por ejemplo, Vemudo) y la URL https://api.vemudo.com/mcp, y pulsa Continue.
  4. Deja los ajustes de autenticación que Claude marque como detectados. Si te pide elegir cómo se identifica el cliente OAuth, elige el registro automático (Register automatically). No hace falta client ID, secreto ni cabeceras.
  5. Pulsa Add y después Connect para abrir la autorización de Vemudo.

En los planes Team y Enterprise el conector lo añade un Owner desde la configuración de la organización y después cada miembro pulsa Connect con su propia cuenta de Vemudo.

El conector queda en tu cuenta de Claude, así que también lo tienes en Claude Desktop y en la app móvil sin repetir la configuración. Claude se conecta desde la nube de Anthropic, no desde tu ordenador. Dentro de una conversación puedes activar o desactivar el conector desde el botón +.

Claude Code

bash
claude mcp add --transport http vemudo https://api.vemudo.com/mcp

Después, dentro de Claude Code, escribe /mcp, elige vemudo y sigue los pasos en el navegador. También puedes autorizar desde la terminal con claude mcp login vemudo. Claude Code guarda los tokens y los renueva solo.

Por defecto queda disponible solo para ti en el proyecto actual. Añade --scope user para tenerlo en todos tus proyectos, o --scope project para guardarlo en el .mcp.json del repositorio (ahí solo va la URL: cada persona autoriza con su propia cuenta). Para cerrar la sesión usa claude mcp logout vemudo; para cortar la conexión también en Vemudo, revócala desde el panel (ver más abajo).

Codex (OpenAI)

Añade el servidor a ~/.codex/config.toml (o a .codex/config.toml de un proyecto de confianza):

toml
[mcp_servers.vemudo]
url = "https://api.vemudo.com/mcp"

Y autoriza:

bash
codex mcp login vemudo

Se abre el navegador con la autorización de Vemudo. En una terminal sin navegador, codex mcp login vemudo --no-browser imprime la dirección para abrirla en otro sitio. Dentro de Codex, /mcp muestra los servidores activos. La CLI, la extensión del editor y la app de escritorio de Codex comparten esta configuración.

Cursor

Crea .cursor/mcp.json en tu proyecto, o ~/.cursor/mcp.json para todos:

json
{
  "mcpServers": {
    "vemudo": { "url": "https://api.vemudo.com/mcp" }
  }
}

En Ajustes > MCP aparece Vemudo pidiendo inicio de sesión: pulsa para autorizar en el navegador.

VS Code

Crea .vscode/mcp.json en tu espacio de trabajo (o usa el comando MCP: Add Server y elige HTTP):

json
{
  "servers": {
    "vemudo": { "type": "http", "url": "https://api.vemudo.com/mcp" }
  }
}

Al arrancar el servidor, VS Code abre la autorización de Vemudo en el navegador.

Otro cliente con OAuth

Cualquier cliente que admita servidores MCP remotos (Streamable HTTP) con la autorización OAuth de MCP sirve igual: pon la URL https://api.vemudo.com/mcp y deja que el cliente haga el resto. Si tu cliente no admite OAuth, usa una clave de API.

Permisos

Al autorizar marcas uno o varios permisos. La pantalla solo ofrece los que permite tu rol en la organización, y Vemudo lo vuelve a comprobar en cada llamada: si te cambian el rol o sales de la organización, la conexión pierde lo que tu rol ya no permite.

PermisoNombre en la pantallaQué deja hacer al asistenteRol mínimo
mcp:readConsultarVer emails, eventos, estadísticas, dominios, contactos, listas, campañas, plantillas, bajas y webhooks. Equivale a una clave read.Cualquiera, también viewer
mcp:sendEnviar emailsEnviar y cancelar emails transaccionales. Equivale a una clave send.developer
mcp:writeGestionar la cuentaCrear y cambiar dominios, plantillas, contactos, listas, bajas, webhooks y campañas, incluido enviarlas. Equivale a full más esas escrituras.developer
mcp:keysGestionar claves APIListar, crear y revocar claves de API. El secreto de una clave nueva aparece en la conversación.owner, admin o developer

Empieza con Consultar en el entorno test y añade permisos cuando los necesites: para cambiarlos, desconecta y vuelve a autorizar.

Ver y revocar conexiones

Las conexiones se ven en el panel, en Claves de API > Conexiones de IA: cliente, persona que la autorizó, entorno, permisos, fecha de creación y último uso. Desconectar revoca al momento los tokens de esa conexión. Owner y admin ven y desconectan todas las de la organización; el resto de roles, solo las suyas.

Conectar con una clave de API

Si tu cliente no admite OAuth, o prefieres una credencial fija (un script, un agente sin navegador), usa una clave de API. Con una clave el asistente tiene solo las 21 herramientas de consulta y envío: las de escritura y las de claves de API exigen una conexión OAuth, porque una clave no gestiona claves.

El asistente hereda los permisos, el entorno y los límites de la clave: no puede ver nada que la clave no vea. La clave nunca se escribe en logs ni en las respuestas. No se expone el cuerpo de los emails: la API no lo devuelve.

Qué clave usar

Crea una clave solo para el asistente y dale el scope mínimo:

Quieres que el asistente...ScopeEntorno
Consulte estadísticas, emails, campañas y contactosreadlive (o test para probar)
Además envíe o cancele emailsfullEmpieza por test
Solo envíe emailssendSegún el caso

Recomendaciones:

  • Empieza con una clave read. Es la opción más segura: el asistente no puede enviar, cancelar ni modificar nada.
  • Si le das capacidad de envío, pruébalo antes con una clave test, que no envía correo real.
  • Revoca la clave desde el panel cuando dejes de usarla.

Clave en el MCP remoto

Usa la misma URL https://api.vemudo.com/mcp y manda la clave en la cabecera Authorization: Bearer vm_live_.... En Claude Code, por ejemplo:

bash
claude mcp add --transport http vemudo https://api.vemudo.com/mcp \
  --header "Authorization: Bearer $VEMUDO_API_KEY"

Con la cabecera puesta no hace falta autorizar en el navegador. Los detalles del protocolo están en Protocolo del MCP remoto.

Herramientas

El asistente solo ve las herramientas que permiten sus permisos: los scopes de la clave o los permisos de la conexión OAuth.

HerramientaQué haceCon claveCon OAuth
whoamiMuestra la organización, el entorno y los permisos.CualquieraCualquiera
get_accountResumen de la cuenta: plan, uso, límites y recuentos.readmcp:read
send_emailEnvía un email (remitente, destinatario, asunto, HTML o texto, o plantilla con variables, replyTo, etiquetas, scheduledAt, idempotencyKey).sendmcp:send
send_batchEnvía hasta 100 emails. Cada uno acepta los mismos campos que send_email menos attachments y scheduledAt.sendmcp:send
cancel_emailCancela un email programado. Exige confirm: true.sendmcp:send
list_emailsLista emails con filtros.readmcp:read
get_emailDetalle de un email. Con send solo los creados con esa misma clave.send o readmcp:send o mcp:read
get_email_eventsEventos de un email.readmcp:read
get_statsEstadísticas por día y tasas.readmcp:read
list_campaigns, get_campaignCampañas y sus métricas.readmcp:read
list_domains, get_domainDominios y sus registros DNS.readmcp:read
list_contacts, get_contact, list_lists, list_segmentsContactos, listas y segmentos.readmcp:read
list_templates, get_templatePlantillas publicadas.readmcp:read
list_suppressions, list_webhooksBajas y bloqueos, y endpoints de webhook.readmcp:read
Herramientas de escrituraDominios (crear, comprobar DNS, borrar), plantillas, contactos, listas, bajas, webhooks y campañas (borrador, programar, enviar y cancelar).Nomcp:write
list_api_keys, create_api_key, revoke_api_keyListar, crear y revocar claves de API, con las mismas reglas que el panel.Nomcp:keys

Con una clave full aparecen las 21 primeras. mcp:write equivale a full más las escrituras, así que también incluye la consulta y el envío; mcp:keys va aparte y ningún otro permiso lo incluye. La lista exacta de herramientas de cada conexión la da tools/list.

Las herramientas de solo lectura van marcadas así para el cliente. Las destructivas (como cancel_email, revoke_api_key o borrar un dominio) van marcadas como destructivas, de modo que tu cliente puede pedirte confirmación; además el servidor exige el campo confirm: true y sin él responde con validation_failed. create_api_key también exige confirm: true. Enviar una campaña solo se puede hacer desde una conexión live. send_email y send_batch no son idempotentes salvo que pases idempotencyKey.

Las respuestas devuelven el JSON de la API. Si la API responde con un error, la herramienta devuelve un resultado de error con el code y el detail (nunca la clave ni el token) para que el asistente pueda explicarlo.

Seguridad

  • Permisos mínimos. Una conexión o una clave en un asistente equivale a darle acceso a esas operaciones. Dale solo lo que necesita y empieza por test.
  • Un solo entorno por conexión. Cada conexión OAuth trabaja en el entorno que elegiste al autorizar (test o live). Para el otro entorno, crea otra conexión.
  • Tokens de corta duración. El token de acceso dura 1 hora y el cliente lo renueva solo con un token de refresco (30 días, de un solo uso). Si alguien reutiliza un token de refresco ya usado, Vemudo revoca la conexión entera. Los tokens OAuth solo valen en /mcp: en /v1 no autentican.
  • Claves creadas por la IA. El secreto de una clave creada con create_api_key se muestra una sola vez en el resultado de la herramienta, es decir, en la conversación con tu asistente, y por tanto pasa por tu proveedor de IA. Trátalo como un secreto que ese proveedor ya ha visto: si eso no es aceptable para una clave de producción, créala desde el panel. Guárdalo enseguida en tu gestor de secretos y revoca la clave si compartes la conversación. Cada alta queda en la auditoría de la organización como hecha desde MCP.
  • Revoca lo que no uses. Desconecta las conexiones desde Claves de API > Conexiones de IA y revoca las claves que ya no necesites. Quitar el servidor de tu cliente no siempre revoca los tokens en Vemudo.
  • Instrucciones en los datos. Un asistente puede equivocarse o seguir instrucciones que aparezcan en datos que lee (asuntos, etiquetas, nombres de contactos). Con solo Consultar o una clave read, ese riesgo no puede enviar correo ni cambiar nada. Revisa las confirmaciones que te pida tu cliente antes de aceptarlas.
  • No pegues claves en conversaciones ni las subas a un repositorio. Más sobre claves en Autenticación y claves.

Protocolo del MCP remoto (POST /mcp)

La API expone el protocolo MCP directamente por HTTP, sin instalar nada: POST https://api.vemudo.com/mcp con Authorization: Bearer <token OAuth o clave> y Content-Type: application/json. Con una clave son los mismos scopes y los mismos límites que /v1; una conexión OAuth tiene los mismos límites del plan.

Es Streamable HTTP sin sesiones ni SSE: cada petición es un único mensaje JSON-RPC 2.0 (se abre en una pestaña nueva) y la respuesta es siempre application/json. GET /mcp y DELETE /mcp no están soportados (no hay sesión que cerrar ni flujo que abrir) y devuelven 405. El cuerpo máximo es 1 MB y el resultado de una herramienta se recorta a 50 KB con truncated: true si lo supera.

Métodos admitidos: initialize (negocia protocolVersion, usa 2025-06-18), notifications/initialized, ping, tools/list y tools/call. Un método que no existe responde con el error JSON-RPC -32601 (Método desconocido), nunca con un estado HTTP de error. Un mensaje enviado como notificación (sin id) se acepta con 202 y sin cuerpo: tools/call no ejecuta la herramienta en ese caso, porque un envío cuyo resultado no se puede devolver tampoco se puede comprobar.

tools/list solo devuelve las herramientas que permiten los permisos de quien llama: con una clave read no aparecen send_email ni cancel_email, por ejemplo. Los errores de negocio de una herramienta (permiso insuficiente, validación, límite alcanzado...) llegan dentro de un resultado JSON-RPC válido, con isError: true en el resultado (y el Retry-After dentro de structuredContent cuando aplica si es un 429), no como error HTTP: la petición a /mcp ha funcionado, es la herramienta la que ha fallado.

bash
curl https://api.vemudo.com/mcp \
  -H "Authorization: Bearer $VEMUDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
bash
curl https://api.vemudo.com/mcp \
  -H "Authorization: Bearer $VEMUDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_account","arguments":{}}}'

OAuth, para quien programa un cliente: una petición a /mcp sin credenciales responde 401 con WWW-Authenticate: Bearer resource_metadata="...". Los metadatos están en https://api.vemudo.com/.well-known/oauth-protected-resource (recurso https://api.vemudo.com/mcp) y en https://api.vemudo.com/.well-known/oauth-authorization-server (RFC 8414), públicos y cacheables 1 hora. El registro dinámico de clientes (RFC 7591) está abierto a clientes públicos, sin secreto; las direcciones de vuelta tienen que ser https o de loopback (http://127.0.0.1 o http://localhost con puerto). Solo se admite el flujo de código de autorización con PKCE S256; el parámetro resource (RFC 8707), si se envía, debe ser https://api.vemudo.com/mcp, y los tokens se revocan en el endpoint de revocación (RFC 7009) que anuncian los metadatos.

Origin: un navegador solo puede llamar a /mcp si su origen está en la lista permitida de la plataforma (defensa contra DNS rebinding); un cliente de escritorio como Claude Desktop, Codex, Cursor o Claude Code no envía esa cabecera y siempre pasa.

Descubrimiento del contrato: GET https://api.vemudo.com/v1/openapi.json sirve el contrato OpenAPI completo, sin clave, cacheable durante 1 hora.

La fecha de disponibilidad de /mcp, de OAuth y de esta referencia pública está en el changelog de la API, junto con la política de cambios.

Problemas habituales

SíntomaCausa
No se abre el navegador al conectarCopia la dirección que muestra el cliente y ábrela a mano (en Codex, codex mcp login vemudo --no-browser).
La pantalla de Vemudo no deja elegir liveLa organización no está activa o no tiene un dominio verificado. Usa test o verifica un dominio.
Falta un permiso en la pantalla de autorizaciónTu rol en esa organización no lo permite (por ejemplo, viewer solo puede Consultar).
oauth_connection_limit al autorizarLa organización ya tiene 10 conexiones activas. Desconecta alguna en Claves de API > Conexiones de IA.
El cliente pide autorizar otra vezLa conexión se ha revocado o el token de refresco ha caducado. Vuelve a autorizar.
No aparece una herramientaLa clave o la conexión no tiene el permiso necesario, o la herramienta solo existe con OAuth. Usa whoami.
invalid_api_keyLa clave está mal copiada o se ha revocado.
Respuesta vacía o 404 not_foundLa clave o la conexión es de otro entorno (test no ve emails live).
429 rate_limitedSe ha superado un límite de la organización o del plan. Espera lo que indique Retry-After.