> ## 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.
# Server MCP di Venice
> Il server ufficiale Venice Model Context Protocol espone 31 tool Venice per chat, immagini, video, audio, musica e character in qualsiasi host MCP.
Il [Venice MCP Server](https://github.com/veniceai/venice-mcp-server) è il server ufficiale [Model Context Protocol](https://modelcontextprotocol.io/) per Venice. Espone l'intera API Venice (chat, image, video, audio, music, embeddings, web augment e characters) come **31 tool** che qualsiasi agente compatibile con MCP può chiamare.
Pubblicato come [`@veniceai/mcp-server`](https://www.npmjs.com/package/@veniceai/mcp-server) su npm. Licenza MIT.
Ogni modalità Venice in un solo blocco di configurazione
Claude Desktop, Cursor, ChatGPT, LM Studio, Continue e altri
Porta una API key, oppure paga per chiamata con un wallet firmato SIWE tramite x402
## Avvio rapido
Generane una da [venice.ai/settings/api](https://venice.ai/settings/api). Consulta la [guida sulle API key](/guides/getting-started/generating-api-key) per istruzioni passo passo.
Inserisci questo nel file di configurazione del tuo host MCP:
```json theme={"system"}
{
"mcpServers": {
"venice": {
"command": "npx",
"args": ["-y", "@veniceai/mcp-server@0.2.0"],
"env": { "VENICE_API_KEY": "" }
}
}
}
```
Percorsi di configurazione comuni:
| Host | Percorso |
| ------------------------ | ----------------------------------------------------------------- |
| 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` (dalle impostazioni MCP dell'app) |
Il tuo agente ora ha disponibili chat, image, video, music, TTS, ASR e altri 25 tool Venice.
La maggior parte degli host MCP passa solo variabili d'ambiente **esplicitamente elencate** nel blocco `env`. Le variabili d'ambiente a livello di sistema non vengono ereditate. Se vedi errori 402 con una API key impostata, controlla due volte che `VENICE_API_KEY` sia all'interno di `env` nella tua configurazione.
## Cosa ottieni
**31 tool** che coprono ogni modalità Venice, **3 resource** (`venice://models`, `venice://styles`, `venice://voices`) e **3 template di prompt**.
### Chat ed embeddings
| Tool | Descrizione |
| ---------------------------- | ------------------------------------------------------------------------------ |
| `venice_chat` | Chat completion compatibile con OpenAI sull'intero catalogo LLM di Venice. |
| `venice_responses` | API Responses compatibile con OpenAI con supporto a tool single- o multi-turn. |
| `venice_embeddings` | Calcola gli embedding per testo in input. |
| `venice_chat_with_character` | Chatta con un personaggio Venice tramite slug. |
### Image
| Tool | Descrizione |
| ------------------------- | ----------------------------------------------------------------------------------------------------- |
| `venice_image_generate` | Genera un'immagine (Flux 2, Lustify SDXL, Anime/WAI, Qwen Image, GPT Image, Nano Banana Pro e altri). |
| `venice_image_edit` | Modifica un'immagine con un prompt. |
| `venice_image_multi_edit` | Modifica più immagini insieme con un solo prompt. |
| `venice_image_upscale` | Esegui l'upscale di un'immagine fino a 4×. |
| `venice_image_remove_bg` | Rimuovi lo sfondo di un'immagine. |
| `venice_image_styles` | Elenca i preset di stile dell'immagine. |
### Video
| Tool | Descrizione |
| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
| `venice_video_generate` | Metti in coda una generazione video (Sora 2, Veo 3.1, Kling, Wan, LTX 2, Seedance, Runway Gen-4 e altri). |
| `venice_video_status` | Controlla lo stato di un job video in coda. |
| `venice_video_complete` | Contrassegna un video completato come scaricato; elimina il media lato server. |
| `venice_video_transcriptions` | Trascrivi un URL video di YouTube. |
| `venice_video_quote` | Ottieni un preventivo prima della messa in coda. |
### Audio (TTS / ASR)
| Tool | Descrizione |
| -------------------- | --------------------------------------------------------- |
| `venice_tts` | Text-to-speech con voci clonate e tag di emozione. |
| `venice_asr` | Trascrivi audio da un URL. |
| `venice_voice_clone` | Elenca le voci integrate o clona una voce da un campione. |
| `venice_audio_quote` | Ottieni un preventivo per la generazione musicale. |
### Musica
| Tool | Descrizione |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `venice_music_generate` | Metti in coda la generazione musicale (`ace-step-15`, `elevenlabs-music`, `minimax-music-v2/v25/v26`, `stable-audio-25`, `mmaudio-v2`, `elevenlabs-sound-effects-v2`). |
| `venice_music_status` | Controlla lo stato di un job musicale in coda. |
| `venice_music_complete` | Contrassegna un job musicale completato come scaricato. |
### Web augment, catalog e crypto
| Tool | Descrizione |
| ------------------------ | ------------------------------------------------------------------------- |
| `venice_web_search` | Cerca sul web (basato su Firecrawl). |
| `venice_web_scrape` | Esegui lo scraping di un URL in markdown. |
| `venice_text_parser` | Estrai testo da PDF/DOCX/EPUB/PPTX/XLSX. |
| `venice_list_models` | Elenca il catalogo modelli live con i prezzi. |
| `venice_list_characters` | Elenca i personaggi Venice pubblici. |
| `venice_crypto_rpc` | Inoltra chiamate JSON-RPC a Base, Ethereum, Polygon, Arbitrum o Optimism. |
### Helper wallet x402
Rilevante solo se ti autentichi con un wallet tramite [x402](/guides/integrations/x402-venice-api) invece che con una API key.
| Tool | Descrizione |
| -------------------------- | --------------------------------------------------------------------------------------------------- |
| `venice_x402_balance` | Controlla il saldo di credito x402 prepagato per un indirizzo wallet EVM o Solana. |
| `venice_x402_top_up_info` | Recupera i requisiti di ricarica (rete, token USDC, ricevitore, importo minimo). |
| `venice_x402_transactions` | Elenca le ricariche x402 recenti e le transazioni di addebito per un indirizzo wallet EVM o Solana. |
## Configurazione
Il server è configurato interamente tramite variabili d'ambiente.
| Variabile d'ambiente | Default | Note |
| ---------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------- |
| `VENICE_API_KEY` | *(nessuno)* | La tua API key Venice. La configurazione più semplice. |
| `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` | Imposta a `1` per rimuovere le note sulla capacità NSFW dalle descrizioni dei tool. |
| `VENICE_HTTP_TIMEOUT_MS` | `60000` | |
| `VENICE_SIWX_TOKEN` | *(nessuno)* | Token di autenticazione in modalità wallet x402. Consulta [x402 più sotto](#x402-wallet-mode). |
Se sono impostati sia `VENICE_API_KEY` sia `VENICE_SIWX_TOKEN`, vince l'API key.
## Modalità wallet x402
Venice supporta l'autenticazione con un [token wallet Sign-In-With-X](/guides/integrations/x402-venice-api) sostenuto da credito USDC prepagato su Base o Solana, oltre al normale flusso con API key. Nessuna email, numero di telefono o KYC richiesti: il tuo wallet è l'unica identità.
```json theme={"system"}
{
"mcpServers": {
"venice": {
"command": "npx",
"args": ["-y", "@veniceai/mcp-server@0.2.0"],
"env": { "VENICE_SIWX_TOKEN": "" }
}
}
}
```
Il server MCP inoltra `VENICE_SIWX_TOKEN` come header `X-Sign-In-With-X` su ogni chiamata all'API Venice. Il server non vede mai la tua chiave privata. La firma del wallet e le autorizzazioni di ricarica USDC avvengono nel tuo wallet.
| Flusso | Cosa succede |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Configurazione una tantum** | Firma un messaggio Sign-In-With-X nel tuo wallet → produce un token SIWX (JSON base64). |
| **Ricarica** | `POST /api/v1/x402/top-up` restituisce 402 + requisiti di pagamento. Firma un pagamento USDC per una delle opzioni Base o Solana restituite, reinvia e Venice accredita il tuo saldo. |
| **Ogni chiamata di inferenza** | Il server MCP invia `X-Sign-In-With-X: `; Venice scala dal tuo saldo prepagato. |
La ricarica minima è di **\$5 USD**. Il saldo minimo per chiamare l'inferenza è **\$0,10**. Una volta ricaricato, le chiamate sono sotto i 100 ms perché la liquidazione avviene off-chain su un account di credito veloce.
I wallet collegati a un account Venice con DIEM in staking consumano dal saldo di staking invece dei crediti USDC, quindi non è necessaria la ricarica.
## Self-hosting (Streamable HTTP)
Per deploy di team o workspace, esegui il server MCP su HTTP invece che su 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
```
Il server è ora disponibile su `http://localhost:3333/mcp`. I client HTTP devono inviare `Authorization: Bearer `.
`/mcp` è un endpoint di esecuzione tool sostenuto da credenziali: i chiamanti possono spendere l'API key Venice configurata o il saldo x402. Quando la modalità HTTP si lega al di fuori del loopback, l'avvio fallisce se `VENICE_MCP_AUTH_TOKEN` non è impostato. Per la produzione, fissa esplicitamente la versione del pacchetto npm invece di affidarti a `latest`.
## Risorse
Codice sorgente, issue e release
`@veniceai/mcp-server`
Skill complementari che insegnano agli agenti come usare questi tool
Scopri di più sul Model Context Protocol