Setting up the Braze MCP server

Learn how to set up the Braze MCP server, so you can interact with your Braze data through natural language using tools like Claude and Cursor. For more general information, see Braze MCP server.

important

Braze MCP server is in beta. You don’t need to request access to use it. Follow the setup instructions to get started. By using the Braze MCP server, you agree to the Braze Beta Terms. To help us make it better, send your feedback to [email protected].

Prerequisites

Before you start, you’ll need the following:

Setting up the Braze MCP server

Step 1: Install uv

First, install uv—a command-line tool by Astral for dependency management and Python package handling.

• 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!

Step 2: Create an API key

The Braze MCP server includes both read-only and write endpoints. They don’t return data from Braze user profiles. Write endpoints let agents create or update content in your workspace.

To create your API key:

1. Go to Settings > APIs and Identifiers > API Keys.
2. Create a new key.
3. Assign some or all of the following permissions to your key.

important

Only assign the permissions you want your agent to use. To prevent your agent from making changes in Braze, leave any write permissions off when you create your API key.

warning

Don’t reuse an existing API key. Create one specifically for your MCP client. Assign only the permissions your agent needs. Agents may try to use any permission you grant, so leave any write permissions off if you don’t want your agent to make changes in Braze.

Step 3: Get your identifier and endpoint

When you configure your MCP client, you’ll need your API key’s identifier and your workspace’s REST endpoint. To get these details, go back to the API Keys page in the dashboard—keep this page open, so you can reference it during the next step.

Step 4: Configure your MCP client

Configure your MCP client using the pre-provided configuration file.

• 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

Step 5: Send a test prompt

After you set up the Braze MCP server, try sending a test prompt to your MCP client. For other examples and best practices, see Using the Braze MCP server.

• claude
• cursor
• gemini cli

Troubleshooting

Terminal errors

uvx command not found

If you receive an error that uvx command not found, reinstall uv and restart your terminal.

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

spawn uvx ENOENT error

If you receive a spawn uvx ENOENT errors, you may need to update the filepath in your client’s config file. First, open your terminal and run the following command:

1
which uvx

The command should return a message similar to the following:

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

Copy the message to your clipboard and open your client’s config file. Replace "command": "uvx" with the path you copied, then restart your client. For example:

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

Package installation fails

If your package installation fails, try installing a specific Python version instead.

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

Client configuration

MCP client can’t find the Braze server

1. Verify your MCP client configuration syntax is correct.
2. Restart your MCP client after configuration changes.
3. Check that uvx is in your system PATH.

Authentication errors

1. Verify your BRAZE_API_KEY is correct and active.
2. Ensure your BRAZE_BASE_URL matches your Braze instance.
3. Check that your API key has the correct permissions.

Connection timeouts or network errors

1. Verify your BRAZE_BASE_URL is correct for your instance.
2. Check your network connection and firewall settings.
3. Ensure you’re using HTTPS in your base URL.

Disclaimer

The Model Context Protocol (MCP) is a newly introduced open-source protocol that may be susceptible to security issues or vulnerabilities at this time.

Braze MCP Server setup code and instructions are provided by Braze “as is” and without any warranties, and customers use it at their own risk. Braze shall not be responsible for any consequences arising from improper setup, misuse of the MCP, or any potential security issues that may arise. Braze strongly encourages customers to review their configurations carefully and to follow the outlined guidelines to reduce risks associated with the integrity and security of their Braze environment.

For assistance or clarification, please contact Braze Support.