Venice MCP Server | Venice API Docs

Venice MCP 서버는 Venice를 위한 공식 Model Context Protocol 서버입니다. Venice API(chat, image, video, audio, music, embeddings, web augment, characters, crypto RPC, TEE attestation)와 계정 작업(결제 및 API 키)을 모든 MCP 호환 에이전트가 호출할 수 있는 45개 도구로 노출합니다.

GitHub: veniceai/venice-mcp-server

npm에는 @veniceai/mcp-server로 게시되어 있습니다. MIT 라이선스.

45개 도구

Venice의 모든 모달리티와 결제, API 키, TEE 도구

모든 MCP 호스트

Claude Desktop, Cursor, ChatGPT, LM Studio, Continue 등

지갑 인증(선택)

API 키를 가져오거나, x402로 SIWE 서명 지갑을 통해 호출당 결제

빠른 시작

Venice API 키 발급

venice.ai/settings/api에서 키를 발급받으세요. 단계별 안내는 API 키 가이드를 참고하세요.

MCP 호스트 설정에 Venice 추가

MCP 호스트 설정 파일에 다음을 넣으세요:

{
  "mcpServers": {
    "venice": {
      "command": "npx",
      "args": ["-y", "@veniceai/[email protected]"],
      "env": { "VENICE_API_KEY": "<your-venice-api-key>" }
    }
  }
}

흔한 설정 경로:

Host	Path
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Cursor	`~/.cursor/mcp.json`
LM Studio	앱의 MCP 설정에서 `mcp.json`

MCP 호스트 재시작

이제 에이전트가 chat, image, video, music, TTS, ASR 외 39개의 Venice 도구를 더 사용할 수 있습니다.

대부분의 MCP 호스트는 env 블록에 명시적으로 나열된 환경 변수만 전달합니다. 시스템 수준 env vars는 상속되지 않습니다. API 키를 설정했는데 402 에러가 보인다면, 설정의 env 안에 VENICE_API_KEY가 있는지 다시 확인하세요.

무엇을 얻나요

