Braze MCP 서버 설정하기

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

중요

Braze MCP 서버는 베타 버전입니다. 사용하기 위해 별도의 액세스 요청은 필요하지 않습니다. 설정 안내에 따라 시작하세요. Braze MCP 서버를 사용하면 Braze 베타 약관에 동의하는 것으로 간주됩니다. 더 나은 제품을 만들 수 있도록 [email protected]으로 피드백을 보내주세요.

필수 조건

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

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 고객 프로필에서 데이터를 반환하지 않는 39개의 엔드포인트를 지원합니다.

API 키를 생성하려면:

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

중요

에이전트가 사용하기를 원하는 권한만 할당하세요. 에이전트가 Braze에서 변경 작업을 수행하지 못하도록 하려면 media_library.create 권한을 제외하세요.

경고

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

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

클라이언트 구성

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 고객지원으로 문의해 주세요.