Braze MCP 서버 설정하기

Claude 및 Cursor와 같은 도구를 사용하여 자연어를 통해 Braze 데이터와 상호 작용할 수 있도록 Braze MCP 서버를 설정하는 방법을 알아보세요. 자세한 내용은 Braze MCP 서버.

필수 조건

Before you start, you’ll need the following:

Braze MCP 서버 설정하기

1단계: 설치 uv

먼저, 종속성 관리 및 Python 패키지 처리를 위한 Astral의 명령줄 툴인 uv을 설치합니다.

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

2단계: API 키 만들기

Braze MCP 서버는 Braze 사용자 프로필에서 데이터를 반환하지 않는 38개의 읽기 전용 엔드포인트를 지원합니다. 설정 > API 및 식별자 > API 키로 이동하여 다음 권한 중 일부 또는 전부를 가진 새 키를 만듭니다.

3단계: 식별자 및 엔드포인트 가져오기

MCP 클라이언트를 구성할 때 API 키의 식별자와 워크스페이스의 REST 엔드포인트가 필요합니다. 이러한 세부 정보를 얻으려면 대시보드의 API 키 페이지로 돌아가서 이 페이지를 열어두면 다음 단계에서 참조할 수 있습니다.

4단계: MCP 클라이언트 구성하기

미리 제공된 구성 파일을 사용하여 MCP 클라이언트를 구성합니다.

• 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

5단계: 테스트 프롬프트 보내기

Braze MCP 서버를 설정한 후 MCP 클라이언트에 테스트 프롬프트를 전송해 보세요. 다른 예제 및 모범 사례는 Braze MCP 서버 사용.

• claude
• cursor
• gemini cli

문제 해결

터미널 오류

uvx 명령을 찾을 수 없습니다.

uvx 명령을 찾을 수 없다는 오류가 표시되면 uv 을 다시 설치하고 터미널을 다시 시작하세요.

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

spawn uvx ENOENT 오류

spawn uvx ENOENT 오류가 발생하면 클라이언트의 설정 파일에서 파일 경로를 업데이트해야 할 수 있습니다. 먼저 터미널을 열고 다음 명령을 실행합니다:

1
which uvx

명령은 다음과 유사한 메시지를 반환해야 합니다:

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

메시지를 클립보드에 복사하고 클라이언트의 설정 파일을 엽니다. "command": "uvx" 을 복사한 경로로 바꾼 다음 클라이언트를 다시 시작합니다. For example:

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

패키지 설치 실패

패키지 설치에 실패하면 특정 Python 버전을 대신 설치해 보세요.

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

클라이언트 구성

MCP 클라이언트가 Braze 서버를 찾을 수 없습니다.

1. MCP 클라이언트 구성 구문이 올바른지 확인합니다.
2. 구성을 변경한 후 MCP 클라이언트를 다시 시작하세요.
3. uvx 가 시스템에 있는지 확인 PATH.

인증 오류

1. BRAZE_API_KEY 주소가 올바르고 활성화되어 있는지 확인합니다.
2. BRAZE_BASE_URL 이 Braze 인스턴스와 일치하는지 확인합니다.
3. API 키에 올바른 권한이 있는지 확인하세요.

연결 시간 초과 또는 네트워크 오류

1. BRAZE_BASE_URL 이 인스턴스에 맞는지 확인합니다.
2. 네트워크 연결 및 방화벽 설정을 확인하세요.
3. 기본 URL에 HTTPS를 사용하고 있는지 확인하세요.

Disclaimer

모델 컨텍스트 프로토콜(MCP) 은 새로 도입된 오픈 소스 프로토콜로, 현재 보안 문제나 취약점이 있을 수 있습니다.

Braze MCP 서버 설정 코드와 지침은 보증 없이 “있는 그대로” 제공되며, 고객은 자신의 책임 하에 이를 사용합니다. 부적절한 설정, MCP의 오용 또는 발생할 수 있는 잠재적인 보안 문제로 인해 발생하는 어떠한 결과에 대해서도 Braze는 책임을 지지 않습니다. Braze는 고객이 자신의 구성을 주의 깊게 검토하고 설명된 가이드라인을 준수하여 Braze 환경의 통합 및 보안과 관련된 위험을 줄일 것을 강력히 권장합니다.

지원이나 설명이 필요한 경우 지원팀( braze.com )으로 문의하시기 바랍니다.