Configure o servidor Braze MCP

Aprenda como configurar o servidor Braze MCP, para que você possa interagir com seus dados do Braze usando ferramentas de linguagem natural como Claude e Cursor. Para mais informações gerais, veja servidor Braze MCP.

Importante

O servidor MCP da Braze hospedado localmente (beta) está passando por sunsetting neste verão. Ele continuará funcionando, mas não estamos mais adicionando endpoints nem oferecendo Suporte ao beta. Um servidor MCP remoto, hospedado pela Braze, estará disponível em acesso antecipado neste verão.

Pré-requisitos

Antes de começar, você precisará do seguinte:

Configurando o servidor Braze MCP

Etapa 1: Instalar uv

Primeiro, instale uv—uma ferramenta de linha de comando da Astral para gerenciamento de dependências e manipulação de pacotes Python.

• macos e linux
• windows

1
curl -LsSf https://astral.sh/uv/install.sh | sh

1
2
3
4
5
6
7
8
$ curl -LsSf https://astral.sh/uv/install.sh | sh

downloading uv 0.8.9 aarch64-apple-darwin
no checksums to verify
installing to /Users/Isaiah.Robinson/.local/bin
  uv
  uvx
everything's installed!

1
irm https://astral.sh/uv/install.ps1 | iex

1
2
3
4
5
6
7
8
PS C:\Users\YourUser> irm https://astral.sh/uv/install.ps1 | iex

Downloading uv 0.8.9 (x86_64-pc-windows-msvc)
no checksums to verify
installing to C:\Users\YourUser\.local\bin
  uv.exe
  uvx.exe
everything's installed!

Etapa 2: Criar uma chave de API

O servidor Braze MCP inclui endpoints somente leitura e de escrita. Eles não retornam dados de perfis de usuários da Braze. Os endpoints de escrita permitem que agentes criem ou atualizem conteúdo no seu espaço de trabalho.

Para criar sua chave de API:

1. Acesse Configurações > APIs e identificadores > Chaves de API.
2. Crie uma nova chave.
3. Atribua algumas ou todas as permissões a seguir à sua chave.

Importante

Atribua apenas as permissões que você deseja que seu agente use. Para impedir que seu agente faça alterações na Braze, não inclua permissões de escrita ao criar sua chave de API.

Aviso

Não reutilize uma chave de API existente. Crie uma especificamente para seu cliente MCP. Atribua apenas as permissões que seu agente precisa. Os agentes podem tentar usar qualquer permissão que você conceder, então não inclua permissões de escrita se você não quiser que seu agente faça alterações na Braze.

Etapa 3: Obtenha seu identificador e endpoint

Quando você configurar seu cliente MCP, precisará do identificador da sua chave de API e do endpoint REST do seu espaço de trabalho. Para obter esses detalhes, volte para a página Chaves de API no dashboard—mantenha esta página aberta, para que você possa consultá-la durante a próxima etapa.

Etapa 4: Configure seu cliente MCP

Configure seu cliente MCP usando o arquivo de configuração pré-fornecido.

• claude
• cursor
• gemini cli

