Novu MCP Server

Novu MCP Server

Visita nuestro repositorio principal de GitHub »

✨ Características

Un único servidor MCP que desbloquea todo tu espacio de trabajo de Novu para agentes de IA:

• Agentes — crea, lista, inspecciona y actualiza agentes de Novu, y transfiere la conexión de canales al playbook de la CLI de Novu
• Conversaciones — lista hilos de agentes e inspecciona líneas de tiempo de actividad (mensajes, aprobaciones, conexiones MCP)
• Notificaciones — obtén y filtra eventos con registros de ejecución completos y estado de entrega
• Suscriptores — busca y gestiona destinatarios por correo electrónico, teléfono, nombre o ID
• Flujos de trabajo — lista, inspecciona, crea, actualiza y activa flujos de trabajo de notificaciones
• Preferencias — lee y actualiza las preferencias de canal de los suscriptores (correo electrónico, SMS, en la aplicación, push, chat)
• Entornos — visualiza entornos y su configuración
• Integraciones — gestiona integraciones de proveedores en todos los canales
• Autenticación e identidad — whoami verifica tu credencial (OAuth o clave de API) e informa la región activa

🚀 Inicio rápido

No necesitas alojar nada: el servidor está completamente gestionado. Elige el endpoint para tu región de Novu Cloud y apunta tu cliente MCP hacia él:

Cada host es una implementación dedicada vinculada a su región: ya no existe el parámetro de consulta ?region=. (Para compatibilidad con versiones anteriores, un ?region= que no coincida con la región del host devuelve un 400 que te indica el endpoint correcto).

Autenticación

El servidor admite dos formas de autenticación, y ambas funcionan de manera idéntica en cualquier endpoint regional:

1. OAuth (recomendado) — Sin clave de API para copiar y pegar. Cuando tu cliente MCP se conecta por primera vez, el servidor responde con un 401 y un documento de descubrimiento OAuth (/.well-known/oauth-protected-resource) que apunta al cliente hacia el servidor de autorización de Novu (Clerk). Tu cliente abre la pantalla de inicio de sesión y consentimiento de Novu, eliges una organización y el cliente recibe un token de acceso automáticamente.

Cualquier cliente MCP que admita OAuth remoto (Cursor, Claude, ChatGPT, Windsurf, …) gestiona este flujo por ti: solo agrega la URL del servidor sin encabezado.

Nota: el cliente debe solicitar el alcance user:org:read (anunciado en el documento de descubrimiento) para que la API de Novu pueda resolver tu organización. Si tu cuenta de Novu pertenece a varias organizaciones, se te pedirá que selecciones una durante el consentimiento.

2. Clave de API — Proporciona tu clave desde el Panel de Novu como token de portador:

Authorization: Bearer <your-novu-api-key>

Cuando presentas una clave de API, el servidor trata la sesión como modo de clave de API y no activará el flujo de inicio de sesión OAuth, incluso en los endpoints alojados. La clave está vinculada a un único entorno (y por lo tanto región), por lo que no se necesita configuración adicional; solo conéctate al endpoint de la región donde vive tu cuenta.

¿Novu autoalojado? OAuth solo está disponible para Novu Cloud (US/EU): el flujo se ejecuta contra el servidor de autorización de Novu Cloud, al que una implementación autoalojada no tiene acceso. Las implementaciones autoalojadas siempre se autentican con una clave de API. Consulta Implementación de tu propia instancia y Desarrollo local.

🎯 Entornos

Cómo se asignan las solicitudes a un entorno de Novu depende de cómo te autentiques:

• Clave de API — la clave en sí está vinculada a un único entorno; las solicitudes siempre se ejecutan contra ese entorno.
• OAuth — el token está vinculado a tu organización, y la API de Novu usa por defecto el entorno de Desarrollo.

Para sesiones OAuth, cada herramienta acepta un parámetro opcional environmentId para apuntar a un entorno específico (reenviado a la API de Novu como el encabezado Novu-Environment-Id). Llama a get_environments primero para listar tus entornos, luego pasa el _id del que quieras, por ejemplo, para inspeccionar notificaciones de Producción. La API de Novu valida que el entorno pertenezca a tu organización. Con una clave de API, el parámetro se ignora: la clave ya fija el entorno.

