Configurando o servidor Braze MCP

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

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 and 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 suporta 38 endpoints somente leitura que não retornam dados dos perfis de usuários Braze. Acessar Configurações > APIs e Identificadores > Chaves de API e criar uma nova chave com algumas ou todas as seguintes permissões.

Etapa 3: Obtenha seu identificador e endpoint

Quando você configurar seu cliente MCP, precisará do identificador da 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 melhores práticas, veja Usando o servidor Braze MCP.

• claude
• cursor
• gemini cli

Solução de problemas

Erros de terminal

uvx comando não encontrado

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

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

spawn uvx ENOENT erro

Se você receber um spawn uvx ENOENT erro, pode ser necessário atualizar o caminho 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 depois 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

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 seu sistema PATH.

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 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 Modelo de Protocolo de Contexto (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 “como estão” 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 delineadas para reduzir os riscos associados à integridade e segurança do ambiente Braze.

Para assistência ou esclarecimentos, entre em contato com [email protected].