Braze MCP 서버를 설정하세요

Claude 및 Cursor와 같은 자연어 도구를 사용하여 Braze 데이터와 상호작용할 수 있도록 Braze MCP 서버를 설정하는 방법을 알아보세요. 더 일반적인 정보는 Braze MCP 서버를 참조하세요.

중요

로컬 호스팅 Braze MCP 서버(베타)는 올여름 서비스 종료 예정입니다. 기존 기능은 계속 작동하지만, 더 이상 엔드포인트를 추가하거나 베타를 지원하지 않습니다. 원격 Braze 호스팅 MCP 서버가 올여름 얼리 액세스로 제공될 예정입니다.

필수 조건

시작하기 전에 다음이 필요합니다:

Braze MCP 서버 설정하기

1단계: uv 설치하기

먼저 uv—의존성 관리 및 Python 패키지 처리를 위한 Astral의 명령줄 도구를 설치하세요.

• 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 고객 프로필에서 데이터를 반환하지는 않습니다. 쓰기 엔드포인트를 사용하면 에이전트가 워크스페이스에서 콘텐츠를 생성하거나 업데이트할 수 있습니다.

API 키를 생성하려면:

1. 설정 > API 키 > API 키로 이동합니다.
2. 새 키를 생성합니다.
3. 키에 다음 권한 중 일부 또는 전부를 할당합니다.

중요

에이전트가 사용하기를 원하는 권한만 할당하세요. 에이전트가 Braze에서 변경 작업을 수행하지 못하도록 하려면 API 키를 생성할 때 쓰기 권한을 모두 제외하세요.

경고

기존 API 키를 재사용하지 마세요. MCP 클라이언트 전용으로 새 키를 생성하세요. 에이전트에 필요한 권한만 할당하세요. 에이전트는 부여된 모든 권한을 사용하려고 시도할 수 있으므로, 에이전트가 Braze에서 변경 작업을 수행하지 않기를 원한다면 쓰기 권한은 제외하세요.

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"를 복사한 경로로 교체한 후 클라이언트를 재시작하세요. 예를 들어:

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

패키지 설치 실패

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

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

클라이언트 구성

“이 확장 프로그램은 기기와 호환되지 않습니다”

Braze MCP 서버 확장 프로그램을 설치할 때 이 오류가 표시되면 다음 중 하나를 나타낼 수 있습니다:

• 기기가 요구 사항을 충족하지 않음: 일부 MCP 서버 확장 프로그램은 특정 운영체제 버전이나 하드웨어를 필요로 합니다.
• 개발 도구 누락(macOS만 해당): macOS에서는 확장 프로그램 설치 시 Python 명령을 실행하기 위해 명령줄 개발자 도구가 필요합니다. 이 도구가 설치되어 있지 않으면 이 오류와 함께 설치가 실패합니다.

macOS에서 명령줄 개발자 도구를 설치하려면 터미널에서 다음을 실행하세요:

1
xcode-select --install

설치가 완료되면 MCP 클라이언트를 재시작하고 확장 프로그램 설치를 다시 시도하세요.

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 서버 설정 코드 및 지침은 Braze에서 “있는 그대로” 어떠한 보증 없이 제공되며, 고객은 자신의 위험 부담 하에 사용합니다. Braze는 부적절한 설정, MCP의 오용 또는 발생할 수 있는 잠재적인 보안 문제로 인한 모든 결과에 대해 책임을 지지 않습니다. Braze는 고객이 구성을 신중하게 검토하고, Braze 환경의 무결성 및 보안과 관련된 위험을 줄이기 위해 안내된 지침을 따를 것을 강력히 권장합니다.

도움이나 추가 설명이 필요하시면 Braze 고객지원으로 문의해 주세요.