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

# Server MCP di Venice

> Il server MCP ufficiale di Venice espone 31 tool per chat, immagini, video, audio ed embeddings a Claude Desktop, Cursor e 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.

<Card title="GitHub: veniceai/venice-mcp-server" icon="github" href="https://github.com/veniceai/venice-mcp-server">
  Pubblicato come [`@veniceai/mcp-server`](https://www.npmjs.com/package/@veniceai/mcp-server) su npm. Licenza MIT.
</Card>

<CardGroup cols={3}>
  <Card title="31 tool" icon="toolbox">
    Ogni modalità Venice in un solo blocco di configurazione
  </Card>

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

  <Card title="Wallet auth (opzionale)" icon="wallet">
    Porta una API key, oppure paga per chiamata con un wallet firmato SIWE tramite x402
  </Card>
</CardGroup>

## Avvio rapido

<Steps>
  <Step title="Ottieni una API key Venice">
    Generane una da [venice.ai/settings/api](https://venice.ai/settings/api?utm_source=venice-api-documentation). Consulta la [guida sulle API key](/guides/getting-started/generating-api-key) per istruzioni passo passo.
  </Step>

  <Step title="Aggiungi Venice alla configurazione del tuo host MCP">
    Inserisci questo nel file di configurazione del tuo 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>" }
        }
      }
    }
    ```

    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) |
  </Step>

  <Step title="Riavvia il tuo host MCP">
    Il tuo agente ora ha disponibili chat, image, video, music, TTS, ASR e altri 25 tool Venice.
  </Step>
</Steps>

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

## 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_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](#modalità-wallet-x402). |

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

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

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

## Self-hosting (Streamable HTTP)

Per deploy di team o workspace, esegui il server MCP su HTTP invece che su 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
```

Il server è ora disponibile su `http://localhost:3333/mcp`. I client HTTP devono inviare `Authorization: Bearer <VENICE_MCP_AUTH_TOKEN>`.

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

## Risorse

<CardGroup cols={2}>
  <Card title="GitHub" icon="github" href="https://github.com/veniceai/venice-mcp-server">
    Codice sorgente, issue e release
  </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">
    Skill complementari che insegnano agli agenti come usare questi tool
  </Card>

  <Card title="Specifica MCP" icon="arrow-up-right-from-square" href="https://modelcontextprotocol.io/">
    Scopri di più sul Model Context Protocol
  </Card>
</CardGroup>


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