Novu MCP Server

Novu MCP Server

Visite nosso repositório principal no GitHub »

✨ Recursos

Um único servidor MCP que desbloqueia todo o seu espaço de trabalho Novu para agentes de IA:

• Agentes — crie, liste, inspecione, atualize agentes Novu e transfira a conexão de canal para o playbook da CLI Novu
• Conversas — liste threads de agentes e inspecione linhas do tempo de atividade (mensagens, aprovações, conexões MCP)
• Notificações — busque e filtre eventos com logs de execução completos e status de entrega
• Assinantes — pesquise e gerencie destinatários por e-mail, telefone, nome ou ID
• Fluxos de trabalho — liste, inspecione, crie, atualize e dispare fluxos de trabalho de notificação
• Preferências — leia e atualize preferências de canal do assinante (e-mail, SMS, in-app, push, chat)
• Ambientes — visualize ambientes e suas configurações
• Integrações — gerencie integrações de provedores entre canais
• Autenticação e Identidade — whoami verifica sua credencial (OAuth ou chave de API) e informa a região ativa

🚀 Início Rápido

Você não precisa hospedar nada — o servidor é totalmente gerenciado. Escolha o endpoint para a sua região do Novu Cloud e aponte seu cliente MCP para ele:

Cada host é uma implantação dedicada vinculada à sua região — não há mais o parâmetro de consulta ?region=. (Para compatibilidade reversa, um ?region= que não corresponde à região do host retorna um 400 apontando você para o endpoint correto.)

Autenticação

O servidor suporta duas formas de autenticação, e ambas funcionam de forma idêntica em qualquer endpoint regional:

1. OAuth (recomendado) — Sem chave de API para copiar/colar. Quando seu cliente MCP se conecta pela primeira vez, o servidor responde com um 401 e um documento de descoberta OAuth (/.well-known/oauth-protected-resource) que aponta o cliente para o servidor de autorização da Novu (Clerk). Seu cliente abre a tela de login + consentimento da Novu, você escolhe uma organização, e o cliente recebe um token de acesso automaticamente.

Qualquer cliente MCP que suporte OAuth remoto (Cursor, Claude, ChatGPT, Windsurf, …) lida com esse fluxo para você — basta adicionar a URL do servidor sem cabeçalho.

Nota: o cliente deve solicitar o escopo user:org:read (anunciado no documento de descoberta) para que a API Novu possa resolver sua organização. Se sua conta Novu pertencer a várias organizações, você será solicitado a selecionar uma durante o consentimento.

2. Chave de API — Forneça sua chave do Painel Novu como um token bearer:

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

Quando você apresenta uma chave de API, o servidor trata a sessão como modo de chave de API e não acionará o fluxo de login OAuth — mesmo nos endpoints hospedados. A chave está vinculada a um único ambiente (e, portanto, região), então nenhuma configuração extra é necessária; basta conectar ao endpoint da região onde sua conta reside.

Novu auto-hospedado? OAuth está disponível apenas para Novu Cloud (EUA/UE) — o fluxo é executado contra o servidor de autorização do Novu Cloud, ao qual uma implantação auto-hospedada não tem acesso. Implantações auto-hospedadas sempre autenticam com uma chave de API. Consulte Implantando sua própria instância e Desenvolvimento Local.

🎯 Ambientes

Como as solicitações são mapeadas para um ambiente Novu depende de como você autentica:

• Chave de API — a própria chave está vinculada a um único ambiente; as solicitações sempre são executadas nesse ambiente.
• OAuth — o token está vinculado à sua organização, e a API Novu usa como padrão o ambiente de Desenvolvimento.

Para sessões OAuth, toda ferramenta aceita um parâmetro opcional environmentId para direcionar um ambiente específico (encaminhado para a API Novu como o cabeçalho Novu-Environment-Id). Chame get_environments primeiro para listar seus ambientes, depois passe o _id do que você deseja — por exemplo, para inspecionar notificações de Produção. A API Novu valida que o ambiente pertence à sua organização. Com uma chave de API, o parâmetro é ignorado — a chave já fixa o ambiente.

