Configurando o servidor MCP do Braze

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

Pré-requisitos

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

Configurando o servidor MCP do Braze

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: Crie uma chave de API

O servidor Braze MCP suporta 38 endpoints somente leitura que não retornam dados dos perfis de usuários do Braze. Acesse Configurações > APIs e Identificadores > Chaves de API e crie 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 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 nosso arquivo de configuração pré-fornecido.

• claude
• cursor

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": "key-identifier",
        "BRAZE_BASE_URL": "rest-endpoint"
      }
    }
  }
}

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
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"
      }
    }
  }
}

Etapa 5: Envie um prompt de teste

Agora que você configurou 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

Solução de problemas

Erros de terminal

uvx comando não encontrado

Se você receber um erro 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 erros, 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 então 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 configurações de firewall.
3. Certifique-se de que está usando HTTPS em sua URL base.

Aviso Legal

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

O código e as instruções de configuração do Braze MCP Server são fornecidos pela Braze “no estado em que se encontram” e sem quaisquer garantias, e os clientes os 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 possíveis problemas de segurança que possam surgir. A Braze incentiva fortemente os clientes a revisarem suas configurações cuidadosamente e a seguirem as diretrizes descritas para reduzir os riscos associados à integridade e à segurança de seu ambiente Braze.

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