Servidor MCP do Notifica

🤖 IA nativa: Controle sua infraestrutura de notificações através de assistentes de IA

Envie notificações, gerencie templates, analise métricas e muito mais — tudo via linguagem natural no seu editor de código.

O que é MCP?

Model Context Protocol (MCP) é um protocolo aberto desenvolvido pela Anthropic que permite que assistentes de IA (como Claude, Cursor, Windsurf) interajam nativamente com APIs e ferramentas externas.

O Servidor MCP do Notifica expõe toda a API do Notifica como ferramentas que sua IA pode invocar diretamente. Isso significa que você pode:

Enviar notificações conversacionalmente: "Envie um WhatsApp de boas-vindas para +5511999999999"
Debugar problemas de entrega: "Por que essa notificação falhou?"
Gerenciar templates: "Crie um template de email para redefinição de senha..."
Consultar analytics: "Qual minha taxa de entrega esta semana?"

Vantagens:

✅ Zero context switch — tudo dentro do seu editor
✅ Menos boilerplate — a IA escreve as chamadas de API
✅ Debug mais rápido — consulte status sem abrir o dashboard
✅ Iteração ágil — teste templates diretamente via chat

Instalação

Passo 1: Obter API Key

Acesse o Dashboard do Notifica
Vá em Configurações → API Keys
Clique em Criar API Key
Dê um nome descritivo (ex: mcp-local)
Copie a key (começa com nk_live_... ou nk_test_...)

dica

Para desenvolvimento, use uma key de teste (nk_test_...) para evitar cobranças e envios reais.

Passo 2: Configurar seu Assistente de IA

Escolha seu editor/assistente:

Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "notifica": {
      "command": "npx",
      "args": ["-y", "@notifica/mcp@latest"],
      "env": {
        "NOTIFICA_API_KEY": "nk_live_..."
      }
    }
  }
}

Cursor

Edite ~/.cursor/mcp.json (crie se não existir):

{
  "mcpServers": {
    "notifica": {
      "command": "npx",
      "args": ["-y", "@notifica/mcp@latest"],
      "env": {
        "NOTIFICA_API_KEY": "nk_live_..."
      }
    }
  }
}

Windsurf

Adicione à sua configuração de MCP do Windsurf:

{
  "mcpServers": {
    "notifica": {
      "command": "npx",
      "args": ["-y", "@notifica/mcp@latest"],
      "env": {
        "NOTIFICA_API_KEY": "nk_live_..."
      }
    }
  }
}

informação

Modo local vs hospedado:

Local (acima): O servidor roda via npx no seu computador
SSE (Server-Sent Events): Para ambientes hospedados, use o endpoint SSE do Notifica (em breve)

Passo 3: Reiniciar o Assistente

Reinicie completamente seu editor/assistente para carregar a nova configuração.

Para verificar se funcionou, pergunte:

Você: Quais ferramentas do Notifica estão disponíveis?
IA: Tenho acesso a 52 ferramentas do Notifica, organizadas em:
    • Notificações (4 ferramentas)
    • Templates (6 ferramentas)
    • Workflows (5 ferramentas)
    • Assinantes (8 ferramentas)
    • SMS (7 ferramentas)
    • Analytics (3 ferramentas)
    • Billing (4 ferramentas)
    • Domínios (4 ferramentas)
    • Webhooks (4 ferramentas)
    • Inbox Embed (3 ferramentas)
    • Inbox Público (4 ferramentas)

Ferramentas Disponíveis

O servidor MCP expõe 52 ferramentas organizadas por módulo:

📤 Notificações (4 ferramentas)

Ferramenta	Descrição
`notifica_notification_send`	Envia notificação (email, WhatsApp, SMS, in-app)
`notifica_notification_list`	Lista notificações com filtros
`notifica_notification_get`	Busca detalhes de uma notificação
`notifica_notification_list_attempts`	Lista tentativas de entrega (debug)

📝 Templates (6 ferramentas)

