AI 에이전트에게 브랜드를 부여하기: Claude나 Cursor를 통해 얻는 브랜드 일관성 이미지 (MCP 이용)

AI 보조 초안입니다. 현재 Brandiseer MCP 엔드포인트 및 개발자 문서를 기준으로 설정 내용을 작성하고 검증했습니다.

고지 사항: 저는 Brandiseer에서 근무합니다. 이 게시물 전체는 해당 MCP 서버를 사용하므로 이 점을 염두에 두고 읽어 주십시오.

Cursor에게 랜딩 페이지용 히어로 이미지를 요청하면 무언가를 받게 됩니다. 보통은 브랜드와 아무 관련이 없는 그럴듯한 사진입니다. 예전에 운영하던 빵집 사이트를 위해 시도했을 때, 저는 청록색 악센트가 들어간 회색 대리석 위의 크루아상을 얻었습니다. 그런데 그 빵집의 상자는 주황색이었습니다. 후속 프롬프트를 보낼수록 에이전트는 브랜드가 어떻게 생겼는지 전혀 모르기 때문에 매번 새롭게 추측하며 조금씩 벗어났습니다.

저에게 해결책이 된 것은 브랜드를 프롬프트에서 분리한 것이었습니다. 에이전트는 여전히 이미지가 필요할 때와 무엇을 넣어야 할지 스스로 결정합니다. 하지만 그 '룩(look)'은 이미 브랜드를 알고 있는 서버로부터 나옵니다. 이 분리가 MCP에 아주 적합한데, 에이전트가 몇 가지 도구를 얻고 규칙은 그 뒤에서 작동하는 방식입니다.

서버의 역할

URL:        https://brandiseer.com/api/mcp
Transport:  streamable-http
Header:     Authorization: Bearer bds_...

API 키는 bds_로 시작합니다. 같은 키가 REST API에도 작동하지만, 헤더가 다릅니다 (아래에서 더 자세히 설명하며, 이것이 가장 흔한 실수입니다).

도구들

brandiseer_list_brands

id, name 및 생성 날짜와 함께 저장된 브랜드 목록을 반환합니다. ID는 bds_c_42와 같은 형태를 띱니다. 에이전트가 무언가를 생성하려면 먼저 이것이 필요하므로, 보통 첫 번째 호출입니다.

brandiseer_check_credits

크레딧 잔액을 반환합니다. 저는 에이전트에게 어떤 배치 작업보다도 먼저 이 함수를 호출하도록 했습니다.

brandiseer_generate_image

