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.

Importante

O servidor MCP da Braze hospedado localmente (beta) está descontinuado e não recebe atualizações adicionais.

Pré-requisitos

Antes de começar, verifique se você tem o seguinte:

Nota

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.

Gerenciando o acesso (para administradores)

Nota

Antes que os usuários possam se conectar, um administrador da empresa deve ativar o Acesso OAuth ao MCP em Configurações > Configurações de administrador > OAuth. Para saber mais, consulte Gerenciar configurações OAuth.

Conceder acesso

Os administradores controlam o acesso ao servidor MCP por meio da permissão “Use MCP Server”. Por padrão, os usuários não possuem essa permissão, e ela deve ser concedida explicitamente.

Revogar acesso

Para revogar o acesso, remova a permissão “Use MCP Server” do usuário. Remover permissões do dashboard de um usuário também remove essas capacidades de qualquer agente conectado na próxima solicitação.

Auditar uso

Quando um usuário se conecta com sucesso por meio do 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

1. Você ou o administrador da sua empresa precisam confirmar que você tem a permissão “Use MCP Server”.
2. Se você precisa acessar vários espaços de trabalho, verifique se a permissão está ativada para todos os espaços de trabalho relevantes.

Etapa 2: Adicione a Braze como um conector MCP remoto

No seu cliente MCP, adicione um novo servidor remoto ou conector personalizado e insira a URL do MCP da Braze. Por exemplo, no Claude, você pode acessar Settings > Connectors > Add custom connector e colar a URL.

Não é necessário informar ID de cliente, segredo de cliente ou chave de API. Seu cliente se registra automaticamente na Braze.

Opções de endpoint do MCP da Braze:

• https://mcp.braze.com/mcp (US)
• https://mcp.braze.eu/mcp (EU)

Dica

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:

• Claude
• Claude Code
• ChatGPT
• Cursor
• OpenAI Codex
• Visual Studio Code

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 a Braze para fazer login.

1. Faça login na Braze como faria normalmente, incluindo SSO, se necessário.
2. Se o seu login pode acessar mais de uma empresa no mesmo cluster, selecione a empresa que deseja usar.
3. Na tela de consentimento, revise o acesso que o aplicativo está solicitando.
4. Marque a caixa de confirmação para concordar com a Política de Privacidade da Braze e selecione Continue para retornar ao seu cliente MCP.

Sua sessão utiliza tokens de acesso de curta duração que são atualizados automaticamente. Ocasionalmente, pode ser necessário fazer login novamente.

Etapa 4: Informe ao seu agente qual espaço de trabalho usar

Se a sua conta pode acessar 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 pode pedir que você esclareça.

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 saber mais, 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 é semelhante para outros clientes compatíveis.

1. No Claude, acesse Settings > Connectors > Add custom connector.
2. Insira um nome, como Braze, e cole a URL do Braze MCP: https://mcp.braze.com/mcp para US ou https://mcp.braze.eu/mcp para EU. Você não precisa de um client ID, client secret ou chave de API.
3. Selecione Add para salvar o conector. O Claude se registra na Braze automaticamente.
4. Selecione Connect para iniciar a autenticação. O Claude abre uma janela do navegador e direciona você para a Braze para fazer login.
5. Faça login na Braze com suas credenciais habituais, incluindo SSO se a sua empresa utiliza. Se o seu login pode acessar mais de uma empresa no mesmo cluster, selecione a empresa que você deseja usar.
6. Na tela de consentimento, revise o acesso solicitado, marque a caixa de confirmação e selecione Continue. O Claude retorna ao seu chat, e seu agente agora 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.

Migrando 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 seja necessário atualizar essas skills para referenciar novos nomes e comportamentos de 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 suportado

1. Confirme que o administrador da sua empresa ativou o acesso OAuth ao MCP nas configurações de OAuth.
2. Confirme que o seu usuário tem a permissão “Use MCP Server”.
3. Tente novamente o login e a autorização.

A autenticação está bloqueada em um cliente não verificado

A Braze mantém uma lista de domínios de clientes suportados para segurança. Se você se conectar a partir de um cliente que não está na lista, a autenticação pode ser bloqueada. Quer support for your MCP client? Considere deixar um feedback de produto.

Clientes que são executados localmente na sua máquina sem um esquema personalizado, como Claude Code e OpenAI Codex, também devem funcionar.

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 geralmente são temporários e se resolvem sozinhos.

O agente não consegue acessar as ferramentas esperadas

1. Confirme que o seu usuário do dashboard possui as permissões necessárias. O seu agente só pode usar ferramentas que correspondam ao seu próprio acesso no dashboard.
2. Confirme que você selecionou o espaço de trabalho esperado no seu prompt.
3. Peça ao seu agente para chamar get_workspaces e verifique os IDs de espaço de trabalho disponíveis.

O agente usa o espaço de trabalho errado

Se a sua conta pode acessar mais de um espaço de trabalho, nomeie o espaço de trabalho no seu prompt usando o nome exato mostrado no dashboard da Braze. Se você não especificar um espaço de trabalho, o seu agente pode pedir esclarecimentos ou usar um inesperado.

Importante

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 daquele que você pretendia.

Mudando para uma empresa diferente

A sua empresa é definida quando você autoriza pela primeira vez. Para trabalhar em uma empresa diferente 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.