Ferramenta	Descrição
`notifica_template_list`	Lista todos os templates
`notifica_template_get`	Busca detalhes de um template
`notifica_template_preview`	Preview de template com dados de exemplo
`notifica_template_validate`	Valida sintaxe do template
`notifica_template_create`	Cria novo template
`notifica_template_update`	Atualiza template existente

🔄 Workflows (5 ferramentas)

Ferramenta	Descrição
`notifica_workflow_list`	Lista workflows automatizados
`notifica_workflow_get`	Busca detalhes de um workflow
`notifica_workflow_trigger`	Dispara workflow para um destinatário
`notifica_workflow_run_get`	Verifica status de execução
`notifica_workflow_run_cancel`	Cancela workflow em execução

👥 Assinantes (8 ferramentas)

Ferramenta	Descrição
`notifica_subscriber_list`	Lista assinantes
`notifica_subscriber_get`	Busca detalhes de um assinante
`notifica_subscriber_create`	Cria/atualiza assinante (upsert)
`notifica_subscriber_update`	Atualiza assinante existente
`notifica_subscriber_get_preferences`	Busca preferências de notificação
`notifica_subscriber_update_preferences`	Atualiza preferências
`notifica_subscriber_get_unread_count`	Conta notificações não lidas
`notifica_subscriber_bulk_import`	Importa múltiplos assinantes

📱 SMS (7 ferramentas)

Ferramenta	Descrição
`notifica_sms_provider_list`	Lista provedores SMS configurados
`notifica_sms_provider_get`	Busca detalhes de um provedor
`notifica_sms_provider_create`	Adiciona novo provedor SMS
`notifica_sms_provider_test`	Testa provedor com SMS real
`notifica_sms_compliance_get`	Configurações de compliance (LGPD)
`notifica_sms_consent_summary`	Estatísticas de consentimento
`notifica_sms_consent_get`	Status de consentimento de um número

📊 Analytics (3 ferramentas)

Ferramenta	Descrição
`notifica_analytics_overview`	Métricas gerais de entrega
`notifica_analytics_by_channel`	Métricas por canal
`notifica_analytics_top_templates`	Templates mais usados

💳 Billing (4 ferramentas)

Ferramenta	Descrição
`notifica_billing_subscription`	Status da assinatura
`notifica_billing_usage`	Uso vs quotas
`notifica_billing_invoices`	Histórico de faturas
`notifica_billing_payment_methods`	Métodos de pagamento

🌐 Domínios (4 ferramentas)

Ferramenta	Descrição
`notifica_domain_list`	Lista domínios de envio
`notifica_domain_get`	Detalhes de um domínio
`notifica_domain_get_health`	Verifica SPF/DKIM/DMARC
`notifica_domain_verify`	Dispara verificação DNS

🔗 Webhooks (4 ferramentas)

Ferramenta	Descrição
`notifica_webhook_list`	Lista webhooks configurados
`notifica_webhook_get`	Detalhes de um webhook
`notifica_webhook_get_deliveries`	Tentativas de entrega
`notifica_webhook_test`	Envia evento de teste

📬 Inbox Embed (3 ferramentas)

Ferramenta	Descrição
`notifica_inbox_embed_get_settings`	Configurações do widget embed
`notifica_inbox_embed_update_settings`	Atualiza configurações (tema, cores)
`notifica_inbox_embed_rotate_key`	Rotaciona chave de segurança

📥 Inbox Público (4 ferramentas)

Ferramenta	Descrição
`notifica_inbox_list_notifications`	Lista notificações in-app
`notifica_inbox_get_unread_count`	Conta não lidas
`notifica_inbox_mark_read`	Marca como lida
`notifica_inbox_mark_all_read`	Marca todas como lidas

dica

Para referência completa de parâmetros, veja o Guia de Referência de Ferramentas MCP.

Exemplos de Uso

Enviar Notificação

Você:

Envie um email de boas-vindas para [email protected] usando o template "welcome-v2"

IA:

Vou enviar o email. Confirmando:
• Canal: email
• Destinatário: [email protected]
• Template: welcome-v2

Enviando... ✅ Notificação criada!
ID: notif_abc123
Status: pending (aguardando processamento)
Estimativa de entrega: ~30 segundos

Verificar Status

Você:

Qual o status da notificação notif_abc123?

IA:

✅ Notificação entregue com sucesso!

ID: notif_abc123
Canal: email
Destinatário: [email protected]
Status: delivered
Enviado: 04/02/2025 às 14:30:02
Entregue: 04/02/2025 às 14:30:05
Aberto: Ainda não aberto
Provedor: Amazon SES

Listar Notificações Falhadas

Você:

Mostre as últimas 10 notificações que falharam

IA:

📋 Últimas 10 notificações com falha:

1. notif_xyz789 (email) - [email protected]
   Erro: Bounce - Email address does not exist
   Falhou em: 04/02/2025 14:25

2. notif_abc456 (sms) - +5511888888888
   Erro: Invalid phone number
   Falhou em: 04/02/2025 14:20

[... mais 8 notificações]

💡 Dica: Use `notifica_notification_list_attempts` para ver tentativas de re-envio.

Criar Template

Você:

Crie um template de email para confirmação de pedido com as variáveis: 
customer_name, order_id, total, items

IA:

Vou criar o template. Proposta:

Slug: order-confirmation
Nome: Confirmação de Pedido
Canal: email
Conteúdo:
---
Assunto: Pedido {{order_id}} confirmado! ✅

Olá {{customer_name}},

Seu pedido #{{order_id}} foi confirmado com sucesso!

Total: R$ {{total}}
Itens: {{items}}

Obrigado pela sua compra!
---

Variáveis: customer_name, order_id, total, items
Status inicial: draft

Posso criar?

Você:

Sim, crie

IA:

✅ Template criado com sucesso!
ID: tpl_xyz789
Slug: order-confirmation
Status: draft

Para ativar: atualize o status para "active" ou use o dashboard.

Analytics

Você:

Mostre as métricas de entrega dos últimos 7 dias

IA:

📊 Métricas de Entrega (Últimos 7 dias)

Total enviado: 1.245 notificações
Entregues: 1.198 (96.2%)
Falharam: 47 (3.8%)

Por canal:
📧 Email: 523 enviados, 98.5% entregues
💬 WhatsApp: 412 enviados, 94.2% entregues
📱 SMS: 310 enviados, 95.8% entregues
🔔 In-App: 0 enviados

Taxa de abertura (email): 42.3%
Taxa de clique (email): 18.7%

Debugar Falha de Entrega

Você:

Por que a notificação notif_xyz789 falhou?

IA:

🔍 Análise de Falha - notif_xyz789

Tentativas de entrega: 3

1️⃣ Primeira tentativa (04/02 14:30:00)
   Provedor: Amazon SES
   Erro: 421 Service unavailable
   Ação: Retry automático agendado

2️⃣ Segunda tentativa (04/02 14:32:00)
   Provedor: Amazon SES
   Erro: 550 Mailbox not found
   Ação: Bounce permanente - sem retry

3️⃣ Status final: bounced
   Motivo: Email address does not exist
   Destinatário: [email protected]

💡 Recomendação: Remova ou atualize o email do assinante para evitar futuros bounces.

Verificar Uso de Billing

Você:

Quanto do meu plano já usei este mês?

IA:

💳 Uso do Plano - Fevereiro 2025

Plano: Pro (R$ 199/mês)
Próxima renovação: 15/02/2025

Uso atual:
📧 Emails: 8.234 / 50.000 (16.5%)
📱 SMS: 1.456 / 5.000 (29.1%)
💬 WhatsApp: 3.012 / 10.000 (30.1%)

Status: Dentro do limite ✅
Projeção: Com base no uso atual, você ficará em ~45% do limite.

⚠️ Alerta: SMS está acima da média. Fique atento aos próximos dias.

