Claude Code용 Higgsfield MCP: 60초 만에 설치하기(그리고 함정 5가지)
최종 업데이트: 2026년 6월 6일. 설치 명령어와 OAuth 플로우를 재검증했습니다. 모델 라인업(GPT Image 2, Soul V2, Veo 3.1, Kling 3.0, Flux 2, Nano Banana Pro, Seedance 2.0)도 최신 상태임을 확인했습니다. 무료 등급 크레딧 지급량(월 150개)도 여전히 정확합니다.
Claude Code에서 Higgsfield MCP를 사용하려면 터미널에서 claude mcp add --transport http --scope user higgsfield https://mcp.higgsfield.ai/mcp를 실행하세요. Claude Code가 브라우저 OAuth를 통해 인증을 처리하므로 API 키는 필요 없습니다. 이 서버는 7개 모델에 걸쳐 5개 도구(generate_image, generate_video, create_character, get_generation_status, list_characters)를 제공합니다. 일반적인 네트워크 환경이라면 설치는 60초 안에 끝납니다.
Higgsfield는 2026년 4월 30일, 이 글을 쓰는 시점으로부터 8일 전에 호스팅 MCP 서버를 출시했습니다. Claude Code가 설치되어 있다면 단 하나의 명령어로 Higgsfield MCP를 워크플로우에 연결할 수 있습니다. API 키도, npm 패키지도 필요 없죠. 이 글을 끝까지 읽을 때쯤이면 실제로 사용하는 모든 AI 클라이언트에 서버를 설치한 상태일 것이고, 7개 모델 중 어떤 것을 골라 써야 할지 알게 될 것이며, 저희가 블로그 히어로 이미지에 자주 활용하는 프롬프트 작성법도 손에 넣게 될 겁니다.
techsy.io에서는 이미 4가지 Higgsfield 에이전트 스킬, 즉 higgsfield-generate, higgsfield-product-photoshoot, higgsfield-soul-id, higgsfield-marketplace-cards를 커버 및 라이프스타일 이미지에 활용하고 있으며, 더 풍부한 대화 중 생성을 위해 MCP 서버도 함께 연결해 쓰고 있습니다. MCP는 컨텍스트 엔지니어링이 도구 레이어에서 실제로 구현되는 방식입니다. 별도의 UI에 URL과 프롬프트를 붙여넣는 대신, 글을 쓰고 있는 바로 그 채팅 안에서 모델이 직접 모델과 파라미터를 선택하죠.
빠른 답변
- Higgsfield MCP는
https://mcp.higgsfield.ai/mcp에 있는 호스팅 서버로, 7개의 이미지 및 비디오 모델을 모든 MCP 클라이언트에 제공합니다.- 명령어 하나로 Claude Code에 설치하며, 인증은 OAuth 방식이고 API 키는 필요 없습니다.
- Claude Code, Claude Desktop, Cursor, Windsurf, Cline, OpenCode에서 작동합니다.
- 무료 등급: 월 150크레딧(2026년 5월 기준), 초과 시 $1당 16크레딧.
Higgsfield MCP가 실제로 하는 일
Higgsfield MCP는 https://mcp.higgsfield.ai/mcp에 있는 호스팅 Model Context Protocol(MCP) 서버로, MCP를 지원하는 모든 AI 클라이언트(Claude Code, Claude Desktop, Cursor, Windsurf, Cline, OpenCode)가 OAuth 인증을 거쳐 5개 도구로 7개의 이미지 및 비디오 모델을 호출할 수 있게 해줍니다. API 키도, npm 설치도, 프록시도 필요 없습니다.
Higgsfield MCP 서버는 여러분의 AI 클라이언트와 30개 이상의 생성형 모델 라인업 사이에 자리합니다. 호스팅 엔드포인트는 저희가 가장 자주 사용하는 7개를 노출합니다. 캐릭터 일관성에는 Soul V2, 비디오에는 Veo 3.1과 Kling 3.0, 사진 같은 사실감에는 GPT Image 2, 일러스트에는 Flux 2, 빠른 반복 작업에는 Nano Banana Pro, 짧은 클립에는 Seedance 2.0이죠. 채팅을 벗어나지 않고도 이 모든 모델을 Claude Code 안에서 서로 다른 모델로 호출할 수 있습니다.
| 모델 | 종류 | 용도 | 생성당 대략적 크레딧 |
|---|---|---|---|
| GPT Image 2 | 이미지 | 사진 같은 사실감, 제품 촬영 | ~8 |
| Nano Banana Pro | 이미지 | 빠르고 저렴한 반복 작업 | ~2 |
| Soul V2 | 이미지 | 캐릭터 일관성(create_character와 함께) | ~10 |
| Seedance 2.0 | 비디오 | 움직임이 있는 짧은 클립 | ~30 |
| Veo 3.1 | 비디오 | 영화 같은 8~15초 클립 | ~60 |
| Kling 3.0 | 비디오 | 유려한 움직임, 캐릭터 액션 | ~50 |
| Flux 2 | 이미지 | 스타일화된 일러스트 | ~6 |
무료 등급: 월 150크레딧, 2026년 5월 기준이며 변경될 수 있습니다.
서버가 노출하는 5개 도구가 기능의 전부입니다:
generate_image: 단일 이미지 생성generate_video: 비동기 비디오 생성, 작업 ID 반환create_character: 일관성을 위한 Soul Character 학습get_generation_status: 비동기 작업 상태 조회list_characters: 학습된 캐릭터 목록 조회
이게 전부입니다. 도구 5개, API 키 없음, 외워야 할 스코프도 없습니다. 벤더 API 대여섯 개를 꿰맞추는 작업과 비교해 보면 MCP 사양이 왜 빠르게 확산되었는지 알 수 있습니다. 공식 모델 목록은 Higgsfield의 공식 MCP 페이지가 가장 정확한 출처입니다.
Claude Code에 Higgsfield MCP를 추가하려면?
Claude Code에 Higgsfield MCP를 설치하려면 claude mcp add --transport http --scope user higgsfield https://mcp.higgsfield.ai/mcp를 실행하세요. 처음 사용할 때 Claude Code가 OAuth를 위해 브라우저를 엽니다. Higgsfield 계정으로 로그인한 뒤 터미널로 돌아와 claude mcp list 또는 /mcp 슬래시 명령어로 확인하면 됩니다. 이것이 higgsfield mcp 설정의 전부입니다.
바로 이 부분이 기존 튜토리얼 대부분이 틀리는 지점입니다. 4월 30일 이전에는 호스팅 서버가 없었고, 글쓴이들은 여러분이 npm으로 어떤 패키지를 설치하고 셸에 HIGGSFIELD_API_KEY를 붙여넣을 거라 가정했습니다. 그럴 필요 없습니다. 호스팅 MCP는 Higgsfield의 인프라에서 실행되며 브라우저에서 OAuth로 인증합니다.
설치 명령어는 이렇습니다. 터미널에 붙여넣으세요:
claude mcp add --transport http --scope user higgsfield https://mcp.higgsfield.ai/mcp알아두면 좋은 플래그가 두 개 있습니다. --transport http는 이것이 로컬 stdio 프로세스가 아니라 HTTP 기반 호스팅 서버라고 Claude Code에 알려줍니다. --scope user는 설정을 ~/.claude/mcp.json에 기록하므로, 여는 프로젝트마다 서버를 사용할 수 있습니다. 특정 리포지토리에서만 쓰고 싶다면(그리고 git에 체크인해서 팀원들도 자동으로 쓰게 하려면) 대신 --scope project를 사용하세요. 이 경우 리포지토리 루트의 .mcp.json에 기록됩니다.
제대로 됐는지 확인하세요:
claude mcp list
# Higgsfield http ✔ connectedHiggsfield 도구를 처음 호출하면 Claude Code가 포트 8080에 로컬 OAuth 콜백을 띄우고 브라우저를 엽니다. Higgsfield 계정으로 로그인한 뒤 터미널로 돌아오면 끝입니다. Claude Code 세션 안에서 /mcp를 실행하면 패널을 볼 수 있습니다. Higgsfield가 5개 도구와 함께 목록에 표시되어야 합니다.
제가 이 글을 쓰고 있는 M3 Pro에서는 설치와 OAuth 왕복이 47초 만에 완료되었습니다. 네트워크 환경에 따라 다르겠지만, 2분이 넘어간다면 글 뒷부분의 함정 섹션으로 바로 건너뛰세요.
잠깐 곁가지로: 같은 MCP를 Claude Code 스킬로 감싸고 싶다면, robonuggets의 higgsfield-skill 리포지토리가 정확히 그 일을 해줍니다. 이 패턴은 Claude Code 스킬 튜토리얼에서 다룬 적이 있습니다. 훅으로 MCP 서버 주변을 자동화할 수도 있는데, 예를 들어 블로그 히어로 생성 전에 list_characters 호출을 자동으로 실행하는 식이죠. 공식 설정 문법은 Claude Code용 Anthropic MCP 설정 문서에서 전송 타입, 스코프 플래그, 재인증 플로우를 빠짐없이 다루고 있습니다.
generate_image 도구 호출.
Claude Desktop에 Higgsfield MCP를 추가하려면?
Claude Desktop은 claude mcp add CLI 대신 JSON 설정 파일(claude_desktop_config.json)을 사용합니다. 위치는 OS마다 다릅니다. 파일을 편집해 higgsfield 블록을 추가한 뒤, Claude Desktop을 완전히 종료했다가 다시 실행하세요. OAuth는 설정을 불러올 때가 아니라 도구를 처음 호출할 때 실행됩니다.
| OS | 경로 |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
이걸 넣으세요:
{
"mcpServers": {
"higgsfield": {
"transport": {
"type": "http",
"url": "https://mcp.higgsfield.ai/mcp"
}
}
}
}Claude Desktop에 서버는 목록에 있는데 도구가 보이지 않는다면, 완전히 종료하지 않은 겁니다. macOS에서는 빨간 신호등 버튼이 아니라 Cmd-Q를 누르세요. 창을 닫기만 하면 이전 설정이 메모리에 남은 채 프로세스가 계속 실행됩니다.
Higgsfield MCP Cursor 설정
higgsfield mcp cursor를 사용하려면 ~/.cursor/mcp.json을 편집해 https://mcp.higgsfield.ai/mcp를 가리키는 HTTP 전송 방식의 higgsfield 서버를 추가하세요. Cursor를 재시작하면 서버가 Settings → MCP Servers 아래에 표시되고, 첫 생성 요청 시 OAuth로 인증합니다. 같은 JSON을 프로젝트 루트의 .cursor/mcp.json으로 써도 됩니다.
Cursor는 url 필드에서 HTTP 전송 방식을 자동 감지하므로 별도로 선언할 필요가 없습니다. 설정은 이렇습니다:
{
"mcpServers": {
"higgsfield": {
"url": "https://mcp.higgsfield.ai/mcp"
}
}
}파일을 저장하고 Cursor를 재시작한 뒤 Settings → MCP Servers를 여세요. 초록 점과 함께 "higgsfield"가 보일 겁니다. 처음 Cursor에게 "Higgsfield로 골든아워 시간대의 여우 히어로 이미지를 만들어줘"라고 요청하면 브라우저가 열리며 OAuth가 진행되고, 로그인하자마자 생성이 실행됩니다.
여기에 항상 Higgsfield를 사용하는 Cursor 규칙을 히어로 이미지에 결합해 보세요. .cursor/rules/blog-images.mdc에 "blog hero"나 "OG image" 요청을 기본 종횡비의 generate_image로 연결하는 규칙을 넣으면 됩니다. 꿀팁: user-scope 파일 대신 리포지토리 루트에 .cursor/mcp.json을 커밋하면, 팀원 전체가 pull할 때 서버를 자동으로 받게 됩니다. 개발자별 설정도 필요 없고, 도구가 왜 안 뜨냐는 Slack 스레드도 사라집니다.
Windsurf나 Cline에 Higgsfield MCP를 설치하려면?
두 클라이언트 모두 VS Code 스타일의 mcp.json 형식을 사용하므로 같은 JSON이 둘 다에서 작동합니다. Windsurf는 ~/.codeium/windsurf/mcp_config.json을 읽고, Cline(VS Code 확장 프로그램)은 Settings UI나 워크스페이스의 .vscode/mcp.json을 사용합니다.
{
"mcpServers": {
"higgsfield": {
"type": "http",
"url": "https://mcp.higgsfield.ai/mcp"
}
}
}꼭 기억해둘 Cline 팁: "Auto-approve safe tools"는 list_characters와 get_generation_status에만 활성화하세요. generate_video는 자동 승인하지 마세요. 호출 한 번에 30~60크레딧이 소모되며, 루프를 도는 자율 에이전트는 5분 만에 무료 등급을 다 써버릴 수 있습니다. 읽기 도구는 괜찮지만, 생성 도구는 안 됩니다.
두 클라이언트의 실사용 차이가 궁금하신가요? Windsurf vs Cursor 비교 글에서 트레이드오프를 다뤘습니다. Higgsfield의 경우, 서버만 등록되면 경험은 동일합니다. 두 클라이언트 모두 같은 MCP 와이어 프로토콜을 사용하기 때문입니다.
Higgsfield MCP는 OpenCode에서 작동하나요?
네. OpenCode(오픈소스 sst/opencode 기반의 Claude Code 대안)도 같은 MCP 와이어 프로토콜을 사용합니다. 설정은 리포지토리 루트의 .opencode/mcp.json이나 user scope의 ~/.config/opencode/mcp.json에 있습니다. 필드 하나가 Claude Code와 다르므로 mcpServers 블록을 무턱대고 복사-붙여넣기하지 마세요.
{
"servers": {
"higgsfield": {
"transport": "http",
"url": "https://mcp.higgsfield.ai/mcp"
}
}
}필드명은 mcpServers가 아니라 servers라는 점에 주의하세요. 쉽게 걸리는 함정입니다. 설정을 추가했는데도 OpenCode에 도구가 표시되지 않는다면 거의 항상 이게 원인입니다. opencode mcp list로 확인하세요. claude mcp list와 같은 역할을 합니다. OAuth 플로우는 동일합니다. 브라우저 열기, 콜백, 끝.
MCP를 통해 Higgsfield에 프롬프트를 주는 가장 좋은 방법은?
저희가 찾은 가장 신뢰할 만한 프롬프트 작성법은 MCSLA입니다. Model(모델), Composition(구도), Subject(피사체), Lighting(조명), Aesthetic(미감)의 앞글자를 딴 것이죠. MCSLA 시네마틱 프롬프트 스킬에서 유래했으며, 막연한 "히어로 이미지 만들어줘"를 Higgsfield 모델이 실제로 실행할 수 있는 브리프로 바꿔줍니다. 다섯 가지 필드, 다섯 줄, 매번 그렇습니다.
- Model(모델): 먼저 알맞은 도구를 고릅니다. 사실감에는 GPT Image 2, 반복되는 캐릭터에는 Soul V2, 스타일화된 작업에는 Flux 2.
- Composition(구도): 샷을 프레이밍합니다("와이드앵글 히어로 구도, 피사체는 왼쪽 3분할 지점, 오른쪽은 여백").
- Subject(피사체): 프레임 안에 무엇을 담을지 구체적 속성과 함께 명시합니다("검은 세라믹 머그, 맺힌 물방울, 풍화된 오크 위").
- Lighting(조명): 방향과 성질을 지정합니다("왼쪽 위에서 비추는 따뜻한 림 라이트, 부드러운 필 라이트, 짙은 푸른 그림자").
- Aesthetic(미감): 최종 룩을 정합니다("매거진 에디토리얼, 35mm 필름 그레인, SaaS 마케팅용 컬러 그레이딩").
레퍼런스 이미지 체이닝 워크플로우야말로 MCP가 제값을 하는 부분입니다. v1을 생성한 뒤 Claude에게 "이제 대비를 더 강하게, 팔레트는 더 차갑게 다시 만들어줘"라고 요청하세요. 채팅 히스토리가 이미지 URL을 유지하므로 다음 generate_image 호출은 이를 자동으로 레퍼런스로 전달합니다. 웹 UI를 오가는 대신 대화 안에서 반복 작업을 이어가는 거죠.
higgsfield mcp 캐릭터 일관성에는 Soul Character 워크플로우가 정답입니다:
- 레퍼런스 이미지 3~5장으로
create_character를 실행합니다. - 학습에 3~5분 정도 걸립니다.
get_generation_status로 상태를 조회하세요. - 이후
generate_image호출에서 반환된 캐릭터 ID를 참조합니다. - 결과: 블로그 시리즈 전체에 걸쳐 같은 얼굴이 유지되고, 흔들림이 없습니다.
techsy.io에서는 바로 이 패턴을 사용합니다. Higgsfield의 higgsfield-product-photoshoot 스킬과 higgsfield-soul-id 스킬이 사이트 전반의 팀원 일러스트와 마켓플레이스 카드를 만들어냅니다. MCP 서버 덕분에 일회성 변형이 필요할 때 별도 UI로 이동하지 않고 Claude Code 대화 안에서 반복 작업을 할 수 있습니다. 같은 인물을 10개 포스팅에 걸쳐 반복해야 하는 캐릭터 작업이 필요할 때는 higgsfield-soul-id 스킬을 씁니다. 시즌별 마켓플레이스 카드에는 higgsfield-marketplace-cards가 더 빠릅니다.
마지막 한 수: 하우스 스타일을 CLAUDE.md 규칙으로 저장해 두면 같은 다섯 줄을 반복해서 입력하지 않아도 모든 프롬프트가 브랜드 톤을 유지합니다. 시작용 라이브러리가 필요하다면 AKCodez의 19개 스타일 팩이 흔히 쓰는 미감 프리셋을 바로 넣을 수 있는 Claude Code 스킬로 묶어 제공합니다.
Higgsfield MCP로 블로그 히어로 이미지를 어떻게 생성하나요?
higgsfield mcp로 블로그 히어로 이미지를 생성하려면, AI 클라이언트에게 1200×630 종횡비, MCSLA 브리프, GPT Image 2 모델로 generate_image를 호출하라고 프롬프트를 주면 됩니다. 반환된 URL을 저장하고 WebP로 최적화한 뒤 CMS에 업로드하세요. MCP가 연결되어 있으면 프롬프트부터 Sanity에 업로드된 WebP까지, 히어로 하나를 별도 탭 하나 열지 않고 만드는 전 과정이 약 90초 걸립니다.
이 블로그의 실제 워크플로우는 이렇습니다. 포스팅의 .claude/skills/blog-hero-image 스킬 안에 히어로 프롬프트를 작성합니다(포스팅당 하나, 버전 관리됨). Claude Code에서 포스팅을 작업하며 "GPT Image 2로 이 포스팅의 프로세스 다이어그램 히어로를 만들어줘, 1200×630, 네이비 배경, 라벨이 달린 박스 3개"라고 합니다. 그러면 generate_image가 호출되고, Higgsfield가 호스팅 URL을 반환하며, 저희 scripts/generate_image.py 파이프라인이 이를 품질 85의 WebP로 다운샘플링하고, scripts/upload_hero_image.py가 Sanity로 전송합니다.
Claude Code 세션 안에서의 일반적인 도구 호출은 이런 모습입니다:
Tool call: generate_image
model: "gpt-image-2"
prompt: "Process diagram, three labeled boxes left-to-right..."
aspect_ratio: "landscape_16_9"
quality: "high"꿀팁: 1200x630을 직접 요청하지 마세요. 대부분의 모델은 landscape_16_9 같은 비율 용어를 선호하며 정확한 픽셀 사양은 거부합니다. 가장 가까운 비율로 생성한 뒤 마지막 5%를 잘라내 정확한 치수에 맞추세요. 실패한 재시도마다 크레딧 하나를 아낄 수 있습니다.
이 호출들을 스크립트로 감싸고 싶다면(예: 프롬프트 CSV에서 히어로 10개를 생성), GitHub의 가벼운 Python 구현체가 대화 밖에서 같은 호출을 재현해 줍니다. 저희는 배치 백필에 사용합니다.
같은 에셋을 여러 채널에 재활용하려면, 블로그 콘텐츠를 히어로 이미지 브리프로 바꿔주는 저희 커뮤니티의 Cover Image Prompter 자동화가 브리프 작성 단계를 처리해 줍니다. Social Banner Generator와 결합하면 MCP로 생성한 히어로 하나가 재프롬프트 없이 4가지 소셜 변형이 됩니다.
generate_image로 렌더링된 블로그 히어로.
Higgsfield MCP로 블로그 요약을 위한 짧은 비디오를 생성할 수 있나요?
기술적으로는 가능합니다. 솔직히 말하면, 단서가 붙습니다. 메커니즘은 Veo 3.1이나 Seedance 2.0으로 generate_video를 호출하는 것으로, 8~15초, 비동기 방식입니다. 호출은 작업 ID를 반환하고, URL이 나올 때까지 get_generation_status로 폴링합니다. 저희는 포스팅 요약 클립에 이를 실험 중이지만, 아직 모든 포스팅에 적용하고 있지는 않습니다.
솔직한 고백 두 가지. 첫째, 비디오 생성은 빠르지 않습니다. Veo 3.1은 8초 클립 하나에 45~90초가 걸리고, Seedance 2.0은 30초 정도입니다. 렌더링 하나마다 커피 한 잔의 여유를 계획하세요. 그리고 빡빡한 루프로 폴링하고 있다면, 빈 processing 응답에 돈을 지불하는 셈입니다. 폴링 간격은 1초가 아니라 5초로 설정하세요.
둘째, 저희 Sanity CMS에는 아직 videoBlock 본문 타입이 없습니다. 이건 파이프라인에 들어올 예정인 것이지, 이미 출시된 것이 아닙니다. 지금은 MCP로 생성한 MP4를 커스텀 블록 안에 HTML5 <video> 태그로 임베드하고 있습니다. 지금 당장 원클릭 솔루션인 척하지는 않겠습니다.
저희가 지향하는 활용 사례: 12초짜리 포스팅 요약 애니메이션으로, 정적 히어로와 동일한 MCSLA 브리프로 "움직이는 프로세스 다이어그램"이라고 프롬프트를 줍니다. 같은 컬러 팔레트, 같은 구도, 다만 움직일 뿐이죠. 더 넓은 비디오 프로덕션 워크플로우 속 AI 맥락은 해당 딥다이브 글에서 에디토리얼 측면을 다루고 있습니다.
호스팅 MCP가 아직 노출하지 않는 모델(예를 들어 Sora 2)에 접근해야 한다면, Sora 2 / Veo 3 접근을 추가한 커뮤니티 포크를 살펴볼 가치가 있습니다. 셀프 호스팅 MCP 래퍼이므로, Higgsfield 라인업에 없는 모델에는 직접 API 키를 가져와야 합니다.
문제 해결: 30분을 날리게 할 함정 5가지
가장 흔한 Higgsfield MCP 문제 5가지는 이렇습니다. OAuth 토큰 만료(/mcp 패널에서 재실행), 서버가 "pending"에 멈춤(Claude Code는 지수 백오프로 5회 재시도), 잘못된 스코프 플래그(--scope user vs --scope project), 모델을 찾을 수 없음(모델명 오타), 그리고 비디오가 비동기 폴링에 멈춤(get_generation_status를 수동 호출하거나 재시작). 알고 나면 각각의 해결은 2분도 걸리지 않습니다.
OAuth 토큰 만료
증상: /mcp에 도구가 보이지만 모든 호출이 "unauthorized"를 반환합니다. 해결: Claude Code에서 /mcp를 실행하고 Higgsfield를 선택한 뒤 "Re-authenticate"를 고릅니다. 브라우저가 다시 열리고, 다시 로그인하면 끝입니다. 토큰에는 수명이 있으며(보통 몇 주), 사전 경고는 없습니다.
서버가 영원히 "Pending"으로 표시됨
증상: claude mcp list에서 higgsfield 옆에 ✔ 대신 ⏳가 표시됩니다. 해결: Claude Code는 지수 백오프(1초 → 2초 → 4초 → 8초 → 16초)로 HTTP/SSE를 재시도하다 5회 시도 후 포기합니다. claude mcp restart higgsfield를 실행하세요. 그래도 pending이면 https://status.higgsfield.ai를 확인하세요. 호스팅 MCP는 모델 롤아웃 중에 간혹 성능이 저하됩니다.
잘못된 스코프(--scope user vs --scope project)
증상: 한 리포지토리에서는 서버가 작동하는데 다른 곳에서는 안 됩니다. 해결: --scope user는 ~/.claude/mcp.json에 기록합니다(전역, 모든 프로젝트). --scope project는 현재 디렉터리의 .mcp.json에 기록합니다(git에 체크인되어 팀과 공유됨). 설치가 2분을 넘긴다면 거의 항상 스코프 플래그 문제입니다. 하나를 고르고 나머지는 삭제하세요.
모델을 찾을 수 없음
증상: Error: model "veo-3" not found. 해결: 모델명은 veo-3이 아니라 veo-3.1입니다. list_characters를 실행해 응답 메타데이터에서 정확한 모델 식별자를 확인하거나, 첫 번째 H2의 표를 확인하세요. Higgsfield 이름은 대소문자를 구분하고 버전이 붙으므로, Soul과 soul-v2는 같은 문자열이 아닙니다.
비디오가 비동기 폴링에 멈춤
증상: generate_video가 작업 ID를 반환했지만 get_generation_status가 3분이 지나도록 계속 processing을 반환합니다. 해결: Veo와 Kling 작업은 90초 이상 걸릴 수 있지만, 3분이 지나면 작업이 조용히 실패했거나 큐에서 정체된 것입니다. claude mcp restart higgsfield를 실행하고 다시 요청하세요. 무료 등급 계정은 큐 우선순위가 낮아 유료 사용자가 이 문제를 덜 겪습니다.
CI에서 MCP 타임아웃이 계속 발생한다면, Higgsfield CLI가 헤드리스로 실행되며 스크립트에 더 친화적입니다. MCP는 대화형 OAuth 왕복을 요구하지만, CLI는 장기간 유효한 API 토큰을 사용하므로 대화형이 아닌 파이프라인에는 이것이 적합합니다.
FAQ
Higgsfield MCP란?
Higgsfield MCP는 https://mcp.higgsfield.ai/mcp에 있는 호스팅 Model Context Protocol 서버로, 7개의 이미지 및 비디오 생성 모델(GPT Image 2, Soul V2, Veo 3.1, Kling 3.0, Flux 2 포함)을 MCP를 지원하는 모든 AI 클라이언트에 제공합니다. 인증은 Higgsfield 계정을 통한 OAuth 방식이며, 호스팅 서버에는 API 키가 필요 없습니다.
Higgsfield MCP는 무료인가요?
네, 월 150크레딧의 무료 등급이 있으며 2026년 5월 기준입니다. 이를 초과하면 선불 크레딧은 대략 $1 = 16크레딧이며, 개별 생성은 모델과 길이에 따라 260크레딧이 듭니다. 스틸 이미지는 약 210크레딧, 8초 Veo 클립은 약 60크레딧입니다. Higgsfield의 유료 플랜은 변동되므로 현재 가격 등급은 결제 페이지에서 확인하세요.
Claude Code에 Higgsfield MCP를 어떻게 설치하나요?
터미널에서 claude mcp add --transport http --scope user higgsfield https://mcp.higgsfield.ai/mcp를 실행하세요. 처음 사용할 때 Claude Code가 OAuth를 위해 브라우저를 엽니다. Higgsfield 계정으로 로그인한 뒤 터미널로 돌아와 claude mcp list 또는 Claude Code 세션 안의 /mcp 슬래시 명령어로 확인하세요. 일반적인 네트워크 환경이라면 전체 플로우는 1분 안에 넉넉히 끝납니다.
Higgsfield MCP는 Codex나 ChatGPT Desktop에서 작동하나요?
OpenAI의 Codex CLI는 됩니다. 표준 MCP 와이어 프로토콜을 사용하므로 같은 mcp.json 설정이 거기서도 작동합니다. ChatGPT 데스크톱은 2026년 5월 기준 안 됩니다. OpenAI는 아직 소비자용 ChatGPT 앱에 MCP 지원을 출시하지 않았습니다. 호스팅 Higgsfield MCP가 노출하지 않는 Sora 2나 기타 OpenAI 모델이 특별히 필요하다면, 커뮤니티 통합 포크가 그 간극을 메워줄 수 있습니다.
Higgsfield MCP vs CLI: 무엇을 써야 하나요?
모델이 컨텍스트에서 파라미터를 고르는 대화형, 채팅 내 생성에는 MCP를 사용하세요. 대부분의 블로그 작성 및 디자인 반복 워크플로우가 여기에 해당합니다. 헤드리스 스크립트 파이프라인, CI 잡, 배치 백필처럼 대화형 OAuth 플로우 대신 장기간 유효한 인증 토큰을 원할 때는 CLI를 사용하세요. 반복되는 패턴에는 MCP를 Claude 스킬로 감쌀 수도 있습니다.
Higgsfield MCP는 어떤 모델을 지원하나요?
호스팅 서버는 현재 7개의 주요 모델을 제공합니다. 일반적인 이미지 작업용 GPT Image 2와 Nano Banana Pro, 캐릭터 일관성용 Soul V2, 스타일화된 출력용 Flux 2, 그리고 비디오용 Seedance 2.0, Veo 3.1, Kling 3.0입니다. Higgsfield의 전체 라인업은 30개 이상의 모델을 포함하며, 호스팅 MCP 라인업은 플랫폼을 통해 새 모델이 출시됨에 따라 점차 확장됩니다.
Higgsfield MCP를 CI에서 헤드리스로 실행할 수 있나요?
직접적으로는 안 됩니다. 호스팅 MCP는 첫 인증 시 대화형 OAuth 왕복을 요구하는데, 이는 CI 환경에서 작동하지 않습니다. CI에는 Higgsfield CLI(@higgsfield/cli)를 사용하세요. 이는 CI 시크릿으로 저장할 수 있는 장기간 유효한 API 토큰을 사용합니다. MCP는 대화형 세션용이고, CLI는 자동화 파이프라인과 배치 생성 잡용입니다.
생성 전반에 걸쳐 캐릭터 일관성을 어떻게 얻나요?
피사체의 레퍼런스 이미지 35장으로 5분의 학습 후 캐릭터 ID를 반환합니다. 이후 Soul V2 모델로 create_character를 사용하세요. 이 도구는 약 3generate_image를 호출할 때 그 ID를 참조하면, 모든 생성에서 같은 얼굴이 나타납니다. 이는 블로그 시리즈, 제품 마스코트, 시각적 연속성이 필요한 모든 프로젝트의 핵심 패턴입니다.
Higgsfield MCP는 Sora나 Veo를 직접 호출하는 것보다 비싼가요?
대부분의 경우 대체로 비슷합니다. Higgsfield는 API 용량을 대량으로 매입해 크레딧으로 재판매하므로, 생성당 비용은 근간이 되는 제공업체와 큰 차이가 없습니다. 대신 통합 청구, 수많은 API 키 대신 OAuth, MCP를 통한 대화형 UX를 얻습니다. 일회성 스크립트라면 직접 호출이 조금 저렴할 수 있지만, 지속적인 창작 작업에는 Higgsfield가 더 단순한 길입니다.
Higgsfield MCP는 Claude Code에서 무료로 사용할 수 있나요?
네, 무료 등급은 월 150크레딧을 무료로 제공하며, 이는 대략 GPT Image 2 스틸 15장이나 Veo 3.1 비디오 클립 2개에 해당합니다. Claude Code 자체는 MCP 도구 호출에 추가 요금을 부과하지 않습니다. 무료 지급량을 초과하면 선불 크레딧은 대략 $1당 16크레딧입니다. 히어로를 대량으로 생성하는 팀에게는 유료 플랜이 가치 있고, 개인 개발자에게는 무료 등급으로 가볍고 중간 정도의 사용량을 감당할 수 있습니다.
Claude Code에서 Higgsfield MCP로 무엇을 생성할 수 있나요?
이 서버는 이미지 생성(단일 샷, 제품 촬영, 스타일화된 일러스트), 비디오 생성(Veo 3.1이나 Kling 3.0으로 최대 15초의 시네마틱 클립), 그리고 시각적 일관성을 위한 캐릭터 학습을 제공합니다. 실제로 팀들은 블로그 히어로 이미지, OG 카드, 제품 목업, 짧은 포스팅 요약 애니메이션에 이를 사용하며, 이 모든 것을 별도의 창작 도구가 아닌 Claude Code 컨텍스트 엔지니어링 워크플로우 안에서 처리합니다.
로드맵에 AI 기능이 있다면, 그것이 바로 저희 전문 분야입니다. Techsy의 AI 통합 팀은 LLM 시스템을 프로토타입에서 프로덕션까지 이끌어 드립니다.
마무리
이것이 전체 여정입니다. Claude Code용 한 줄 설치, 그 외 모든 주요 MCP 클라이언트용 JSON 스니펫, MCSLA 프롬프트 작성법, 일관성을 위한 Soul Character 워크플로우, 그리고 미리 알지 못하면 오후를 통째로 날릴 함정 5가지까지. Higgsfield는 저희 개발자를 위한 최고의 MCP 서버 모음 글에서 가장 즉각적으로 유용한 항목 중 하나로, 서버 스택 전체를 구축 중이라면 즐겨찾기해 둘 가치가 있습니다. 아직 AI 클라이언트를 고르는 중이라면 Claude Code vs Cursor vs Copilot 비교 글이 더 넓은 지형을 다룹니다. 그리고 Higgsfield MCP가 반복 가능한 콘텐츠 제작 루틴에 어떻게 들어맞는지 보고 싶다면, Claude Code 워크플로우 가이드에서 전체 설정을 확인할 수 있습니다.
Higgsfield MCP를 Sanity나 원하는 CMS와 함께 팀의 콘텐츠 파이프라인에 연결하는 일을 저희에게 맡기고 싶다면, 무료 상담을 받아보세요.