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 espelha suas permissões no dashboard. Se o acesso ao seu 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 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 por meio da permissão “Use MCP Server”. Por padrão, os usuários não têm essa permissão, e ela precisa 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.

Se você acredita que um token foi vazado ou usado indevidamente, um administrador da empresa pode revogar todos os tokens OAuth MCP da empresa de uma vez em Configurações > Configurações de administrador > OAuth. Todos os clientes conectados perdem o acesso e todos os usuários precisam se reconectar. Para saber mais, consulte Revogar tokens OAuth MCP.

Auditar o 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 possuem a permissão “Use MCP Server”.
2. Se você precisa de acesso a 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 conector MCP remoto

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

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

Opções de endpoint do Braze MCP:

• 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 do cliente:

• 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 seu login puder 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 usa tokens de acesso de curta duração que são renovados automaticamente. Ocasionalmente, pode ser necessário fazer login novamente.

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

Se 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 poderá 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 mais exemplos, consulte Usando o servidor Braze MCP.

Exemplo: conectar com o Claude

Conectar um cliente requer 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 ID de cliente, segredo do cliente 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 sua empresa utiliza esse recurso. Se o seu login pode acessar mais de uma empresa no mesmo cluster, selecione a empresa que 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. Pode ser 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, pode ser necessário atualizá-los 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 compatível

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

A autenticação é bloqueada em um cliente não verificado

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

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

Uma conexão funcional 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 empresa. Faça login na Braze pelo seu cliente novamente para criar uma nova conexão. Se o login ainda falhar, confirme que o acesso OAuth do 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 geralmente são temporários e se resolvem sozinhos.

O agente não consegue acessar as ferramentas esperadas

1. Confirme que seu usuário do dashboard tem as permissões necessárias. Seu agente só pode usar ferramentas que correspondem 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 exibido no dashboard da Braze. Se você não especificar um espaço de trabalho, seu agente pode pedir para você esclarecer ou usar um inesperado.

Importante

Antes de 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.

Mudando para uma empresa diferente

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.