API local / auto-hospedada — para apontar este servidor MCP para uma API Novu em execução em outro lugar (por exemplo, uma instância auto-hospedada em http://localhost:3000), defina NOVU_API_URL em .dev.vars e execute o servidor localmente (consulte Desenvolvimento Local). Isso substitui o antigo parâmetro de consulta ?region=local. Auto-hospedado sempre usa chave de API — OAuth é apenas para Novu Cloud.

🛠️ Uso

O servidor fala o transporte MCP HTTP Streamable em https://mcp.novu.co/ (EUA) e https://eu.mcp.novu.co/ (UE).

Cursor, Windsurf, Claude e outros clientes com capacidade OAuth

Qualquer cliente que suporte servidores MCP remotos com OAuth pode conectar sem cabeçalho — o cliente executa o fluxo de login para você:

• URL (EUA): https://mcp.novu.co/
• URL (UE): https://eu.mcp.novu.co/

Na primeira conexão, o cliente abre a tela de login + consentimento da Novu. Aprove-a, selecione sua organização, e as ferramentas aparecem automaticamente.

Chave de API (clientes mcp-remote / stdio, Novu auto-hospedado)

Para clientes que suportam apenas transportes stdio, se você preferir uma chave de API estática, ou se você executar uma instância Novu auto-hospedada (onde OAuth não está disponível), use o proxy mcp-remote com um cabeçalho Authorization. Apresentar uma chave de API impede que o cliente inicie o fluxo OAuth:

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

Para a região da UE, troque a URL por https://eu.mcp.novu.co/.

📦 Ferramentas Disponíveis

💻 Desenvolvimento Local

Pré-requisitos: Node.js 20+ e 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

O servidor é executado em http://localhost:8787. Aponte seu cliente MCP para ele da mesma forma que faria com a versão hospedada:

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

A configuração é lida de .dev.vars (ignorado pelo git) — copie .dev.vars.example para começar. As variáveis-chave são:

• NOVU_API_URL — a API Novu para a qual este servidor faz proxy (ex.: http://localhost:3000 para uma API auto-hospedada, ou https://api.novu.co / https://eu.api.novu.co para cloud).
• NOVU_REGION — o rótulo de exibição apresentado por whoami.
• CLERK_OAUTH_ISSUER — o servidor de autorização Clerk para OAuth. Deixe vazio para desabilitar OAuth completamente e executar apenas com chave de API (o modo auto-hospedado).

Para desenvolvimento local contra uma API Novu auto-hospedada em http://localhost:3000, defina NOVU_API_URL="http://localhost:3000" em .dev.vars e use a chave de API da sua instância (OAuth é apenas para Novu Cloud):

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

OAuth no desenvolvimento local

Para exercitar OAuth localmente, defina CLERK_OAUTH_ISSUER em .dev.vars para um servidor de autorização Clerk que sua API Novu confie (ex.: https://clerk.dashboard.novu.co para EUA). A origem do endpoint MCP é derivada da URL da solicitação, então execute o servidor de desenvolvimento e aponte seu cliente MCP para a mesma URL (ex.: http://localhost:8787/). O RFC 9728 exige que o campo PRM resource corresponda exatamente à URL do endpoint MCP; conectar via um host/porta diferente do qual o servidor está vinculado faz com que clientes como Cursor descartem os metadados e registrem sem o escopo user:org:read.

Quando CLERK_OAUTH_ISSUER está vazio, os endpoints de descoberta OAuth retornam 404 e as respostas 401 omitem os metadados OAuth, então os clientes recorrem à autenticação por chave de API.

Implantando sua própria instância

O servidor é um Worker padrão do Cloudflare. wrangler.jsonc é organizado para que a configuração de nível superior seja apenas para desenvolvimento local (sem routes, então wrangler dev serve em localhost e a descoberta OAuth anuncia a origem localhost), enquanto implantações reais vivem sob ambientes nomeados:

• 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 implantar sua própria instância, faça um fork do repositório e adicione um ambiente sob env (ou edite um existente) com seu próprio routes, NOVU_API_URL e NOVU_REGION, depois implante com wrangler deploy --env <name>. Uma instância auto-implantada funciona imediatamente com autenticação por chave de API contra o que NOVU_API_URL aponta — incluindo uma API Novu auto-hospedada. OAuth na sua própria implantação requer definir o segredo CLERK_OAUTH_ISSUER (wrangler secret put CLERK_OAUTH_ISSUER --env <name>) para um servidor de autorização que sua API Novu confie; deixe não definido para apenas chave de API.

Scripts

• pnpm dev — Executa o worker localmente via Wrangler (configuração de nível superior, sem rotas)
• pnpm deploy — Implanta o worker dos EUA (mcp.novu.co, --env us)
• pnpm deploy:eu — Implanta o worker da UE (eu.mcp.novu.co, --env eu)
• pnpm type-check — Executa a verificação de tipos TypeScript
• pnpm lint:fix — Corrige problemas de lint com Biome
• pnpm format — Formata o código com Biome

Estrutura do projeto

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

Adicione novas ferramentas criando uma função register*Tools sob src/tools/ e conectando-a em src/server/NovuMCP.ts.

🔒 Segurança

• O servidor é um pass-through OAuth puro: ele não emite, troca ou re-assina tokens. Ele nunca valida tokens por conta própria — ele anuncia o servidor de autorização Clerk da Novu e encaminha o cabeçalho Authorization do chamador verbatim para a API da Novu, que o valida e resolve a organização/permissões.
• Tokens de acesso OAuth (tokens opacos oat_… do Clerk) são de curta duração e revogáveis pelo lado da Novu, portanto são muito mais seguros do que uma chave de API de longa duração.
• Seja token OAuth ou chave de API legada, a credencial é limitada à sua sessão MCP: ela é entregue ao Durable Object da sessão via canal de props do runtime — nunca colocada em URLs, onde vazaria para logs de requisição — e é descartada com a sessão. O servidor não mantém credenciais ambientais.
• Nunca faça commit de chaves de API ou configuração do emissor. Use .dev.vars para valores locais (já ignorados pelo git).
• Trate sua chave de API da Novu como uma senha — rotacione-a pelo dashboard se suspeitar que ela foi exposta.

🤝 Contribuindo

1. Faça as Alterações

   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. Abra um Pull Request

   • Use um título descritivo com prefixo feat:, fix:, docs: ou chore:
   • Inclua uma descrição curta da alteração e, quando relevante, um exemplo de chamada de ferramenta

Diretrizes:

• Mantenha as descrições das ferramentas concisas — elas são exibidas verbatim para LLMs
• Valide entradas com esquemas Zod em src/utils/
• Prefira os helpers ToolFactory para endpoints CRUD padrão
• Algo faltando? Abra uma issue no GitHub

Precisa de ajuda? Envie um e-mail para support@novu.co ou entre no Discord.

Obrigado por contribuir! 🙏