API local / autoalojada — para apuntar este servidor MCP a una API de Novu que se ejecute en otro lugar (por ejemplo, una instancia autoalojada en http://localhost:3000), establece NOVU_API_URL en .dev.vars y ejecuta el servidor localmente (consulta Desarrollo local). Esto reemplaza el antiguo parámetro de consulta ?region=local. El autoalojamiento siempre usa una clave de API: OAuth es solo para Novu Cloud.

🛠️ Uso

El servidor habla el transporte MCP HTTP Streamable en https://mcp.novu.co/ (US) y https://eu.mcp.novu.co/ (EU).

Cursor, Windsurf, Claude y otros clientes compatibles con OAuth

Cualquier cliente que admita servidores MCP remotos con OAuth puede conectarse sin encabezado: el cliente ejecuta el flujo de inicio de sesión por ti:

• URL (US): https://mcp.novu.co/
• URL (EU): https://eu.mcp.novu.co/

En la primera conexión, el cliente abre la pantalla de inicio de sesión y consentimiento de Novu. Aprueba, selecciona tu organización y las herramientas aparecen automáticamente.

Clave de API (clientes mcp-remote / stdio, Novu autoalojado)

Para clientes que solo admiten transportes stdio, si prefieres una clave de API estática, o si ejecutas una instancia de Novu autoalojado (donde OAuth no está disponible), usa el proxy mcp-remote con un encabezado Authorization. Presentar una clave de API evita que el cliente inicie el flujo OAuth:

{
  "mcpServers": {
    "novu": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.novu.co/",
        "--header",
        "Authorization:Bearer your-novu-api-key"
      ]
    }
  }
}

Para la región EU, cambia la URL por https://eu.mcp.novu.co/.

📦 Herramientas disponibles

💻 Desarrollo local

Requisitos previos: Node.js 20+ y pnpm.

# Clone and install
git clone https://github.com/novuhq/novu-mcp-server.git
cd novu-mcp-server
pnpm install

# Start the local worker
pnpm dev

El servidor se ejecuta en http://localhost:8787. Apunta tu cliente MCP hacia él de la misma manera que lo harías con la versión alojada:

{
  "mcpServers": {
    "novu": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/",
        "--header",
        "Authorization:Bearer your-novu-api-key"
      ]
    }
  }
}

La configuración se lee desde .dev.vars (ignorado por git): copia .dev.vars.example para comenzar. Las variables clave son:

• NOVU_API_URL — la API de Novu a la que este servidor hace de proxy (por ejemplo, http://localhost:3000 para una API autoalojada, o https://api.novu.co / https://eu.api.novu.co para la nube).
• NOVU_REGION — la etiqueta de visualización que muestra whoami.
• CLERK_OAUTH_ISSUER — el servidor de autorización de Clerk para OAuth. Déjalo vacío para deshabilitar OAuth por completo y ejecutar solo con clave de API (el modo autoalojado).

Para desarrollo local contra una API de Novu autoalojada en http://localhost:3000, establece NOVU_API_URL="http://localhost:3000" en .dev.vars y usa la clave de API de tu instancia (OAuth es solo para Novu Cloud):

{
  "mcpServers": {
    "novu-local": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8787/",
        "--header",
        "Authorization:Bearer your-local-novu-api-key"
      ]
    }
  }
}

OAuth en desarrollo local