Variáveis de Ambiente

Configure o comportamento do servidor MCP via variáveis de ambiente:

Variável	Obrigatória	Padrão	Descrição
`NOTIFICA_API_KEY`	✅ Sim	—	Sua API key (`nk_live_...` ou `nk_test_...`)
`NOTIFICA_BASE_URL`	Não	`https://app.usenotifica.com.br/v1`	URL base da API
`NOTIFICA_TIMEOUT`	Não	`30000`	Timeout de requisições (ms)
`NOTIFICA_MAX_RETRIES`	Não	`3`	Máximo de tentativas em caso de falha

Exemplo de configuração avançada:

{
  "mcpServers": {
    "notifica": {
      "command": "npx",
      "args": ["-y", "@notifica/mcp@latest"],
      "env": {
        "NOTIFICA_API_KEY": "nk_live_...",
        "NOTIFICA_TIMEOUT": "60000",
        "NOTIFICA_MAX_RETRIES": "5"
      }
    }
  }
}

Segurança

Escopo de API Keys

API keys podem ter escopos restritos. Para o MCP, recomendamos:

Desenvolvimento:

Use keys de teste (nk_test_...)
Escopo: read:* (somente leitura) se estiver apenas explorando
Escopo: write:notifications, write:templates para desenvolvimento completo

Produção:

Use keys de produção (nk_live_...) com escopo mínimo necessário
Exemplo: Se for apenas para analytics, use read:analytics
Nunca compartilhe keys em repositórios públicos

Ferramentas Read vs Write

O servidor MCP separa ferramentas em dois grupos:

Read-only (seguras):

*_list, *_get, *_preview, *_validate
Não alteram dados
Ideais para debugging e exploração

Write (requerem confirmação):

*_send, *_create, *_update, *_trigger
A IA sempre pede confirmação antes de:
- Enviar notificações para destinatários externos
- Disparar workflows
- Criar/atualizar recursos

aviso

Confirmação de envio: Por padrão, o servidor MCP pede confirmação antes de enviar notificações para destinatários externos. Isso evita envios acidentais durante desenvolvimento.

Rotação de Keys

Para rotacionar sua API key:

Crie uma nova key no dashboard
Atualize a configuração do MCP
Reinicie o assistente
Revogue a key antiga após confirmar que funciona

Troubleshooting

Ferramentas não aparecem na IA

Problema: A IA não reconhece as ferramentas do Notifica.

Soluções:

Reinicie completamente o assistente (fechar e abrir não é suficiente)
Verifique a configuração JSON — deve estar em mcpServers.notifica
Teste o comando manualmente:
```
npx @notifica/mcp@latest
```
Deve imprimir a lista de ferramentas disponíveis.
Verifique a API key — deve começar com nk_live_ ou nk_test_

Erro de autenticação

Problema: 401 Unauthorized ou Invalid API key.

Soluções:

Verifique se a key está correta — copie novamente do dashboard
Confirme que a key está ativa — pode ter sido revogada
Verifique o ambiente — nk_test_ só funciona em modo de teste

Timeout ao enviar notificações

Problema: Requisições demoram muito ou falham com timeout.

Soluções:

Aumente o timeout:
```
"env": {
  "NOTIFICA_TIMEOUT": "60000"
}
```

Verifique sua conexão — teste com curl:

curl -H "Authorization: Bearer nk_live_..." \
  https://app.usenotifica.com.br/v1/notifications

Use modo assíncrono — as notificações são processadas em background

Notificações não são enviadas

Problema: Notificação criada, mas não entregue.

Soluções:

Verifique o status com notifica_notification_get
Veja as tentativas com notifica_notification_list_attempts
Confirme configuração do canal:
- Email: domínio verificado + SPF/DKIM configurados
- SMS: provedor configurado e ativo
- WhatsApp: template aprovado (para templates)

Ferramentas retornam erros 404

Problema: 404 Not Found ao chamar ferramentas.

Soluções:

