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
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 Authorizationdel MCP remoto. Solo da las 21 herramientas de consulta y envío.
Conectar con OAuth (recomendado)
Añades el servidor en tu cliente con la URL https://api.vemudo.com/mcp.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). Vemudo te enseña qué cliente pide acceso, a qué dirección volverá y te deja elegir la organización, el entorno ( testolive) 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.Al aceptar vuelves al cliente y la conexión queda lista.
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
Abre Customize > Connectors (en la interfaz en español, los nombres de los menús pueden aparecer traducidos). Pulsa Add y después Add custom connector. Escribe un nombre (por ejemplo, Vemudo) y la URL https://api.vemudo.com/mcp, y pulsa Continue.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. Pulsa Add y después Connect para abrir la autorización de Vemudo.
Claude Code
claude mcp add --transport http vemudo https://api.vemudo.com/mcp/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.
--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)
~/.codex/config.toml (o a .codex/config.toml de un proyecto de confianza):
[mcp_servers.vemudo]
url = "https://api.vemudo.com/mcp"codex mcp login vemudocodex 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
.cursor/mcp.json en tu proyecto, o ~/.cursor/mcp.json para todos:
{
"mcpServers": {
"vemudo": { "url": "https://api.vemudo.com/mcp" }
}
}VS Code
.vscode/mcp.json en tu espacio de trabajo (o usa el comando MCP: Add Server y elige HTTP):
{
"servers": {
"vemudo": { "type": "http", "url": "https://api.vemudo.com/mcp" }
}
}Otro cliente con OAuth
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
mcp:read | read. | ||
mcp:send | send. | ||
mcp:write | full más esas escrituras. | ||
mcp:keys |
test y añade permisos cuando los necesites: para cambiarlos, desconecta y vuelve a autorizar.
Ver y revocar conexiones
Conectar con una clave de API
Qué clave usar
read | live (o test para probar) | |
full | test | |
send |
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
https://api.vemudo.com/mcp y manda la clave en la cabecera Authorization: Bearer vm_live_.... En Claude Code, por ejemplo:
claude mcp add --transport http vemudo https://api.vemudo.com/mcp \
--header "Authorization: Bearer $VEMUDO_API_KEY"Herramientas
whoami | |||
get_account | read | mcp:read | |
send_email | replyTo, etiquetas, scheduledAt, idempotencyKey). | send | mcp:send |
send_batch | send_email menos attachments y scheduledAt. | send | mcp:send |
cancel_email | confirm: true. | send | mcp:send |
list_emails | read | mcp:read | |
get_email | send solo los creados con esa misma clave. | send o read | mcp:send o mcp:read |
get_email_events | read | mcp:read | |
get_stats | read | mcp:read | |
list_campaigns, get_campaign | read | mcp:read | |
list_domains, get_domain | read | mcp:read | |
list_contacts, get_contact, list_lists, list_segments | read | mcp:read | |
list_templates, get_template | read | mcp:read | |
list_suppressions, list_webhooks | read | mcp:read | |
mcp:write | |||
list_api_keys, create_api_key, revoke_api_key | mcp:keys |
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.
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.
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 ( testolive). 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/v1no autentican.Claves creadas por la IA. El secreto de una clave creada con create_api_keyse 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)
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.
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.
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.
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"}'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":{}}}'/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.
GET https://api.vemudo.com/v1/openapi.json sirve el contrato OpenAPI completo, sin clave, cacheable durante 1 hora.
/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
codex mcp login vemudo --no-browser). | |
live | test o verifica un dominio. |
oauth_connection_limit al autorizar | |
whoami. | |
invalid_api_key | |
404 not_found | test no ve emails live). |
429 rate_limited | Retry-After. |