Configurar el servidor Braze MCP

Aprende a configurar el servidor MCP de Braze para poder interactuar con tus datos de Braze utilizando herramientas de lenguaje natural como Claude y Cursor. Para obtener información más general, consulta Servidor Braze MCP.

Importante

El servidor MCP de Braze está en fase beta. No necesitas solicitar acceso para usarlo. Sigue las instrucciones de configuración para empezar. Al usar el servidor MCP de Braze, aceptas los Términos beta de Braze. Para ayudarnos a mejorarlo, envía tus comentarios a [email protected].

Requisitos previos

Antes de empezar, necesitarás lo siguiente:

Configuración del servidor Braze MCP

Paso 1: Instalar uv

En primer lugar, instala uv—una herramienta de línea de comandos de Astral para la administración de dependencias y el manejo de paquetes 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!

Paso 2: Crear una clave de API

El servidor Braze MCP incluye puntos de conexión de solo lectura y de escritura. No devuelven datos de los perfiles de usuario de Braze. Los puntos de conexión de escritura permiten a los agentes crear o actualizar contenido en tu espacio de trabajo.

Para crear tu clave de API:

1. Ve a Configuración > API e identificadores > Claves de API.
2. Crea una nueva clave.
3. Asigna algunos o todos los permisos siguientes a tu clave.

Importante

Asigna únicamente los permisos que quieras que tu agente utilice. Para evitar que tu agente realice cambios en Braze, no incluyas ningún permiso de escritura al crear tu clave de API.

Advertencia

No reutilices una clave de API existente. Crea una específicamente para tu cliente MCP. Asigna únicamente los permisos que tu agente necesite. Los agentes pueden intentar utilizar cualquier permiso que les concedas, así que deja desactivados los permisos de escritura si no quieres que tu agente realice cambios en Braze.

Paso 3: Obtén tu identificador y punto de conexión

Cuando configures tu cliente MCP, necesitarás el identificador de tu clave de API y el punto de conexión REST de tu espacio de trabajo. Para obtener estos datos, vuelve a la página Claves de API en el dashboard—mantén esta página abierta para poder consultarla durante el siguiente paso.

Paso 4: Configura tu cliente MCP

Configura tu cliente MCP utilizando el archivo de configuración proporcionado previamente.

• 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

Paso 5: Enviar una solicitud de prueba

Después de configurar el servidor Braze MCP, intenta enviar una solicitud de prueba a tu cliente MCP. Para ver otros ejemplos y prácticas recomendadas, consulta Uso del servidor Braze MCP.

• claude
• cursor
• gemini cli

Solución de problemas

Errores de terminal

Comando uvx no encontrado

Si recibes un error que indica que no se encuentra el comando uvx, vuelve a instalar uv y reinicia tu terminal.

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

Error spawn uvx ENOENT

Si recibes un error spawn uvx ENOENT, es posible que necesites actualizar la ruta del archivo en el archivo de configuración de tu cliente. Primero, abre tu terminal y ejecuta el siguiente comando:

1
which uvx

El comando debería devolver un mensaje similar al siguiente:

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

Copia el mensaje en el portapapeles y abre el archivo de configuración de tu cliente. Reemplaza "command": "uvx" con la ruta que copiaste y, a continuación, reinicia tu cliente. Por ejemplo:

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

Error en la instalación del paquete

Si la instalación del paquete falla, intenta instalar una versión específica de Python.

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

Configuración del cliente

El cliente MCP no puede encontrar el servidor Braze

1. Verifica que la sintaxis de configuración de tu cliente MCP sea correcta.
2. Reinicia tu cliente MCP después de realizar cambios en la configuración.
3. Comprueba que uvx está en el PATH de tu sistema.

Errores de autenticación

1. Verifica que tu BRAZE_API_KEY sea correcto y esté activo.
2. Asegúrate de que BRAZE_BASE_URL coincida con tu instancia de Braze.
3. Comprueba que tu clave de API tiene los permisos correctos.

Tiempo de espera de conexión agotado o errores de red

1. Verifica que tu BRAZE_BASE_URL sea correcto para tu instancia.
2. Comprueba tu conexión de red y la configuración del cortafuegos.
3. Asegúrate de utilizar HTTPS en tu URL base.

Descargo de responsabilidad

El Model Context Protocol (MCP) es un protocolo de código abierto recientemente introducido que, en este momento, puede ser susceptible a problemas de seguridad o vulnerabilidades.

El código y las instrucciones de configuración del servidor MCP de Braze se proporcionan «tal cual», sin garantías de ningún tipo, y los clientes los utilizan bajo su propia responsabilidad. Braze no se hará responsable de ninguna consecuencia derivada de una configuración incorrecta, un uso indebido del MCP o cualquier posible problema de seguridad que pueda surgir. Braze recomienda encarecidamente a los clientes que revisen cuidadosamente sus configuraciones y sigan las directrices descritas para reducir los riesgos asociados a la integridad y seguridad de su entorno Braze.

Si necesitas ayuda o aclaración, ponte en contacto con soporte de Braze.