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 o seguinte:
| Pré-requisito | Descrição |
|---|---|
| Cliente MCP compatível | Qualquer cliente que ofereça suporte a servidores MCP remotos com OAuth pode funcionar. A Braze verificou o Claude, o ChatGPT, o Cursor, o OpenAI Codex, o Claude Code e o Visual Studio Code. |
| URI de redirecionamento aprovado | Um administrador da empresa precisa aprovar o URI de redirecionamento do seu cliente em Configurações > Configurações de administrador > Conexões externas. O administrador pode copiá-lo das 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 existe 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 consegue acessar qualquer cluster da Braze. |
| Conta paga da Braze | O servidor Braze MCP não está disponível para contas de avaliação gratuita. |
| Sem lista de permissões de IP | Clientes que usam a lista de permissões de IP 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 for limitado a uma equipe em vez de um espaço de trabalho completo, algumas ferramentas podem não funcionar.
Gerenciamento do acesso (para administradores)
Antes que os usuários possam se conectar, um administrador da empresa precisa ativar o acesso OAuth ao MCP em Configurações > Configurações do administrador > Conexões externas. Para saber mais, consulte Gerenciar configurações de OAuth.
Conceder acesso
Os administradores controlam o acesso ao servidor MCP com a 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 todos os tokens OAuth do MCP da empresa de uma só vez em Configurações > Configurações do administrador > Conexões externas. 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 por 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 verificar isso por você.
- 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 Braze MCP. 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 na Braze automaticamente. O registro não aprova o URI de redirecionamento do cliente para sua empresa, então um administrador ainda precisa aprová-lo, conforme descrito na Etapa 1.
Opções de endpoint do Braze MCP:
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 via 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 seleção de confirmação para concordar com a Política de Privacidade da Braze e, em seguida, selecione Continuar para voltar ao seu cliente MCP.
Sua sessão usa tokens de acesso de curta duração que são atualizados automaticamente. Talvez você precise fazer login novamente de vez em quando.
Etapa 4: Informe ao seu agente qual espaço de trabalho usar
Se a 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 esclarecimentos.
Etapa 5: Envie um prompt de teste
Após a 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 Usando o servidor Braze MCP.
Exemplo: Conectar com o Claude
Conectar um cliente leva apenas 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.
- Insira 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 sua empresa.
- Selecione Conectar para iniciar a autenticação. O Claude abre uma janela do navegador e direciona você para fazer login na Braze.
- Faça login na Braze com suas credenciais de sempre, incluindo SSO, se sua empresa usar. Se o seu login tiver acesso a mais de uma empresa no mesmo cluster, selecione a empresa que você quer usar.
- Na tela de consentimento, revise o acesso solicitado, marque a caixa de seleção 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
Durante a migração, você pode executar o servidor beta local e o servidor hospedado remotamente lado a lado. 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 habilidades para o servidor local, talvez precise atualizá-las para referenciar os novos nomes e o novo comportamento das ferramentas.
Depois de confirmar que seus fluxos de trabalho e habilidades 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 que 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 de domínios de clientes compatíveis. Se você se conectar a partir de um cliente que não está nessa lista, a autenticação poderá 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 para 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 novamente pelo seu cliente para criar uma nova conexão. Se o login continuar falhando, confirme que o Acesso OAuth ao MCP está ativado e que você ainda tem a permissão “Use MCP Server”.
As ferramentas não aparecem no seu cliente
Se o seu agente não consegue 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 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 tem 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 poderá pedir esclarecimentos ou usar um espaço inesperado.
Antes que seu agente comece 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 outra empresa
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.