Para probar OAuth localmente, establece CLERK_OAUTH_ISSUER en .dev.vars a un servidor de autorización de Clerk que tu API de Novu confíe (por ejemplo, https://clerk.dashboard.novu.co para US). El origen del endpoint MCP se deriva de la URL de la solicitud, así que ejecuta el servidor de desarrollo y apunta tu cliente MCP a la misma URL (por ejemplo, http://localhost:8787/). RFC 9728 requiere que el campo PRM resource coincida exactamente con la URL del endpoint MCP; conectarse a través de un host/puerto diferente al que está vinculado el servidor hace que clientes como Cursor descarten los metadatos y se registren sin el alcance user:org:read.

Cuando CLERK_OAUTH_ISSUER está vacío, los endpoints de descubrimiento OAuth devuelven 404 y las respuestas 401 omiten los metadatos OAuth, por lo que los clientes recurren a la autenticación con clave de API.

Implementación de tu propia instancia

El servidor es un Worker estándar de Cloudflare. wrangler.jsonc está organizado para que la configuración de nivel superior sea solo para desarrollo local (sin routes, por lo que wrangler dev sirve en localhost y el descubrimiento OAuth anuncia el origen de localhost), mientras que las implementaciones reales viven bajo entornos con nombre:

• pnpm deploy → --env us (vincula mcp.novu.co, NOVU_API_URL=https://api.novu.co)
• pnpm deploy:eu → --env eu (vincula eu.mcp.novu.co, NOVU_API_URL=https://eu.api.novu.co)

Para implementar tu propia instancia, haz un fork del repositorio y agrega un entorno bajo env (o edita uno existente) con tu propio routes, NOVU_API_URL y NOVU_REGION, luego impleméntalo con wrangler deploy --env <name>. Una instancia autoimplementada funciona de inmediato con autenticación de clave de API contra lo que NOVU_API_URL apunte, incluida una API de Novu autoalojada. OAuth en tu propia implementación requiere establecer el secreto CLERK_OAUTH_ISSUER (wrangler secret put CLERK_OAUTH_ISSUER --env <name>) a un servidor de autorización que tu API de Novu confíe; déjalo sin establecer para solo clave de API.

Scripts

• pnpm dev — Ejecuta el worker localmente mediante Wrangler (configuración de nivel superior, sin rutas)
• pnpm deploy — Implementa el worker de US (mcp.novu.co, --env us)
• pnpm deploy:eu — Implementa el worker de EU (eu.mcp.novu.co, --env eu)
• pnpm type-check — Ejecuta la verificación de tipos de TypeScript
• pnpm lint:fix — Corrige problemas del linter con Biome
• pnpm format — Formatea el código con Biome

Estructura del proyecto

src/
├── index.ts            # Worker entry — auth extraction and routing
├── oauth.ts            # OAuth discovery, 401 bootstrap, initialize-time probe
├── server/NovuMCP.ts   # Durable Object hosting the MCP agent
├── tools/              # One file per tool group (workflows, subscribers, …)
├── utils/              # API client, validation, tool factory
└── types/              # Shared TypeScript types

Agrega nuevas herramientas creando una función register*Tools bajo src/tools/ y conéctala en src/server/NovuMCP.ts.

🔒 Seguridad

• El servidor es un paso directo de OAuth puro: no crea, intercambia ni vuelve a firmar tokens. Nunca valida tokens por sí mismo — anuncia el servidor de autorización Clerk de Novu y reenvía el encabezado Authorization del llamante tal cual a la API de Novu, que lo valida y resuelve la organización/permisos.
• Los tokens de acceso OAuth (tokens opacos oat_… de Clerk) son de corta duración y revocables desde el lado de Novu, por lo que son mucho más seguros que una clave API de larga duración.
• Ya sea un token OAuth o una clave API heredada, la credencial está limitada a tu sesión de MCP: se entrega al Objeto Durable de la sesión a través del canal de props del runtime — nunca se coloca en URLs, donde podría filtrarse en los registros de solicitudes — y se descarta con la sesión. El servidor no mantiene credenciales ambientales.
• Nunca confirmes claves API ni configuración del emisor. Usa .dev.vars para valores locales (ya ignorado por git).
• Trata tu clave API de Novu como una contraseña — gírala desde el panel si sospechas que ha sido expuesta.

🤝 Contribuciones

1. Haz cambios

   git checkout -b feat/your-change
   pnpm dev           # Test locally
   pnpm type-check    # Verify types
   git commit -m "feat: your change"
   git push origin feat/your-change
   

2. Abre una solicitud de extracción

   • Usa un título descriptivo con el prefijo feat:, fix:, docs: o chore:
   • Incluye una breve descripción del cambio y, cuando sea relevante, una llamada de herramienta de ejemplo

Pautas:

• Mantén las descripciones de herramientas concisas — se muestran tal cual a los LLMs
• Valida las entradas con esquemas Zod en src/utils/
• Prefiere los ayudantes ToolFactory para endpoints CRUD estándar
• ¿Falta algo? Abre un problema de GitHub

¿Necesitas ayuda? Escríbenos a support@novu.co o únete al Discord.

¡Gracias por contribuir! 🙏