> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-docs-responses-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Venice MCP Server

> O servidor MCP oficial da Venice expõe 31 ferramentas de chat, imagem, vídeo, áudio e embeddings para Claude Desktop, Cursor e 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.

<Card title="GitHub: veniceai/venice-mcp-server" icon="github" href="https://github.com/veniceai/venice-mcp-server">
  Publicado como [`@veniceai/mcp-server`](https://www.npmjs.com/package/@veniceai/mcp-server) no npm. Licença MIT.
</Card>

<CardGroup cols={3}>
  <Card title="31 ferramentas" icon="toolbox">
    Toda modalidade da Venice em um único bloco de configuração
  </Card>

  <Card title="Qualquer host MCP" icon="plug">
    Claude Desktop, Cursor, ChatGPT, LM Studio, Continue e mais
  </Card>

  <Card title="Autenticação por carteira (opcional)" icon="wallet">
    Use uma chave de API, ou pague por chamada com uma carteira assinada por SIWE via x402
  </Card>
</CardGroup>

## Quickstart

<Steps>
  <Step title="Obtenha uma chave de API Venice">
    Gere uma em [venice.ai/settings/api](https://venice.ai/settings/api?utm_source=venice-api-documentation). Veja o [guia de chave de API](/guides/getting-started/generating-api-key) para instruções passo a passo.
  </Step>

  <Step title="Adicione a Venice à configuração do seu host MCP">
    Cole isto no arquivo de configuração do seu host MCP:

    ```json theme={null}
    {
      "mcpServers": {
        "venice": {
          "command": "npx",
          "args": ["-y", "@veniceai/mcp-server@0.2.0"],
          "env": { "VENICE_API_KEY": "<your-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) |
  </Step>

  <Step title="Reinicie seu host MCP">
    Seu agente agora tem chat, imagem, vídeo, música, TTS, ASR e mais 25 ferramentas Venice disponíveis.
  </Step>
</Steps>

<Note>
  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.
</Note>

## 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_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](#modo-carteira-x402). |

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={null}
{
  "mcpServers": {
    "venice": {
      "command": "npx",
      "args": ["-y", "@veniceai/mcp-server@0.2.0"],
      "env": { "VENICE_SIWX_TOKEN": "<base64 Sign-In-With-X payload>" }
    }
  }
}
```

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: <SIWX>`; 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.

<Tip>
  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.
</Tip>

## Auto-hospedagem (Streamable HTTP)

Para implantações de equipe ou workspace, execute o servidor MCP via HTTP em vez de stdio:

```bash theme={null}
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
```

O servidor agora está disponível em `http://localhost:3333/mcp`. Clientes HTTP devem enviar `Authorization: Bearer <VENICE_MCP_AUTH_TOKEN>`.

<Warning>
  `/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`.
</Warning>

## Recursos

<CardGroup cols={2}>
  <Card title="GitHub" icon="github" href="https://github.com/veniceai/venice-mcp-server">
    Código-fonte, issues e releases
  </Card>

  <Card title="npm" icon="npm" href="https://www.npmjs.com/package/@veniceai/mcp-server">
    `@veniceai/mcp-server`
  </Card>

  <Card title="Venice Skills" icon="book" href="/guides/integrations/venice-skills">
    Skills complementares que ensinam aos agentes como usar essas ferramentas
  </Card>

  <Card title="Spec do MCP" icon="arrow-up-right-from-square" href="https://modelcontextprotocol.io/">
    Saiba mais sobre o Model Context Protocol
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.