단일 이미지를 생성하고 인라인으로 반환하여 채팅창에 바로 표시됩니다. 내부적으로는 POST /api/v2/generate를 호출합니다. 예외는 `mode:

v2를 래핑하므로, v2 노브(knobs)로 작업하게 됩니다:

필요한 것들

• 최소한 하나의 브랜드가 저장된 Brandiseer 계정
• Settings > API (https://brandiseer.com/settings/api)에서 받은 API 키
• Cursor 또는 원격 MCP 서버를 지원하는 Claude 호스트
• 몇 개의 크레딧. 빠른 1K 이미지는 4개입니다.

Cursor에 연결하기

Cursor는 프로젝트의 .cursor/mcp.json 또는 모든 프로젝트의 ~/.cursor/mcp.json에서 MCP 구성을 읽습니다. 원격 서버는 url과 headers를 받습니다:

{
  "mcpServers": {
    "brandiseer": {
...

하지만 파일에 실제 키를 두는 것은 꺼려집니다. Cursor는 url 및 headers 내에서 ${env:NAME}을 보간(interpolate)하므로, 이 방법도 작동합니다:

{
  "mcpServers": {
    "brandiseer": {
...

쉘 프로필이나 시스템 환경에 BRANDISEER_API_KEY를 넣고 Cursor를 재시작하세요. 여기서는 .env 파일을 사용할 필요가 없습니다. envFile은 stdio 서버에만 작동하며, 원격 서버는 이를 무시합니다.

그런 다음 사이드바에서 Customize를 열고 서버가 켜져 있는지 확인하고 사용 가능한 도구 목록을 확인하세요. 대신 오류가 표시되면, 출력 패널(Output panel)에 실제 메시지가 담긴

Claude Desktop은 예외적인 경우입니다. 제가 알기로는 이 커스텀 커넥터들은 붙여넣는 헤더 방식이 아니라 OAuth 로그인 과정을 거칩니다. 서버의 401 응답에는 OAuth 로그인을 옵션으로 언급하고 있지만, 저는 이번 게시물에서 그 흐름을 직접 진행해 보지 않았으므로 문서화할 수는 없습니다. URL과 Bearer 헤더를 설정할 수 있는 모든 호스트는 위에 제시된 값들을 사용합니다.

브랜드와 충돌하지 않는 프롬프팅 (Prompting without fighting the brand)

대부분의 나쁜 이미지는 여기서 발생합니다. Brandiseer는 각 브랜드의 색상, 타이포그래피, 시각적 스타일을 자체 브랜드 메모리에 보관하고 모든 생성에 적용합니다. 만약 사용자의 프롬프트가 "네이비 팔레트"나 "우아한 세리프 헤드라인"과 같은 내용을 포함한다면, 이는 Brandiseer의 설정과 충돌하게 되고, 때로는 이 충돌하는 내용이 승리할 수 있습니다. 그 결과, 정반대의 역할만 하는 도구에서 브랜드와 맞지 않는 이미지가 나오게 됩니다.

따라서 프롬프트는 이미지 안에 무엇이 들어갈지, 그리고 어떻게 배치될지를 설명해야 합니다: 피사체(subject), 레이아웃 및 구성(layout and composition), 그리고 이미지에 들어가는 텍스트가 있다면 그 내용까지입니다. 그것이 어떻게 보여야 하는지에 대한 내용은 포함하지 않아야 합니다.

브랜드와 충돌하는 예시:

Instagram post for a coffee shop, cozy warm tones, minimalist aesthetic,
soft pastel colors, elegant serif font for the headline, latte on a
wooden table by a window

브랜드와 조화되는 예시:

Instagram post for a coffee shop: a latte on a wooden table by a window,
morning light through the glass. Headline across the top: "Open from 7"

일부 단어는 스타일처럼 들리지만 그렇지 않습니다. "골든 아워(Golden hour)"와 "스튜디오 조명(studio lighting)"은 장면에 물리적으로 무엇이 있는지 설명합니다. "플랫 일러스트레이션(Flat illustration)", "아이소메트릭(isometric)", 그리고 "포토리얼리스틱(photorealistic)"은 매체(medium)를 지정하며, 이는 브랜드가 결정하는 영역이 아닙니다. 제거해야 할 단어들은 "분위기 있는(moody)" 같은 분위기 관련 단어나, "프리미엄(premium)"과 같이 모호한 품질 관련 단어, 그리고 명시된 색상이나 글꼴 이름입니다. 전체 규칙은 https://brandiseer.com/guide/image에 나와 있습니다. 이 가이드는 에이전트를 위해 작성되었으므로, 직접 여러분의 프롬프트를 여기에 지정할 수 있습니다.

또한, 종횡비(aspect ratio)와 해상도(resolution)는 도구 인자(tool arguments)입니다. 프롬프트 텍스트에 "정사각형, 4K"라고 쓰는 것은 아무런 효과가 없습니다.

에이전트는 도구 호출을 할 때 '깔끔하고 현대적인 미학(clean modern aesthetic)'으로 프롬프트를 '개선'하는 것을 좋아합니다. 프로젝트 규칙은 이러한 행동의 대부분을 막아줍니다. Cursor에서는 .cursor/rules/brandiseer.mdc 파일에 다음과 같이 작성합니다:

---
description: Rules for Brandiseer image generation
alwaysApply: false
...

이 텍스트는 Claude Code의 CLAUDE.md에서도 동일하게 작동합니다.

스모크 테스트 (Smoke test)

에이전트 채팅에서 다음 순서로 세 개의 메시지를 보냅니다.

1. "내 Brandiseer 브랜드 목록을 보여줘." 에이전트는 brandiseer_list_brands를 호출해야 합니다. Cursor는 기본적으로 MCP 도구를 실행하기 전에 사용자에게 묻고, 도구 이름 옆의 화살표에는 인수가 표시됩니다. 그러면 id, name, date가 반환됩니다. 원하는 id를 복사합니다.

2. "Brandiseer 크레딧이 얼마나 남았어?" 이것은 brandiseer_check_credits입니다. 이 두 가지가 모두 작동한다면 인증(auth)에는 문제가 없으며, 나중에 오류가 발생하는 것은 생성(generate) 호출 자체에 대한 문제입니다.

3. 지루하고 레이아웃만 있는 이미지.

Use brandiseer_generate_image with brand bds_c_42, aspect ratio 1:1,
resolution 1K, mode fast, no logo.
Prompt: a flat lay of a notebook, a phone and a coffee cup on a desk,
...

자신의 브랜드 id로 교체합니다. 호출을 승인하기 전에 인수를 확장하여 에이전트가 실제로 보내는 프롬프트를 읽어봅니다. 만약 스타일 관련 단어가 끼어 있다면 거부하고 그 이유를 말합니다. 이미지는 인라인으로 반환됩니다.

참고로, 이미지당 크레딧은 다음과 같습니다:

따라서 스모크 테스트 비용은 4입니다.

오류 발생 시 (When it breaks)

Cursor 연결 시 401 에러. 인증 헤더가 전혀 없는 경우 엔드포인트는 다음과 같이 응답합니다:

Missing Authorization: Bearer <api-key-or-oauth-token> header. Connect via
OAuth sign-in or paste an API key from https://brandiseer.com/settings/api.

MCP 엔드포인트는 Authorization: Bearer bds_...를 요구합니다. X-API-Key는 REST 헤더이며, 이것을 mcp.json에 넣는 것이 일반적인 실수입니다. 제가 확인할 다른 두 가지 사항은 누락된 Bearer 접두사 또는 단일 터미널 세션에서만 존재하는 환경 변수(env var)가 Cursor가 볼 수 없는 경우입니다.

이미지가 브랜드와 맞지 않게 나옵니다. 도구 인자(tool arguments)에 있는 프롬프트를 읽어보세요. 보통 거기에 작성하지 않은 색상이나 분위기 단어가 있습니다.

디자인 모드가 멈춘 것처럼 보입니다. 디자인 작업은 대략 40초에서 70초가 걸리며, MCP 서버는 이 시간 동안 비동기(async) 작업을 폴링(polling)합니다. 완료될 때까지 기다려 주세요. 취소하고 다시 요청하면 새 작업이 제출될 뿐입니다. 빠른 확인이나 레이아웃 반복을 위해서는 fast를 유지하고 원하는 것이 확실해지면 design으로 전환하세요.

REST 사용 시점

MCP는 에이전트가 루프(loop) 안에 있을 때 사용합니다. 배치 스크립트, CI 단계 또는 백엔드 작업의 경우 API를 직접 호출하세요. 키를 X-API-Key로 사용하는 v2를 사용하세요:

curl -X POST https://brandiseer.com/api/v2/generate \
  -H "X-API-Key: $BRANDISEER_API_KEY" \
  -H "Content-Type: application/json" \
...

이것은 { "imageUrl": "...", "creditsUsed": 4 }를 반환합니다.

사용자 자체 타임아웃을 가진 디자인 모드의 경우, 비동기 엔드포인트에 제출하고 폴링해야 합니다. 문서는 status가 done 또는 failed가 될 때까지 3초에서 5초마다 확인하라고 말합니다:

import os
import time

...

여기서 중요한 문서 세부 사항 몇 가지를 알려드립니다. 크레딧은 제출할 때 차감되며, 작업이 실패하면 자동으로 환불됩니다. 제출했을 때 사용한 것과 동일한 키로 폴링해야 합니다. 작업은 10분 후에 만료되므로 마감 시간은 9분입니다. 이 루프보다 더 많은 것을 원한다면 일반적인 패턴(백오프(backoff), Idempotency, Retry-After)을 이미지 작업 폴링에 관한 이전 게시물에서 작성했습니다.

전체 참고 자료: [https://brandiseer.com/developers/docs]

proMode 무시하기

v1 API는 proMode: true/false를 사용했고 fast와 pro만 있었습니다. v2는 이를 mode로 대체했습니다. 일부 발견 표면(discovery surfaces)은 여전히 proMode라고 언급합니다. 2026년 10월 14일 기준으로, 이는 MCP 매니페스트 자체의 brandiseer_generate_image 설명에 포함되는데, 여기에는

에이전트는 도구 설명을 읽기 때문에 Cursor는 proMode: true를 전송하려고 시도할 수 있습니다. MCP와 v2의 경우, fast, design 또는 pro를 사용하여 mode를 사용하세요. 그래서 위의 규칙 파일에는 '절대 proMode를 보내지 마라'고 되어 있는 것입니다. /api/v1/generate는 오래된 통합을 위해 여전히 proMode를 허용하지만, 두 가지를 섞어 쓰지 마세요. 아직 모든 부분이 정리되지는 않았기 때문에, 문서나 OpenAPI 파일 또는 도구 설명에서 proMode를 본다면, 그것은 구형 API를 보고 있는 것입니다.