> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Venice MCP Server
> O servidor oficial Model Context Protocol da Venice expõe 31 ferramentas Venice para chat, imagem, vídeo, áudio, música e personagens em qualquer host MCP.
O [Venice MCP Server](https://github.com/veniceai/venice-mcp-server) é o servidor oficial do [Model Context Protocol](https://modelcontextprotocol.io/) para a Venice. Ele expõe a API Venice completa (chat, imagem, vídeo, áudio, música, embeddings, web augment e characters) como **31 ferramentas** que qualquer agente compatível com MCP pode chamar.
Publicado como [`@veniceai/mcp-server`](https://www.npmjs.com/package/@veniceai/mcp-server) no npm. Licença MIT.
Toda modalidade da Venice em um único bloco de configuração
Claude Desktop, Cursor, ChatGPT, LM Studio, Continue e mais
Use uma chave de API, ou pague por chamada com uma carteira assinada por SIWE via x402
## Quickstart
Gere uma em [venice.ai/settings/api](https://venice.ai/settings/api). Veja o [guia de chave de API](/guides/getting-started/generating-api-key) para instruções passo a passo.
Cole isto no arquivo de configuração do seu host MCP:
```json theme={"system"}
{
"mcpServers": {
"venice": {
"command": "npx",
"args": ["-y", "@veniceai/mcp-server@0.2.0"],
"env": { "VENICE_API_KEY": "" }
}
}
}
```
Caminhos comuns de configuração:
| Host | Caminho |
| ------------------------ | ----------------------------------------------------------------- |
| 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.json` (a partir das configurações de MCP do app) |
Seu agente agora tem chat, imagem, vídeo, música, TTS, ASR e mais 25 ferramentas Venice disponíveis.
A maioria dos hosts MCP só passa variáveis de ambiente que estão **explicitamente listadas** no bloco `env`. Variáveis de ambiente do sistema não são herdadas. Se você ver erros 402 com uma chave de API definida, verifique novamente se `VENICE_API_KEY` está dentro de `env` na sua configuração.
## O que você obtém
**31 ferramentas** abrangendo cada modalidade Venice, **3 recursos** (`venice://models`, `venice://styles`, `venice://voices`) e **3 templates de prompt**.
### Chat e embeddings
| Ferramenta | Descrição |
| ---------------------------- | ------------------------------------------------------------------------------------ |
| `venice_chat` | Chat completion compatível com OpenAI contra o catálogo LLM completo da Venice. |
| `venice_responses` | Responses API compatível com OpenAI com suporte a ferramentas single- ou multi-turn. |
| `venice_embeddings` | Calcula embeddings para entrada de texto. |
| `venice_chat_with_character` | Conversa com um personagem Venice por slug. |
### Imagem
| Ferramenta | Descrição |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| `venice_image_generate` | Gera uma imagem (Flux 2, Lustify SDXL, Anime/WAI, Qwen Image, GPT Image, Nano Banana Pro e mais). |
| `venice_image_edit` | Edita uma imagem com um prompt. |
| `venice_image_multi_edit` | Edita várias imagens juntas com um único prompt. |
| `venice_image_upscale` | Faz upscale de uma imagem até 4×. |
| `venice_image_remove_bg` | Remove o fundo de uma imagem. |
| `venice_image_styles` | Lista presets de estilo de imagem. |
### Vídeo
| Ferramenta | Descrição |
| ----------------------------- | --------------------------------------------------------------------------------------------------- |
| `venice_video_generate` | Enfileira uma geração de vídeo (Sora 2, Veo 3.1, Kling, Wan, LTX 2, Seedance, Runway Gen-4 e mais). |
| `venice_video_status` | Verifica o status de um job de vídeo enfileirado. |
| `venice_video_complete` | Marca um vídeo concluído como baixado; exclui a mídia no servidor. |
| `venice_video_transcriptions` | Transcreve uma URL de vídeo do YouTube. |
| `venice_video_quote` | Obtém uma cotação de preço antes de enfileirar. |
### Áudio (TTS / ASR)
| Ferramenta | Descrição |
| -------------------- | ---------------------------------------------------------------- |
| `venice_tts` | Texto para fala com vozes clonadas e tags de emoção. |
| `venice_asr` | Transcreve áudio a partir de uma URL. |
| `venice_voice_clone` | Lista vozes integradas ou clona uma voz a partir de uma amostra. |
| `venice_audio_quote` | Obtém uma cotação de preço para geração de música. |
### Música
| Ferramenta | Descrição |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `venice_music_generate` | Enfileira geração de música (`ace-step-15`, `elevenlabs-music`, `minimax-music-v2/v25/v26`, `stable-audio-25`, `mmaudio-v2`, `elevenlabs-sound-effects-v2`). |
| `venice_music_status` | Verifica o status de um job de música enfileirado. |
| `venice_music_complete` | Marca um job de música concluído como baixado. |
### Web augment, catálogo e cripto
| Ferramenta | Descrição |
| ------------------------ | --------------------------------------------------------------------------------- |
| `venice_web_search` | Pesquisa na web (com tecnologia Firecrawl). |
| `venice_web_scrape` | Faz scraping de uma URL para markdown. |
| `venice_text_parser` | Extrai texto de PDF/DOCX/EPUB/PPTX/XLSX. |
| `venice_list_models` | Lista o catálogo de modelos em tempo real com preços. |
| `venice_list_characters` | Lista personagens públicos da Venice. |
| `venice_crypto_rpc` | Intermedeia chamadas JSON-RPC para Base, Ethereum, Polygon, Arbitrum ou Optimism. |
### Helpers de carteira x402
Relevante apenas se você se autenticar com uma carteira via [x402](/guides/integrations/x402-venice-api) em vez de uma chave de API.
| Ferramenta | Descrição |
| -------------------------- | ----------------------------------------------------------------------------------- |
| `venice_x402_balance` | Verifica saldo de crédito pré-pago x402 para um endereço de carteira EVM ou Solana. |
| `venice_x402_top_up_info` | Busca requisitos de recarga (rede, token USDC, receiver, valor mínimo). |
| `venice_x402_transactions` | Lista transações recentes de recarga e débito x402 para um endereço EVM ou Solana. |
## Configuração
O servidor é configurado inteiramente por variáveis de ambiente.
| Variável de ambiente | Padrão | Notas |
| ---------------------------- | ------------------------- | ------------------------------------------------------------------------------------- |
| `VENICE_API_KEY` | *(nenhuma)* | Sua chave de API Venice. A configuração mais simples. |
| `VENICE_DEFAULT_CHAT_MODEL` | `venice-uncensored` | |
| `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` | Defina como `1` para remover notas de capacidade NSFW das descrições das ferramentas. |
| `VENICE_HTTP_TIMEOUT_MS` | `60000` | |
| `VENICE_SIWX_TOKEN` | *(nenhum)* | Token de auth para o modo carteira x402. Veja [x402 abaixo](#x402-wallet-mode). |
Se ambos `VENICE_API_KEY` e `VENICE_SIWX_TOKEN` estiverem definidos, a chave de API prevalece.
## Modo carteira x402
A Venice suporta autenticação com um [token de carteira Sign-In-With-X](/guides/integrations/x402-venice-api) lastreado por crédito USDC pré-pago na Base ou Solana, além do fluxo normal de chave de API. Sem necessidade de e-mail, telefone ou KYC: sua carteira é a única identidade.
```json theme={"system"}
{
"mcpServers": {
"venice": {
"command": "npx",
"args": ["-y", "@veniceai/mcp-server@0.2.0"],
"env": { "VENICE_SIWX_TOKEN": "" }
}
}
}
```
O servidor MCP encaminha `VENICE_SIWX_TOKEN` como o cabeçalho `X-Sign-In-With-X` em cada chamada à API Venice. O servidor nunca vê sua chave privada. A assinatura da carteira e as autorizações de recarga em USDC acontecem na sua própria carteira.
| Fluxo | O que acontece |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Configuração única** | Assine uma mensagem Sign-In-With-X em sua carteira → produz um token SIWX (JSON em base64). |
| **Recarregar** | `POST /api/v1/x402/top-up` retorna 402 + requisitos de pagamento. Assine um pagamento USDC para uma das opções de Base ou Solana retornadas, reenvie e a Venice credita seu saldo. |
| **Cada chamada de inferência** | O servidor MCP envia `X-Sign-In-With-X: `; a Venice debita seu saldo pré-pago. |
A recarga mínima é de **\$5 USD**. O saldo mínimo para chamar inferência é de **\$0,10**. Uma vez recarregadas, as chamadas têm latência abaixo de 100ms porque a liquidação acontece off-chain em uma conta de crédito rápida.
Carteiras vinculadas a uma conta Venice com DIEM em staking consomem do saldo de staking em vez de créditos USDC, então não é necessária recarga.
## Auto-hospedagem (Streamable HTTP)
Para implantações de equipe ou workspace, execute o servidor MCP via HTTP em vez de stdio:
```bash theme={"system"}
docker run -p 3333:3333 \
-e VENICE_API_KEY= \
-e VENICE_MCP_AUTH_TOKEN= \
ghcr.io/veniceai/venice-mcp-server:latest
```
O servidor agora está disponível em `http://localhost:3333/mcp`. Clientes HTTP devem enviar `Authorization: Bearer `.
`/mcp` é um endpoint de execução de ferramentas com credenciais: chamadores podem gastar a chave de API Venice configurada ou o saldo x402. Quando o modo HTTP é ligado a um endereço fora do loopback, a inicialização falha a menos que `VENICE_MCP_AUTH_TOKEN` esteja definido. Para produção, fixe a versão do pacote npm explicitamente em vez de depender de `latest`.
## Recursos
Código-fonte, issues e releases
`@veniceai/mcp-server`
Skills complementares que ensinam aos agentes como usar essas ferramentas
Saiba mais sobre o Model Context Protocol