1
2
3
4
5
6
7
8
9
10
11
12
{
  "mcpServers": {
    "braze": {
      "command": "uvx",
      "args": ["--native-tls", "braze-mcp-server@latest"],
      "env": {
        "BRAZE_API_KEY": "your-braze-api-key",
        "BRAZE_BASE_URL": "your-braze-endpoint-url"
      }
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
{
  "mcpServers": {
    "braze": {
      "command": "uvx",
      "args": ["--native-tls", "braze-mcp-server@latest"],
      "env": {
        "BRAZE_API_KEY": "2e8b-3c6c-d12e-bd75-4f0e2a8e5c71",
        "BRAZE_BASE_URL": "https://torchie.braze.com"
      }
    }
  }
}

1
2
mkdir -p ~/.gemini
nano ~/.gemini/settings.json

1
2
3
4
5
6
7
8
9
10
11
12
{
  "mcpServers": {
    "braze": {
      "command": "/Users/yourname/.local/bin/uvx",
      "args": ["--native-tls", "braze-mcp-server@latest"],
      "env": {
        "BRAZE_API_KEY": "2e8b-3c6c-d12e-bd75-4f0e2a8e5c71",
        "BRAZE_BASE_URL": "https://torchie.braze.com"
      }
    }
  }
}

1
2
3
4
gemini
/mcp
/mcp desc
/mcp schema

Etapa 5: Envie um prompt de teste

Depois de configurar o servidor Braze MCP, tente enviar um prompt de teste para o seu cliente MCP. Para outros exemplos e práticas recomendadas, veja Usando o servidor Braze MCP.

• claude
• cursor
• gemini cli

Solução de problemas

Erros de terminal

Comando uvx não encontrado

Se você receber um erro informando que o comando uvx não foi encontrado, reinstale uv e reinicie seu terminal.

1
curl -LsSf https://astral.sh/uv/install.sh | sh

Erro spawn uvx ENOENT

Se você receber um erro spawn uvx ENOENT, pode ser necessário atualizar o caminho do arquivo no arquivo de configuração do seu cliente. Primeiro, abra seu terminal e execute o seguinte comando:

1
which uvx

O comando deve retornar uma mensagem semelhante à seguinte:

1
/Users/alex-lee/.local/bin/uvx

Copie a mensagem para sua área de transferência e abra o arquivo de configuração do seu cliente. Substitua "command": "uvx" pelo caminho que você copiou e reinicie seu cliente. Por exemplo:

1
"command": "/Users/alex-lee/.local/bin/uvx"

A instalação do pacote falha

Se a instalação do seu pacote falhar, tente instalar uma versão específica do Python.

1
uvx --python 3.12 braze-mcp-server@latest

Configuração do cliente

“Esta extensão não é compatível com seu dispositivo”

Se você vir esse erro ao instalar a extensão do servidor Braze MCP, isso pode indicar uma das seguintes situações:

• Seu dispositivo não atende aos requisitos: Algumas extensões de servidor MCP exigem versões específicas do sistema operacional ou hardware.
• Ferramentas de desenvolvimento ausentes (somente macOS): No macOS, a instalação da extensão requer ferramentas de desenvolvedor de linha de comando para executar comandos Python. Se essas ferramentas não estiverem instaladas, a instalação falhará com esse erro.

Para instalar as ferramentas de desenvolvedor de linha de comando no macOS, execute o seguinte no seu terminal:

1
xcode-select --install

Após a conclusão da instalação, reinicie seu cliente MCP e tente instalar a extensão novamente.

O cliente MCP não consegue encontrar o servidor Braze

1. Verifique se a sintaxe da configuração do seu cliente MCP está correta.
2. Reinicie seu cliente MCP após as alterações de configuração.
3. Verifique se uvx está no PATH do seu sistema.

Erros de autenticação

1. Verifique se seu BRAZE_API_KEY está correto e ativo.
2. Certifique-se de que seu BRAZE_BASE_URL corresponde à sua instância da Braze.
3. Verifique se sua chave de API tem as permissões corretas.

Timeouts de conexão ou erros de rede

1. Verifique se seu BRAZE_BASE_URL está correto para sua instância.
2. Verifique sua conexão de rede e as configurações do firewall.
3. Certifique-se de que está usando HTTPS na sua URL base.

Aviso Legal

O Model Context Protocol (MCP) é um protocolo de código aberto recém-introduzido que pode estar suscetível a problemas de segurança ou vulnerabilidades neste momento.

O código e as instruções de configuração do servidor MCP da Braze são fornecidos pela Braze “no estado em que se encontram” e sem quaisquer garantias, e os clientes o utilizam por sua própria conta e risco. A Braze não será responsável por quaisquer consequências decorrentes de configuração inadequada, uso indevido do MCP ou quaisquer potenciais problemas de segurança que possam surgir. A Braze incentiva fortemente os clientes a revisar suas configurações cuidadosamente e a seguir as diretrizes descritas para reduzir os riscos associados à integridade e segurança do seu ambiente Braze.

Para assistência ou esclarecimentos, fale com o suporte da Braze.