> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Servidor MCP do OneSignal

> Conecte qualquer ferramenta ou agente de IA compatível com servidores MCP remotos ao OneSignal usando a URL do servidor MCP hospedado. Inclui a configuração no Claude Code, Codex CLI, Cursor, VS Code e conectores personalizados, além de todas as ferramentas compatíveis, incluindo as de Journeys.

Conecte o OneSignal a qualquer ferramenta ou agente de IA compatível com servidores remotos do Model Context Protocol (MCP) adicionando a URL do servidor MCP do OneSignal. Use esta página para conectar o Cursor, Claude Code, Codex CLI, VS Code ou seu próprio agente, ou para ver a lista completa de ferramentas. Para instalar o OneSignal pelo diretório do Claude ou do ChatGPT, veja [Usar o OneSignal no Claude e no ChatGPT](https://documentation.onesignal.com/docs/en/onesignal-in-claude-chatgpt.md).

O [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) é um padrão aberto para conectar aplicativos de IA a sistemas externos. O servidor MCP do OneSignal expõe ações do OneSignal, como consultar um usuário ou enviar uma mensagem, como ferramentas que sua ferramenta de IA pode chamar.

## Pré-requisitos \\

* Uma conta do OneSignal com acesso aos aplicativos do OneSignal que você deseja gerenciar.
* Permissão para aprovar o acesso ao OneSignal por meio do OAuth, o login baseado em navegador que o OneSignal usa.
* Uma ferramenta de IA compatível com servidores MCP remotos via HTTP com OAuth.

## Detalhes da conexão \\

Todas as ferramentas de IA se conectam ao mesmo endpoint hospedado:

```text theme={null}
https://api.onesignal.com/mcp/oauth
```

Você se autentica fazendo login no OneSignal no navegador e aprovando o acesso. Não há chave da REST API para configurar. Deixe em branco os campos de ID e segredo do cliente OAuth: o OneSignal registra sua ferramenta de IA automaticamente, e valores preenchidos fazem a conexão falhar.

## Configure sua ferramenta de IA \\

### Cursor \\

Instale o OneSignal pelo Cursor Marketplace.

**1. Abra o plugin do OneSignal**

Acesse [o OneSignal no Cursor Marketplace](https://cursor.com/marketplace/onesignal) ou pesquise por **OneSignal** no marketplace do Cursor.

**2. Instale o plugin**

Clique em **Add to Cursor**. O Cursor instala o plugin do OneSignal, incluindo o servidor MCP.

**3. Faça login no OneSignal**

Abra **Settings > MCP & Integrations** e clique em **Authenticate** ao lado de OneSignal. Faça login no navegador e clique em **Agree & Allow Access**.

**4. Use o OneSignal no chat do Agent**

Inicie um novo chat do Agent e peça ao OneSignal para executar uma verificação somente leitura, como listar seus aplicativos do OneSignal.

Para configurar o Cursor manualmente, adicione o OneSignal ao seu `mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "onesignal": {
      "url": "https://api.onesignal.com/mcp/oauth"
    }
  }
}
```

### Claude Code \\

**1. Adicione o servidor MCP do OneSignal**

Execute o seguinte comando no terminal:

```bash theme={null}
claude mcp add --transport http onesignal https://api.onesignal.com/mcp/oauth
```

**2. Autentique-se dentro do Claude Code**

Inicie o `claude` e digite `/mcp` para abrir o painel MCP. Selecione **onesignal** e escolha **Authenticate** para abrir a página de login do OneSignal no navegador.

**3. Aprove o acesso**

Faça login e clique em **Agree & Allow Access**. Volte ao Claude Code. O status do servidor muda para **connected**.

Execute `claude mcp list`, ou `/mcp` dentro do Claude Code, para ver a quantidade de ferramentas.

### Conector personalizado do Claude \\

Use um conector personalizado apenas quando não for possível instalar o OneSignal pelo [diretório do Claude](https://claude.ai/directory/connectors/onesignal). Servidores MCP remotos não podem ser adicionados pelo `claude_desktop_config.json`, que serve apenas para servidores `stdio` locais.

**1. Adicione um conector personalizado**

Acesse **Customize > Connectors** e clique em **Add custom connector**.

**2. Informe os detalhes do servidor**

Defina **Name** como `OneSignal` e **Remote MCP server URL** como `https://api.onesignal.com/mcp/oauth`. Deixe **OAuth Client ID** e **OAuth Client Secret**, em **Advanced settings**, em branco.

**3. Faça login no OneSignal**

Clique em **Add**, conclua o login no OneSignal no navegador e clique em **Agree & Allow Access**.

### Codex CLI \\

**1. Abra o navegador de plugins**

Execute `codex` e digite `/plugins`.

**2. Instale o OneSignal**

Encontre **OneSignal**, abra e instale.

**3. Inicie uma nova sessão e faça login**

Inicie uma nova sessão. Quando o Codex solicitar a autenticação, faça login no OneSignal no navegador e clique em **Agree & Allow Access**.

A extensão do Codex para IDEs não é compatível com plugins. Para usar o OneSignal com o Codex, instale-a pelo Codex CLI ou pela aba **Plugins** do aplicativo ChatGPT para desktop.

### GitHub Copilot no VS Code \\

Adicione o OneSignal ao `.vscode/mcp.json` do seu workspace para compartilhá-la com sua equipe, ou execute **MCP: Open User Configuration** na Paleta de Comandos para instalá-la no seu perfil de usuário:

```json theme={null}
{
  "servers": {
    "onesignal": {
      "type": "http",
      "url": "https://api.onesignal.com/mcp/oauth"
    }
  }
}
```

Na primeira vez que o Copilot precisar de uma ferramenta do OneSignal, o VS Code solicitará a autenticação e abrirá a página de login do OneSignal.

### Outras ferramentas e agentes de IA \\

Adicione `https://api.onesignal.com/mcp/oauth` nas configurações de servidor MCP remoto da sua ferramenta de IA. Na primeira vez que a ferramenta de IA chamar uma ferramenta do OneSignal, ela abrirá a página de login do OneSignal no navegador. Faça login e clique em **Agree & Allow Access**. Sua ferramenta de IA lista as ferramentas do OneSignal assim que a conexão for bem-sucedida.

## Verifique a conexão \\

Inicie um novo chat ou sessão e envie:

```text theme={null}
Use the list_apps tool to list the OneSignal apps I can access.
```

Se a resposta listar seus aplicativos do OneSignal, a conexão está funcionando. Se retornar "tool access is not enabled for this application", veja [Solução de problemas](#troubleshooting).

Para verificar apenas se sua ferramenta de IA alcança o servidor, chame `onesignal_health`. Ela responde antes de o acesso por ferramentas de IA ser ativado, então um resultado saudável não confirma que as outras ferramentas funcionam.

## Solução de problemas \\

* **Autentique-se novamente.** Reconecte o OneSignal nas configurações de MCP ou de conectores da sua ferramenta de IA e inicie uma nova sessão.

* **Verifique a URL do servidor.** A URL deve ser exatamente `https://api.onesignal.com/mcp/oauth`, sem caminho extra nem caracteres no final.

* **Limpe os campos do cliente OAuth.** Se sua ferramenta de IA tiver campos de ID ou segredo do cliente OAuth, deixe-os em branco.

* **Verifique o acesso por ferramentas de IA.** Se uma ferramenta retornar "tool access is not enabled for this application":

  O OneSignal ainda não ativou o acesso por ferramentas de IA para o seu login do OneSignal. Entre em contato com o suporte do OneSignal.

* **Reinicie sua ferramenta de IA** e inicie uma nova sessão. Isso resolve a maioria dos problemas temporários de conexão.

## Ferramentas \\

Explore as ferramentas abaixo. A descoberta de ferramentas depende da ativação do MCP no seu aplicativo ou conta do OneSignal. Cada operação também verifica as permissões do seu aplicativo do OneSignal.

### Aplicativos (2 ferramentas) \\

| Ação | Ferramenta |
| - | - |
| Listar os aplicativos acessíveis ao usuário autenticado | `list_apps` |
| Verificar quais canais de mensagens estão ativados em um aplicativo | `get_app_channel_availability` |

### Journeys (9 ferramentas) \\

| Ação | Ferramenta |
| - | - |
| Listar as Journeys de um aplicativo | `list_journeys` |
| Ver a estrutura de uma Journey e sua chave de concorrência atual | `get_journey` |
| Ver estatísticas de Journey, etapas, ramificações e mensagens | `get_journey_stats` |
| Obter o JSON Schema para criar, duplicar ou atualizar uma Journey ou etapa | `get_journey_schema` |
| Criar uma Journey como rascunho | `create_journey_draft` |
| Duplicar uma Journey como um novo rascunho | `duplicate_journey` |
| Atualizar campos de uma Journey ou alterar seu estado | `update_journey` |
| Atualizar uma etapa individual da Journey | `update_journey_node` |
| Excluir uma Journey permanentemente | `delete_journey` |

> [card] [Gerenciar Journeys com MCP](https://documentation.onesignal.com/docs/en/mcp-journeys.md)
>
> Estruture solicitações de ferramentas, obtenha schemas e aplique alterações em Journeys com segurança.

### Mensagens (3 ferramentas) \\

| Ação | Ferramenta |
| - | - |
| Enviar uma notificação push, e-mail ou SMS | `send_message` |
| Listar notificações recentes | `list_messages` |
| Ver detalhes da notificação e estatísticas de entrega | `view_message` |

Para iniciar ou atualizar uma Live Activity, veja [Live Activities](#live-activities-2-tools) abaixo.

### Usuários e assinaturas (12 ferramentas) \\

| Ação | Ferramenta |
| - | - |
| Consultar um usuário por alias | `view_user` |
| Obter os aliases de identidade de um usuário | `get_user_identity` |
| Obter a identidade pelo ID da assinatura | `get_user_identity_by_subscription` |
| Criar um novo usuário com propriedades | `create_user` |
| Atualizar propriedades do usuário (tags, idioma e mais) | `update_user` |
| Adicionar ou atualizar aliases de identidade | `create_or_update_alias` |
| Adicionar aliases pelo ID da assinatura | `create_alias_by_subscription` |
| Adicionar uma assinatura de push, e-mail ou SMS | `create_subscription` |
| Atualizar uma assinatura existente | `update_subscription` |
| Atualizar uma assinatura pelo token | `update_subscription_by_token` |
| Cancelar a inscrição de um endereço de e-mail | `unsubscribe_email` |
| Transferir uma assinatura para outro usuário | `transfer_subscription` |

### Templates (4 ferramentas) \\

| Ação | Ferramenta |
| - | - |
| Listar templates | `list_templates` |
| Ver um template | `get_template` |
| Criar um template | `create_template` |
| Atualizar um template | `update_template` |

### Segmentos (4 ferramentas) \\

| Ação | Ferramenta |
| - | - |
| Listar segmentos | `list_segments` |
| Ver um segmento e seus filtros | `get_segment` |
| Criar um segmento | `create_segment` |
| Atualizar um segmento | `update_segment` |

### Live Activities (2 ferramentas) \\

| Ação | Ferramenta |
| - | - |
| Iniciar uma Live Activity no iOS | `start_live_activity` |
| Atualizar ou encerrar uma Live Activity | `update_live_activity` |

### Exportações (2 ferramentas) \\

| Ação | Ferramenta |
| - | - |
| Exportar assinaturas para CSV | `export_subscriptions_csv` |
| Exportar a atividade do público da notificação para CSV | `export_audience_activity_csv` |

### Eventos personalizados (2 ferramentas) \\

| Ação | Ferramenta |
| - | - |
| Criar eventos personalizados para usuários | `create_custom_events` |
| Listar definições de eventos personalizados indexados | `get_custom_events` |

### Entregabilidade de e-mail (4 ferramentas) \\

| Ação | Ferramenta |
| - | - |
| Verificar o status de verificação de DNS do domínio de e-mail (SPF, DKIM, DMARC) | `get_email_domains` |
| Ver as taxas de rejeição e de reclamações de spam de todo o aplicativo | `get_email_reputation` |
| Obter métricas de entregabilidade por provedor de caixa de entrada de um domínio | `get_provider_metrics` |
| Obter uma série temporal das métricas de entregabilidade dos provedores | `get_provider_metrics_timeseries` |

### Aquecimento de e-mail (5 ferramentas) \\

| Ação | Ferramenta |
| - | - |
| Verificar se um envio precisa de aquecimento de IP ou de domínio | `check_send_volume` |
| Estimar a quantidade de destinatários a partir de segmentos e filtros | `estimate_recipient_count` |
| Obter um cronograma de aquecimento em etapas recomendado | `recommended_warm_up_schedule` |
| Aplicar um cronograma de aquecimento a uma campanha em rascunho | `apply_warm_up_schedule` |
| Listar os cronogramas de aquecimento em andamento | `get_active_warm_up_schedules` |

### Análises e utilitários (4 ferramentas) \\

| Ação | Ferramenta |
| - | - |
| Ver análises de resultados | `view_outcomes` |
| Verificar a integridade do servidor | `onesignal_health` |
| Ver a configuração do servidor | `onesignal_config` |
| Ver uma visão geral de referência de todas as ferramentas | `onesignal_reference_overview` |

## Segurança e proteções \\

* O OneSignal marca `send_message` como uma ferramenta de alto impacto, então ferramentas de IA que respeitam anotações de ferramentas podem pedir confirmação antes de executá-la.
* `send_message` valida a segmentação antes do envio: apenas um método de segmentação por solicitação, e os filtros têm um limite.
* O OneSignal valida as entradas antes da execução, incluindo identificadores, endereços de e-mail e números de telefone.
* Para requisitos de concorrência de Journeys, controles de ciclo de vida e recuperação após gravações incertas, veja o [guia de solicitações de Journeys](https://documentation.onesignal.com/docs/en/mcp-journeys.md).
* O OneSignal ativa ou desativa o acesso por ferramentas de IA para cada login do OneSignal.
* O servidor MCP não armazena os dados dos seus clientes (assinantes, mensagens, exportações).

## Limites e uso \\

Conectar o OneSignal é gratuito. Cada ação conta para os limites normais de uso da API do OneSignal. O plano do seu provedor de IA pode ter custos próprios.

* As chamadas de ferramentas têm limite de taxa para evitar loops descontrolados.
* Uma conexão segue as permissões do usuário conectado e pode acessar todos os aplicativos do OneSignal que esse usuário pode gerenciar.
* Pode ser necessário que o OneSignal ative o acesso por ferramentas de IA para o seu login antes que ferramentas além das utilitárias funcionem.

## FAQ \\

### Preciso de uma chave da REST API? \\

Não. Todas as conexões usam o OAuth do OneSignal. Você faz login pelo navegador e aprova o acesso, então não há chave de API para copiar, armazenar ou rotacionar.

### Como trabalho com mais de um aplicativo do OneSignal? \\

Uma única conexão abrange todos os aplicativos que sua conta do OneSignal pode gerenciar. Chame `list_apps` para encontrar os IDs dos aplicativos. Você não precisa de uma configuração separada para cada aplicativo.

### Posso conectar uma ferramenta de IA que só é compatível com servidores stdio locais? \\

Não. O servidor MCP do OneSignal é um servidor remoto via HTTP. Sua ferramenta de IA precisa ser compatível com servidores MCP remotos com OAuth.

### Como revogo o acesso de uma ferramenta de IA? \\

Acesse **[Settings > Account settings > Connected apps](https://dashboard.onesignal.com/settings/connected-apps)** no OneSignal e revogue a conexão. Revogar a conexão não afeta as conexões dos seus colegas de equipe.

## Páginas relacionadas \\

> [card] [Usar o OneSignal no Claude e no ChatGPT](https://documentation.onesignal.com/docs/en/onesignal-in-claude-chatgpt.md)
>
> Instale o OneSignal pelo diretório do Claude ou do ChatGPT.

> [card] [Gerenciar Journeys com MCP](https://documentation.onesignal.com/docs/en/mcp-journeys.md)
>
> Crie rascunhos, atualize etapas de Journeys e gerencie o estado das Journeys pelo seu cliente MCP.

> [card] [Visão geral da REST API](https://documentation.onesignal.com/reference/rest-api-overview.md)
>
> Referência dos endpoints que o servidor MCP do OneSignal chama.

> [card] [API de criação de mensagens](https://documentation.onesignal.com/reference/create-message.md)
>
> Referência do endpoint por trás de `send_message`.

> [card] [Práticas de dados de IA](https://documentation.onesignal.com/docs/en/ai-data-practices.md)
>
> Como o OneSignal trata os dados para recursos de IA e ferramentas de IA conectadas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.