MCP: collega un assistente AI

MCP (Model Context Protocol) è lo standard che permette a un assistente AI di collegarsi a un servizio esterno e usarlo davvero, non solo parlarne. Collegando Yellohu al tuo assistente, puoi chiedere un preventivo, creare una spedizione, controllare un tracking o prenotare un ritiro semplicemente scrivendo in linguaggio naturale: l'assistente si occupa di chiamare l'API al posto tuo.

Serve una chiave dedicata (diversa da quella dell'integrazione API diretta, se ne hai già una) e un client compatibile MCP: qui sotto trovi le istruzioni per i principali.

Vai in dashboard, sezione Integrazioni, card "MCP". Genera una chiave Sandbox per provare senza rischi (non tocca mai corrieri o pagamenti reali), oppure Live per azioni reali. In entrambi i casi ogni azione che crea o annulla qualcosa richiede comunque la tua conferma esplicita prima di essere eseguita davvero.

Subito dopo la creazione vedrai anche uno snippet di configurazione pronto da copiare: le istruzioni qui sotto ti dicono dove incollarlo per ciascun client.

1. 1

   Non usare Impostazioni → Connettori

   Quella schermata in Claude Desktop supporta solo l'autenticazione OAuth, non una chiave API come la nostra. Il percorso giusto è modificare direttamente il file di configurazione.

2. 2

   Apri il file di configurazione

   Su macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. Su Windows: %APPDATA%\Claude\claude_desktop_config.json. Se non esiste ancora, crealo.

3. 3

   Aggiungi la configurazione

   Claude Desktop rifiuta un server remoto configurato solo con "url" e "headers" (lo segnala come voce non valida e lo ignora): serve un bridge locale via npx, il pacchetto mcp-remote, che inoltra le richieste al server reale aggiungendo l'header di autenticazione. Incolla (o unisci, se il file ha già altri server) il blocco qui sotto, sostituendo yh_mcp_live_xxx con la tua chiave.

4. 4

   Riavvia Claude Desktop

   Chiudi e riapri l'app perché la nuova configurazione venga letta.

Claude Desktop non supporta un server MCP remoto configurato direttamente con "url"/"headers": richiede il bridge locale mcp-remote (via npx, serve Node.js installato).

{
  "mcpServers": {
    "yellohu": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://yellohu.com/api/mcp",
        "--header",
        "X-Api-Key:${YELLOHU_MCP_KEY}"
      ],
      "env": {
        "YELLOHU_MCP_KEY": "yh_mcp_live_xxx"
      }
    }
  }
}

1. 1

   Esegui il comando

   Un solo comando da terminale, nessun file da modificare a mano.

claude mcp add --transport http yellohu https://yellohu.com/api/mcp --header "X-Api-Key: yh_mcp_live_xxx"

1. 1

   Apri (o crea) il file di configurazione

   .cursor/mcp.json nella cartella del progetto, oppure la configurazione globale dalle impostazioni MCP di Cursor.

2. 2

   Aggiungi la configurazione

   Incolla (o unisci) il blocco qui sotto con la tua chiave.

{
  "mcpServers": {
    "yellohu": {
      "url": "https://yellohu.com/api/mcp",
      "headers": {
        "X-Api-Key": "yh_mcp_live_xxx"
      }
    }
  }
}

1. 1

   Apri il file .vscode/mcp.json

   Deve essere specificamente questo file (workspace, cartella .vscode) e non un .mcp.json generico alla radice del progetto: un bug noto di VS Code ignora silenziosamente l'header di autenticazione in quel secondo caso.

2. 2

   Aggiungi la configurazione

   Attenzione a due differenze rispetto agli altri client: la chiave principale è "servers", non "mcpServers", e serve un campo "type": "http" esplicito.

VS Code usa un formato leggermente diverso dagli altri client: chiave "servers" (non "mcpServers") e campo "type" obbligatorio.

{
  "servers": {
    "yellohu": {
      "type": "http",
      "url": "https://yellohu.com/api/mcp",
      "headers": {
        "X-Api-Key": "yh_mcp_live_xxx"
      }
    }
  }
}

1. 1

   Apri il file di configurazione

   ~/.codeium/windsurf/mcp_config.json.

2. 2

   Aggiungi la configurazione

   Attenzione: Windsurf chiama il campo dell'URL "serverUrl", non "url" come gli altri client. Copiare una config da un altro client senza rinominare questo campo è l'errore più comune.

Windsurf usa "serverUrl", non "url", per l'indirizzo del server.

{
  "mcpServers": {
    "yellohu": {
      "serverUrl": "https://yellohu.com/api/mcp",
      "headers": {
        "X-Api-Key": "yh_mcp_live_xxx"
      }
    }
  }
}

1. 1

   Attiva la modalità sviluppatore

   Impostazioni → Connettori → Impostazioni avanzate → attiva "Developer mode" (richiede un piano Plus, Pro, Team, Enterprise o Edu).

2. 2

   Aggiungi un nuovo connettore

   Inserisci l'URL del server (https://yellohu.com/api/mcp) e scegli l'autenticazione "API key" (non OAuth).

3. 3

   Verifica che funzioni davvero

   L'interfaccia di ChatGPT per questa parte è ancora la più recente delle sette e può cambiare: se il campo per l'autenticazione non permette di scegliere il nome dell'header, prova comunque a inserire la chiave e chiedi subito un preventivo per verificare che la connessione risponda davvero prima di fidartene.

Integrazione più recente e in evoluzione rispetto alle altre sei: verifica sempre con una richiesta reale che la connessione funzioni.

URL: https://yellohu.com/api/mcp
Autenticazione: API key
Header: X-Api-Key

1. 1

   Apri (o crea) il file ~/.codex/config.toml

   Puoi anche usare .codex/config.toml nella cartella del progetto invece che nella home. Il comando "codex mcp add" funziona solo per server locali, non per server remoti come questo: va configurato a mano nel file.

2. 2

   Aggiungi la configurazione

   Incolla il blocco qui sotto con la tua chiave. Nota: Codex usa il formato TOML, non JSON come gli altri client.

Codex usa TOML invece di JSON e non ha un comando da terminale per i server remoti: va sempre configurato modificando il file.

[mcp_servers.yellohu]
url = "https://yellohu.com/api/mcp"
http_headers = { "X-Api-Key" = "yh_mcp_live_xxx" }

Qualsiasi client MCP che supporti un server remoto via Streamable HTTP funziona allo stesso modo: stessi due valori, solo il nome dei campi può cambiare da client a client. Controlla la documentazione del tuo client per sapere come si chiamano i campi URL e header nel suo formato.

URL: https://yellohu.com/api/mcp
Header: X-Api-Key: yh_mcp_live_xxx

Le azioni che creano o annullano qualcosa per davvero (creare una spedizione, annullarla, prenotare un ritiro) non avvengono mai al primo colpo. L'assistente ti mostra sempre un riepilogo (corriere, prezzo, indirizzi) e aspetta che tu dica esplicitamente di procedere, prima di eseguire l'azione reale. Non devi scrivere nessun comando tecnico per confermare: basta rispondere normalmente, come faresti con una persona.

Puoi personalizzare questo comportamento per singola azione (creazione spedizione, annullamento, prenotazione ritiro) dalla dashboard, sezione Integrazioni, MCP, card "Autorizzazioni strumenti": puoi scegliere di eseguirla subito senza chiedere conferma, di richiederla sempre (il comportamento appena descritto, il default), oppure di disabilitarla del tutto per l'assistente AI.