Verifique o NOTIFICA_BASE_URL — deve ser https://app.usenotifica.com.br/v1 (com /v1)
Confirme que o recurso existe — ex: notificação com ID válido
Verifique permissões da API key — pode não ter acesso ao recurso

Próximos Passos

Agora que você tem o MCP configurado, explore:

Recurso	Descrição
Referência de Ferramentas MCP	Documentação completa de todas as 52 ferramentas
Envio de Notificações	Guia completo da API de notificações
Templates	Como criar e gerenciar templates
Workflows	Automações multi-step
Analytics	Dashboard de métricas

FAQ

P: O MCP funciona com outros assistentes além de Claude?
R: Sim! Cursor, Windsurf, e qualquer ferramenta compatível com MCP.

P: Posso usar em produção?
R: Sim, mas use API keys com escopos restritos e confirme sempre antes de enviar notificações.

P: Há custo adicional pelo MCP?
R: Não! O MCP é apenas uma interface para a API. Você paga pelos recursos consumidos (notificações, SMS, etc).

P: Posso criar meu próprio servidor MCP?
R: Sim! O servidor é open-source. Veja o repositório no GitHub.

P: Como contribuir com novas ferramentas?
R: Abra uma issue ou PR no repositório. Aceitamos contribuições!

🚀 Pronto para começar? Configure seu assistente e comece a controlar o Notifica via IA hoje mesmo!

O que é MCP?​

Instalação​

Passo 1: Obter API Key​

Passo 2: Configurar seu Assistente de IA​

Claude Desktop​

Cursor​

Windsurf​

Passo 3: Reiniciar o Assistente​

Ferramentas Disponíveis​

📤 Notificações (4 ferramentas)​

📝 Templates (6 ferramentas)​

🔄 Workflows (5 ferramentas)​

👥 Assinantes (8 ferramentas)​

📱 SMS (7 ferramentas)​

📊 Analytics (3 ferramentas)​

💳 Billing (4 ferramentas)​

🌐 Domínios (4 ferramentas)​

🔗 Webhooks (4 ferramentas)​

📬 Inbox Embed (3 ferramentas)​

📥 Inbox Público (4 ferramentas)​

Exemplos de Uso​

Enviar Notificação​

Verificar Status​

Listar Notificações Falhadas​

Criar Template​

Analytics​

Debugar Falha de Entrega​

Verificar Uso de Billing​

Variáveis de Ambiente​

Segurança​

Escopo de API Keys​

Ferramentas Read vs Write​

Rotação de Keys​

Troubleshooting​

Ferramentas não aparecem na IA​

Erro de autenticação​

Timeout ao enviar notificações​

Notificações não são enviadas​

Ferramentas retornam erros 404​

Próximos Passos​

FAQ​

O que é MCP?

Instalação

Passo 1: Obter API Key

Passo 2: Configurar seu Assistente de IA

Claude Desktop

Cursor

Windsurf

Passo 3: Reiniciar o Assistente

Ferramentas Disponíveis

📤 Notificações (4 ferramentas)

📝 Templates (6 ferramentas)

🔄 Workflows (5 ferramentas)

👥 Assinantes (8 ferramentas)

📱 SMS (7 ferramentas)

📊 Analytics (3 ferramentas)

💳 Billing (4 ferramentas)

🌐 Domínios (4 ferramentas)

🔗 Webhooks (4 ferramentas)

📬 Inbox Embed (3 ferramentas)

📥 Inbox Público (4 ferramentas)

Exemplos de Uso

Enviar Notificação

Verificar Status

Listar Notificações Falhadas

Criar Template

Analytics

Debugar Falha de Entrega

Verificar Uso de Billing

Variáveis de Ambiente

Segurança

Escopo de API Keys

Ferramentas Read vs Write

Rotação de Keys

Troubleshooting

Ferramentas não aparecem na IA

Erro de autenticação

Timeout ao enviar notificações

Notificações não são enviadas

Ferramentas retornam erros 404

Próximos Passos

FAQ