Configurando o servidor Braze MCP
Aprenda como se conectar ao servidor remoto Braze MCP, autenticar com OAuth e começar a usar as ferramentas da Braze a partir do seu cliente MCP. Para saber mais, consulte servidor Braze MCP.
O servidor MCP da Braze hospedado localmente (beta) está descontinuado e não recebe atualizações adicionais.
Pré-requisitos
Antes de começar, confira se você tem os seguintes itens:
| Pré-requisito | Descrição |
|---|---|
| Cliente MCP compatível | Qualquer cliente compatível com servidores MCP remotos com OAuth pode funcionar. A Braze verificou o Claude, ChatGPT, Cursor, OpenAI Codex, Claude Code e Visual Studio Code. |
| URI de redirecionamento aprovada | Um administrador da empresa precisa aprovar a URI de redirecionamento do seu cliente em Configurações > Configurações do administrador > OAuth. O administrador pode copiá-la nas configurações de OAuth ou de conector do cliente. Para saber mais, consulte Gerenciar configurações de OAuth. |
| Conta no dashboard da Braze | Você faz login com suas credenciais normais da Braze, incluindo SSO ou SAML, se a sua empresa usar. Não há um login separado para o MCP. |
| Seleção do endpoint do servidor | Escolha https://mcp.braze.com/mcp (EUA) ou https://mcp.braze.eu/mcp (UE). Qualquer um dos endpoints pode acessar qualquer cluster da Braze. |
| Sem lista de IPs permitidos | Clientes que usam a lista de IPs permitidos não podem usar o servidor Braze MCP no momento. |
O acesso do seu agente reflete suas permissões no dashboard. Se o seu acesso ao dashboard estiver limitado a uma equipe em vez de um espaço de trabalho completo, algumas ferramentas podem não funcionar.
Gerenciamento de acesso (para administradores)
Antes que os usuários possam se conectar, um administrador da empresa precisa ativar o acesso OAuth do MCP em Configurações > Configurações de administrador > OAuth. Para saber mais, consulte Gerenciar configurações de OAuth.
Conceder acesso
Os administradores controlam o acesso ao servidor MCP pela permissão “Use MCP Server”. Por padrão, os usuários não têm essa permissão, então ela precisa ser concedida explicitamente.
Revogar acesso
Para revogar o acesso, remova a permissão “Use MCP Server” do usuário. Quando você remove permissões do dashboard de um usuário, esses recursos também são removidos de qualquer agente conectado na próxima solicitação.
Se você suspeitar que um token vazou ou foi usado indevidamente, um administrador da empresa pode revogar de uma só vez todos os tokens OAuth do MCP da empresa em Configurações > Configurações de administrador > OAuth. Todos os clientes conectados perdem o acesso, e todos os usuários precisam se conectar novamente. Para saber mais, consulte Revogar tokens OAuth do MCP.
Auditar o uso
Quando um usuário se conecta com sucesso via OAuth, um evento é registrado no relatório de eventos de segurança.
Conecte seu cliente
Etapa 1: Confirme as permissões e o acesso ao espaço de trabalho
- Confirme que você tem a permissão “Use MCP Server” ou peça ao administrador da sua empresa para verificá-la.
- Se você precisar de acesso a vários espaços de trabalho, verifique se a permissão está ativada em todos os espaços de trabalho relevantes.
- Peça ao administrador da sua empresa para confirmar que o URI de redirecionamento do seu cliente está aprovado nas configurações de OAuth. Se não estiver, você não conseguirá concluir o login na Braze na Etapa 3.
Etapa 2: Adicione a Braze como um conector MCP remoto
No seu cliente MCP, adicione um novo servidor remoto ou conector personalizado e insira o URL do MCP da Braze. Por exemplo, no Claude, você pode acessar Settings > Connectors > Add custom connector e colar o URL.
Não é necessário informar ID do cliente, segredo do cliente nem chave de API. Seu cliente se registra automaticamente na Braze. O registro não aprova o URI de redirecionamento do cliente para a sua empresa. Por isso, um administrador ainda precisa aprová-lo, conforme descrito na Etapa 1.
Opções de endpoint do MCP da Braze:
https://mcp.braze.com/mcp(EUA)https://mcp.braze.eu/mcp(UE)
Clientes da UE devem usar o endpoint da UE. Clientes fora da UE podem usar qualquer um dos endpoints.
Guias de configuração de clientes:
Etapa 3: Faça login na Braze por OAuth
Na primeira vez que seu agente chamar uma ferramenta da Braze, seu cliente abrirá uma janela do navegador e direcionará você para fazer login na Braze.
- Faça login na Braze como de costume, incluindo SSO, se necessário.
- Se o seu login tiver acesso a mais de uma empresa no mesmo cluster, selecione a empresa que deseja usar.
- Na tela de consentimento, revise o acesso que o aplicativo está solicitando.
- Marque a caixa de confirmação para concordar com a Política de Privacidade da Braze e selecione Continuar para voltar ao seu cliente MCP.
Sua sessão usa tokens de acesso de curta duração que são atualizados automaticamente. Ocasionalmente, talvez você precise fazer login novamente.
Etapa 4: Informe ao seu agente qual espaço de trabalho usar
Se sua conta tiver acesso a mais de um espaço de trabalho, especifique o espaço de trabalho no seu prompt. Por exemplo:
I'd like to look at campaign analytics for the past week in the Production workspace.Can you compare this week's analytics between my prod-1 workspace and my prod-2 workspace?
Se você não especificar um espaço de trabalho, seu agente poderá pedir que você esclareça.
Etapa 5: Envie um prompt de teste
Depois da configuração, envie um prompt rápido de validação, como:
List the Braze tools available in this workspace.Show my recent Canvases from the Production workspace.
Para ver mais exemplos, consulte Uso do servidor Braze MCP.
Exemplo: conectar com o Claude
Conectar um cliente leva só algumas etapas. O passo a passo a seguir usa o Claude, mas o fluxo é parecido para outros clientes compatíveis.
Antes de começar, confira se um administrador da empresa aprovou o URI de redirecionamento do seu cliente, conforme descrito na Etapa 1.
- No Claude, acesse Configurações > Conectores > Adicionar conector personalizado.
- Digite um nome, como
Braze, e cole a URL do Braze MCP:https://mcp.braze.com/mcppara os EUA ouhttps://mcp.braze.eu/mcppara a UE. Você não precisa de ID do cliente, segredo do cliente nem chave de API. - Selecione Adicionar para salvar o conector. O Claude se registra automaticamente na Braze, mas isso não aprova o URI de redirecionamento dele para a sua empresa.
- Selecione Conectar para iniciar a autenticação. O Claude abre uma janela do navegador e direciona você para a Braze para fazer login.
- Faça login na Braze com suas credenciais de sempre, incluindo SSO, se a sua empresa usar. Se o seu login tiver acesso a mais de uma empresa no mesmo cluster, selecione a empresa que deseja usar.
- Na tela de consentimento, revise o acesso solicitado, marque a caixa de confirmação e selecione Continuar. O Claude volta para o seu chat, e seu agente já pode usar as ferramentas da Braze.
Para confirmar a conexão, envie um prompt de teste, como Show my recent Canvases from the Production workspace.
Migração do servidor beta local
Você pode executar o servidor beta local e o servidor hospedado remotamente lado a lado durante a migração. Talvez seja necessário informar explicitamente ao seu agente qual deles usar.
O servidor hospedado remotamente inclui novas ferramentas que não existem no servidor beta local. Se você criou skills para o servidor local, talvez precise atualizá-las para que façam referência aos novos nomes e ao novo comportamento das ferramentas.
Depois de confirmar que seus fluxos de trabalho e skills estão funcionando no servidor remoto, desative o servidor hospedado localmente.
Solução de problemas
A autenticação falha em um cliente compatível
- Confirme se o administrador da sua empresa ativou o acesso OAuth ao MCP nas configurações de OAuth.
- Confirme se seu usuário tem a permissão “Use MCP Server”.
- Confirme se o URI de redirecionamento do seu cliente está aprovado. Se você vir “This app needs approval” ou um erro genérico como “An unexpected error occurred” na etapa de consentimento, peça ao administrador da sua empresa para confirmar se o status do URI de redirecionamento está como Aprovado nas configurações de OAuth.
- Tente fazer login e autorizar novamente.
A autenticação é bloqueada em um cliente não verificado
Por segurança, a Braze mantém uma lista de permissões com os domínios de clientes compatíveis. Se você se conectar a partir de um cliente que não está nessa lista, a autenticação pode ser bloqueada. Quer support for your MCP client? Considere deixar um feedback de produto.
Clientes executados localmente na sua máquina sem um esquema personalizado, como Claude Code e OpenAI Codex, também devem funcionar.
Uma conexão que funcionava deixa de autenticar
Se o seu cliente estava conectado e agora não consegue autenticar, o administrador da sua empresa pode ter revogado os tokens OAuth do MCP da sua empresa. Faça login na Braze pelo seu cliente novamente para criar uma nova conexão. Se o login continuar falhando, confirme se o acesso OAuth ao MCP está ativado e se você ainda tem a permissão “Use MCP Server”.
As ferramentas não aparecem no seu cliente
Se o seu agente não conseguir listar as ferramentas da Braze, aguarde alguns minutos e tente novamente. Esses problemas costumam ser temporários e se resolvem sozinhos.
O agente não consegue acessar as ferramentas esperadas
- Confirme se o seu usuário do dashboard tem as permissões necessárias. Seu agente só pode usar ferramentas compatíveis com o seu próprio acesso ao dashboard.
- Confirme se você selecionou o espaço de trabalho esperado no seu prompt.
- Peça ao seu agente para chamar
get_workspacese verifique os IDs dos espaços de trabalho disponíveis.
O agente usa o espaço de trabalho errado
Se a sua conta tiver acesso a mais de um espaço de trabalho, informe o espaço de trabalho no seu prompt usando o nome exato exibido no dashboard da Braze. Se você não especificar um espaço de trabalho, seu agente pode pedir esclarecimentos ou usar um espaço inesperado.
Antes de o seu agente começar a trabalhar, sempre confirme qual espaço de trabalho ele está usando. Em alguns casos, um agente pode selecionar um espaço de trabalho diferente do que você pretendia.
Mudar para uma empresa diferente
Sua empresa é definida na primeira autorização. Para trabalhar em outra empresa no mesmo cluster, desconecte o conector da Braze no seu cliente, autorize novamente e selecione a outra empresa durante o login.
Aviso legal
Como instruções e respostas são tratadas
O servidor MCP da Braze recebe instruções do seu cliente MCP de provedor terceiro, como Claude, ChatGPT, Copilot, Gemini CLI, Codex ou Cursor, exatamente como o modelo de IA subjacente desse provedor as formula. Quando você digita uma solicitação em linguagem natural, o modelo de IA interpreta sua solicitação e a traduz em uma ou mais chamadas de ferramenta específicas para a Braze. A Braze recebe e executa a chamada de ferramenta conforme enviada. A Braze não vê seu prompt original em linguagem natural e não pode verificar se a chamada de ferramenta gerada reflete total ou precisamente a sua solicitação pretendida.
Quando a Braze retorna dados ou um resultado, essa resposta é enviada de volta ao seu cliente MCP de provedor terceiro, que então interpreta, formata e apresenta as informações para você. A Braze não controla como o modelo de IA apresenta, resume ou descreve as informações retornadas.
A Braze não é responsável por instruções geradas por, ou respostas transmitidas por meio de, qualquer cliente MCP de provedor terceiro. A Braze recomenda não usar o “modo automático” caso seu cliente MCP de provedor terceiro o ofereça para implementação automática de ações. Revise os resumos gerados por IA comparando-os com os dados de origem no seu dashboard da Braze e revise qualquer ação proposta pela IA antes de implementá-la por meio do seu cliente MCP de provedor terceiro.