Venice의 모든 모달리티와 계정 작업을 아우르는 45개 도구, 3개의 리소스(venice://models, venice://styles, venice://voices), 3개의 prompt 템플릿(검열 없는 리서치, NSFW 창작 글쓰기, 이미지 스타일 탐색기). 모든 도구는 readOnlyHint, destructiveHint, idempotentHint, openWorldHint 어노테이션을 명시적으로 선언하므로, 호스트는 조회 작업을 확인 없이 실행하고 미디어 정리나 크립토 릴레이 같은 파괴적인 작업 전에는 확인을 요청할 수 있습니다.

Chat 및 임베딩

Tool	Description
`venice_chat`	Venice의 LLM 카탈로그 전체에 대한 OpenAI 호환 chat completion. text/image/audio/video/file 블록, 구조화된 출력, 함수 도구, prompt 캐싱, 추론 제어를 지원합니다. 호출은 평문이며 스트리밍되지 않습니다.
`venice_responses`	Stateless OpenAI 호환 Responses API. text/image 입력과 추론 제어를 지원합니다. 이 도구는 도구 호출 필드를 노출하지 않으며, E2EE 모델은 지원되지 않습니다.
`venice_embeddings`	텍스트 input에 대한 임베딩 계산.
`venice_chat_with_character`	slug로 Venice 캐릭터와 채팅.

이미지

Tool	Description
`venice_image_generate`	이미지 생성(Flux 2, Lustify SDXL, Anime/WAI, Qwen Image, GPT Image, Nano Banana Pro 등). 종횡비 또는 너비/높이, 품질 등급, prompt 향상, 스타일 레퍼런스, 웹 검색, 변형을 지원합니다.
`venice_image_edit`	prompt로 이미지 편집.
`venice_image_multi_edit`	하나의 prompt로 최대 8개 이미지를 함께 편집(합성 / 아웃페인팅).
`venice_image_upscale`	`creativity` 제어와 함께 이미지를 2–4×로 업스케일.
`venice_image_remove_bg`	이미지 배경 제거.
`venice_image_styles`	이미지 스타일 프리셋 목록.

비디오

Tool	Description
`venice_video_generate`	이미지, 비디오, 오디오, 레퍼런스, element 입력을 사용한 비디오 생성 큐 등록(Sora 2, Veo 3.1, Kling, Wan, LTX 2, Seedance, Runway Gen-4 등).
`venice_video_status`	큐에 등록된 비디오 작업 상태 확인(`POST /video/retrieve`).
`venice_video_complete`	완료된 비디오를 다운로드 완료로 표시하고 서버 측 미디어를 삭제합니다. Venice가 삭제를 확인한 경우에만 삭제를 보고합니다.
`venice_video_quote`	큐 등록 전 가격 견적.

오디오 (TTS / ASR)

Tool	Description
`venice_tts`	클론 음성, temperature, 감정 태그를 갖춘 text-to-speech. 스트리밍은 하나의 완전한 오디오 결과로 버퍼링됩니다.
`venice_asr`	URL에서 오디오를 전사하며, 단어/문자 타임스탬프를 선택적으로 제공합니다. 큰 전사본은 세션 핸들을 통해 페이지 단위로 제공됩니다.
`venice_voice_clone`	모델별 실시간 음성 목록을 조회하거나 샘플 URL로부터 음성을 클론합니다(`venice_tts`용 `vv_<id>` 핸들 반환).
`venice_audio_quote`	음악 생성 가격 견적.

음악

Tool	Description
`venice_music_generate`	가사, 연주곡, 루프, 음성, 언어, 속도, 길이 제어를 갖춘 음악 생성 큐 등록(`ace-step-15`, `elevenlabs-music`, `minimax-music-v2/v25/v26`, `stable-audio-25`, `mmaudio-v2-text-to-audio`, `elevenlabs-sound-effects-v2`).
`venice_music_status`	큐에 등록된 음악 작업 상태 확인.
`venice_music_complete`	완료된 음악 작업을 다운로드 완료로 표시.

웹 augment

Tool	Description
`venice_web_search`	Brave(기본값, Zero Data Retention) 또는 Google(Venice가 프록시 및 익명화)로 웹 검색.
`venice_web_scrape`	URL 하나를 마크다운으로 스크래핑.
`venice_text_parser`	PDF/DOCX/EPUB/PPTX/XLSX에서 텍스트 추출.

카탈로그 및 캐릭터

Tool	Description
`venice_list_models`	모든 유형의 실시간 모델 카탈로그를 간결한 요약, 가격, 기능 플래그와 함께 페이지 단위로 조회.
`venice_model_details`	특정 모델 하나의 전체 정보 조회: `model_spec` 제약 조건, 기능, 가격.
`venice_model_traits`	트레잇 이름(`default`, `most_uncensored`, …)을 현재 모델 ID에 매핑.
`venice_model_compatibility_mapping`	호환 모델 이름을 Venice 모델 ID에 매핑.
`venice_list_characters`	검색, 태그, 모델, 정렬 필터로 공개 Venice 캐릭터 목록 조회. API 키 전용.
`venice_get_character`	slug로 공개 캐릭터 하나 조회. API 키 전용.
`venice_character_reviews`	캐릭터의 공개 리뷰를 페이지 단위로 조회. API 키 전용.

TEE attestation

Tool	Description
`venice_tee_attestation`	사용자가 제공한 32바이트 nonce로 TEE 지원 텍스트 모델의 하드웨어 attestation 증거(Intel TDX quote, 선택적 NVIDIA 증거, 서명 키)를 가져옵니다.
`venice_tee_signature`	완료된 TEE chat 요청 ID에 대한 enclave 서명 payload를 가져옵니다.

두 TEE 도구 모두 제공자의 증거만 반환합니다: 증거를 검증하지 않으며 chat을 암호화하지도 않습니다. TEE 모델을 신뢰하기 전에 반환된 nonce, 디버그 모드 상태, 서명 키 바인딩을 직접 검증하세요. TEE Attestation 검증하기를 참고하세요. 이 서버는 enable_e2ee를 거부합니다.

크립토

Tool	Description
`venice_crypto_networks`	RPC 프록시가 허용하는 실시간 네트워크 slug 목록.
`venice_crypto_rpc`	JSON-RPC 요청 하나 또는 최대 100개의 배치를 Ethereum, Base, Arbitrum, Optimism, Polygon, Solana, Starknet, zkSync, Linea, BSC, Avalanche, Blast 등으로 프록시.

트랜잭션 브로드캐스트(eth_sendRawTransaction, eth_sendUserOperation, Solana sendTransaction, Starknet 쓰기)는 idempotency_key와 함께 단일 요청으로 보내야 하며, 재시도 시 같은 키를 재사용해야 합니다.

결제 (관리자 키)

Tool	Description
`venice_billing_balance`	현재 USD, DIEM, 번들 크레딧 사용 가능 금액.
`venice_billing_usage_analytics`	베타. 날짜, 모델, API 키별 집계 사용량(조회 기간 또는 사용자 지정 범위).
`venice_billing_usage_history`	커서 페이지네이션과 JSON 또는 CSV 출력을 지원하는 상세 사용량.

결제 도구에는 ADMIN API 키가 필요합니다. 추론 키로는 이 endpoint를 호출할 수 없으며, 서버는 지갑 토큰으로 대체하지 않고 로컬에서 실패 처리합니다.

API 키

Tool	Description
`venice_list_api_keys`	활성 키 메타데이터 목록(키는 마지막 6자만 포함). 관리자 키 전용.
`venice_get_api_key`	키 ID로 키 하나의 메타데이터, 사용량, 잔액, rate limit 조회. 관리자 키 전용.
`venice_api_key_rate_limits`	현재 잔액, 접근 상태, 등급, 만료일, 모델별 rate limit. 추론 키 또는 관리자 키.
`venice_api_key_rate_limit_logs`	최근 50건의 rate limit 초과 이벤트(실험적). 관리자 키 전용.

x402 지갑 헬퍼

API 키 대신 x402를 통해 지갑으로 인증할 때만 관련됩니다.

Tool	Description
`venice_x402_balance`	EVM 또는 Solana 지갑 주소의 선불 x402 크레딧 잔액 확인.
`venice_x402_top_up_info`	충전 요건(네트워크, USDC 토큰, 수령자, 최소 금액) 조회. 인자를 받지 않습니다.
`venice_x402_transactions`	EVM 또는 Solana 지갑 주소의 최근 x402 충전 및 차감 트랜잭션 목록.

구성

서버는 전적으로 환경 변수로 구성됩니다.

모델 및 요청

Env var	Default	Notes
`VENICE_API_KEY`	(없음)	Venice API 키. 가장 간단한 설정.
`VENICE_DEFAULT_CHAT_MODEL`	`deepseek-v4-flash-0731`
`VENICE_DEFAULT_IMAGE_MODEL`	`flux-2-pro`
`VENICE_DEFAULT_TTS_MODEL`	`tts-kokoro`
`VENICE_DEFAULT_ASR_MODEL`	`openai/whisper-large-v3`
`VENICE_DISABLE_NSFW`	`0`	`1`로 설정하면 도구 설명에서 NSFW 가능 표시 제거.
`VENICE_HTTP_TIMEOUT_MS`	`60000`
`VENICE_SIWX_TOKEN`	(없음)	x402 지갑 모드 인증 토큰. 아래 x402 참고.

VENICE_API_KEY와 VENICE_SIWX_TOKEN이 모두 설정되어 있으면 대부분의 호출에서 API 키가 우선합니다. 예외는 인증 모드 지원 범위를 참고하세요.

응답 크기 제한

생성된 미디어는 버퍼링되어 MCP 결과에 base64로 포함되므로, 각 모달리티에는 바이트 상한이 있습니다.

Env var	Default	Applies to
`VENICE_MAX_IMAGE_RESPONSE_BYTES`	`33554432` (32 MiB)	`venice_image_generate`, `venice_image_edit`, `venice_image_multi_edit`, `venice_image_upscale`, `venice_image_remove_bg`
`VENICE_MAX_VIDEO_RESPONSE_BYTES`	`26214400` (25 MiB)	`venice_video_status`
`VENICE_MAX_AUDIO_RESPONSE_BYTES`	`33554432` (32 MiB)	`venice_tts`, `venice_music_status`

크기를 초과한 이미지 또는 TTS 결과는 에러와 함께 폐기됩니다. 크기를 초과한 비디오 또는 음악 결과는 큐에 남아 있으므로, 제한을 올린 후 같은 큐 ID로 상태 도구를 다시 호출할 수 있습니다.

HTTP 서버

Streamable HTTP 배포에서만 관련됩니다.

Env var	Default	Notes
`PORT`	`3333`	HTTP 리스너 포트.
`VENICE_MCP_HOST`	`127.0.0.1`	바인드 주소. LAN 또는 컨테이너 노출을 위해서는 `0.0.0.0`으로 설정하세요.
`VENICE_MCP_AUTH_TOKEN`	(없음)	`/mcp`용 Bearer 토큰. loopback 외부에 바인딩할 때 필수이며, 이 경우 최소 16자 이상이어야 합니다. 설정하면 loopback에서도 적용됩니다.
`VENICE_MCP_ALLOW_UNAUTHENTICATED_HTTP`	`0`	인증 없이 노출된 HTTP를 허용하는 비상 탈출구. 신뢰할 수 있는 인증 프록시 뒤에서만 사용하세요.
`VENICE_MCP_MAX_SESSIONS`	`100`	최대 활성 Streamable HTTP 세션 수.
`VENICE_MCP_SESSION_TTL_MS`	`1800000`	정리되기 전까지의 유휴 세션 수명.

미디어 생성 동작

완료된 미디어는 바이트 또는 URL일 수 있습니다. 비디오 및 음악 작업은 포함된 MP4/오디오 리소스를 반환하거나, 리소스 링크로 반환되는 download_url이 담긴 JSON을 반환합니다. 먼저 해당 링크를 다운로드한 후 venice_video_complete 또는 venice_music_complete를 호출하세요. 파일이 삭제되면 링크가 작동하지 않으므로 download_url 결과에는 미디어 정리가 절대 적용되지 않습니다.
일부 모델은 큐 등록 시점에만 URL을 반환합니다. VPS 및 Grok Imagine Private 모델의 경우 venice_video_generate가 반환한 download_url을 저장해 두었다가 venice_video_status에 전달하세요. 인라인 URL 없이 COMPLETED로 조회되더라도 사용 가능한 링크를 얻을 수 있습니다.
prompt 향상 결과가 함께 보고됩니다. enhance_prompt가 적용되면, 이미지 생성, 편집, 다중 편집 결과에 Venice가 반환한 URL 디코딩된 prompt가 포함됩니다.
ASR 페이징은 한 번만 과금됩니다. 8,000자를 초과하는 전사본이나 한 페이지에 들어가는 것보다 많은 타임스탬프(기본적으로 배열당 200개, timestamp_limit으로 최대 500개)가 있는 전사본은 첫 페이지와 함께 result_handle을 반환합니다. 이후 페이지는 해당 핸들로 요청하세요. 핸들은 MCP 세션별로 10분 동안 메모리에 유지되며, 가장 최근 16개만 보관됩니다.
Seedance 동의는 정책 우회가 아닙니다. 현재 공개된 Seedance 모델은 식별 가능한 사람이 포함된 미디어를 바로 거부할 수 있습니다. needs_consent 응답이 반환되는 경우 세 개의 consents.seedance 플래그는 법적 확인 사항입니다: 사용자가 각 진술을 명시적으로 확인한 후에만 true로 설정하세요.

x402 지갑 모드

Venice는 일반 API 키 흐름 외에도 Base 또는 Solana의 선불 USDC 크레딧을 기반으로 한 Sign-In-With-X 지갑 토큰을 통한 인증을 지원합니다. 이메일, 전화번호, KYC 불필요: 지갑이 유일한 신원입니다.

{
  "mcpServers": {
    "venice": {
      "command": "npx",
      "args": ["-y", "@veniceai/[email protected]"],
      "env": { "VENICE_SIWX_TOKEN": "<base64 Sign-In-With-X payload>" }
    }
  }
}

MCP 서버는 모든 Venice API 호출에 VENICE_SIWX_TOKEN을 SIGN-IN-WITH-X 헤더로 전달합니다. 서버는 사용자의 private key를 절대 볼 수 없습니다. 지갑 서명과 USDC 충전 승인은 사용자의 지갑 내부에서 발생합니다.

Flow	What happens
일회성 설정	지갑에서 Sign-In-With-X 메시지에 서명 → SIWX 토큰(base64 JSON) 생성.
충전	`POST /api/v1/x402/top-up`이 402와 결제 요건을 반환. 반환된 Base 또는 Solana 옵션 중 하나에 대한 USDC 결제를 서명하고 재제출하면, Venice가 잔액에 크레딧합니다.
모든 추론 호출	MCP 서버가 `SIGN-IN-WITH-X: <SIWX>`를 보내고, Venice가 선불 잔액을 차감.

최소 충전액은 $5 USD입니다. 추론 호출을 위한 최소 잔액은 $0.10입니다. 한 번 충전하면 정산이 빠른 크레딧 계정의 오프체인에서 일어나므로 호출은 100ms 미만입니다.

DIEM이 스테이킹된 Venice 계정에 연결된 지갑은 USDC 크레딧 대신 스테이킹 잔액에서 소비하므로 충전이 필요 없습니다.

Venice는 추론 경로에서 결제 헤더를 받지 않으므로, 이 서버는 결제 헤더를 절대 보내지 않습니다. PAYMENT-SIGNATURE는 /x402/top-up에만 해당하며, 충전 헬퍼는 결제를 제출하지 않고 요건만 조회합니다.

인증 모드 지원 범위

일부 endpoint는 하나의 인증 모드만 허용합니다:

Tool	API key	x402
추론, 미디어, 웹 augment, 크립토 RPC, 캐릭터 채팅	✓	✓
`venice_list_characters`, `venice_get_character`, `venice_character_reviews`	✓	✗
`venice_billing_*`, `venice_list_api_keys`, `venice_get_api_key`, `venice_api_key_rate_limit_logs`	✓ (관리자)	✗
`venice_api_key_rate_limits`	✓ (모든 키)	✗
`venice_x402_balance`, `venice_x402_transactions`	✗	✓
`venice_x402_top_up_info`	✓	✓

두 자격 증명이 모두 설정되어 있으면, 항상 지갑 토큰을 보내는 venice_x402_balance와 venice_x402_transactions를 제외한 모든 인증 호출에 API 키가 사용됩니다.

셀프 호스팅 (Streamable HTTP)

팀이나 워크스페이스 배포의 경우 stdio 대신 HTTP로 MCP 서버를 실행하세요:

docker run -p 3333:3333 \
  -e VENICE_API_KEY=<your-venice-api-key> \
  -e VENICE_MCP_AUTH_TOKEN=<choose-a-long-random-token> \
  ghcr.io/veniceai/venice-mcp-server:latest

이제 서버는 http://localhost:3333/mcp에서 사용 가능합니다. HTTP 클라이언트는 Authorization: Bearer <VENICE_MCP_AUTH_TOKEN>을 전송해야 하며, 새 세션은 mcp-session-id 헤더 없이 생성한 후 서버가 발급한 세션 ID를 재사용해야 합니다.

/mcp는 자격 증명 기반 도구 실행 endpoint입니다: 호출자는 구성된 Venice API 키나 x402 잔액을 소비할 수 있습니다. HTTP 모드가 loopback 외부에 바인딩될 때 VENICE_MCP_AUTH_TOKEN이 설정되어 있거나, 신뢰할 수 있는 인증 프록시 뒤에서 VENICE_MCP_ALLOW_UNAUTHENTICATED_HTTP=1이 설정되어 있지 않으면 시작이 실패합니다. 프로덕션에서는 latest에 의존하지 말고 npm 패키지 버전을 명시적으로 고정하세요.

리소스

GitHub

소스 코드, 이슈, 릴리스

npm

@veniceai/mcp-server

Venice Skills

이 도구들의 사용법을 에이전트에게 가르치는 동반 스킬

MCP 스펙

Model Context Protocol에 대해 더 알아보기

GitHub: veniceai/venice-mcp-server

45개 도구

모든 MCP 호스트

지갑 인증(선택)

​빠른 시작

​무엇을 얻나요

​Chat 및 임베딩

​이미지

​비디오

​오디오 (TTS / ASR)

​음악

​웹 augment

​카탈로그 및 캐릭터

​TEE attestation

​크립토

​결제 (관리자 키)

​API 키

​x402 지갑 헬퍼

​구성

​모델 및 요청

​응답 크기 제한

​HTTP 서버

​미디어 생성 동작

​x402 지갑 모드

​인증 모드 지원 범위

​셀프 호스팅 (Streamable HTTP)

​리소스

GitHub

npm

Venice Skills

MCP 스펙

빠른 시작

무엇을 얻나요

Chat 및 임베딩

이미지

비디오

오디오 (TTS / ASR)

음악

웹 augment

카탈로그 및 캐릭터

TEE attestation

크립토

결제 (관리자 키)

API 키

x402 지갑 헬퍼

구성

모델 및 요청

응답 크기 제한

HTTP 서버

미디어 생성 동작

x402 지갑 모드

인증 모드 지원 범위

셀프 호스팅 (Streamable HTTP)

리소스