Claude MCP

Il Model Context Protocol (MCP) è uno standard aperto che consente agli assistenti AI come Claude di accedere in modo sicuro a strumenti e fonti di dati esterni. Finn espone un server MCP, quindi puoi collegare Finn a Claude (o a qualsiasi client compatibile con MCP) e far sì che il tuo assistente AI interroghi, configuri e gestisca la piattaforma in modo conversazionale.

A chi è rivolto. È pensato per utenti esperti — sviluppatori, ingegneri dell'automazione e operatori con dimestichezza con l'AI che vogliono pilotare Finn da Claude Desktop, Claude Code o qualsiasi altro client MCP. Se non conosci Claude o MCP, non ti serve: la dashboard fa tutto ciò che espone l'MCP.

Stato: il server MCP di Finn è in beta pubblica. Le API sono stabili, ma vengono aggiunti regolarmente nuovi strumenti.

Cosa puoi fare con l'MCP

Una volta effettuata la connessione, il tuo Claude (o un'altra AI compatibile con MCP) può fare tutto quanto segue per tuo conto:

Operazioni di lettura

• Ottenere lo stato di qualsiasi deployment.
• Elencare i tuoi Finn, le audience e i numeri di telefono.
• Estrarre trascrizioni delle chiamate e analytics per qualsiasi intervallo temporale.
• Cercare pattern specifici nello storico chiamate ("mostrami le chiamate in cui il chiamante ha citato 'rimborso'").
• Leggere i costi dei deployment, l'utilizzo del piano e i riepiloghi di fatturazione.

Operazioni di scrittura

• Avviare un nuovo deployment.
• Mettere in pausa o interrompere un deployment attivo.
• Aggiungere contatti a un'audience.
• Aggiornare i campi di analisi post-chiamata su un Finn.
• Sopprimere numeri (aggiungerli alla lista do-not-call).

Coordinamento

• Generare automaticamente report settimanali/mensili.
• Incrociare gli esiti delle chiamate con il tuo CRM per rilevare lacune di attribuzione.
• Creare automaticamente un nuovo deployment quando una lista CRM raggiunge una dimensione soglia.
• Riassumere un deployment in linguaggio semplice, adatto alla condivisione con uno stakeholder non tecnico.

Configurare il server MCP

Passaggio 1 — Genera un token MCP

Impostazioni → Integrazioni → MCP → Genera token.

Copia subito il token: lo vedrai una sola volta. Conservalo nel tuo password manager o secret store.

Gli scope del token sono configurabili:

• Sola lettura — interroga i dati senza modificarli
• Lettura + scrittura — accesso operativo completo (da usare con cautela)
• Limitato a Finn/audience specifici — restringe l'accesso a un sottoinsieme

Per la maggior parte degli utenti, conviene iniziare in sola lettura per prendere confidenza ed estendere gli scope in seguito.

Passaggio 2 — Configura il tuo client MCP

Claude Desktop (Mac, Windows):

Modifica il file di configurazione di Claude Desktop:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Aggiungi il server Finn:

{
  "mcpServers": {
    "finnai": {
      "command": "npx",
      "args": ["-y", "@finnai/mcp-server"],
      "env": {
        "FINNAI_API_TOKEN": "your_token_here"
      }
    }
  }
}

Riavvia Claude Desktop. Gli strumenti Finn diventano disponibili in qualsiasi conversazione.

Claude Code (CLI):

claude mcp add finnai \
  --command "npx -y @finnai/mcp-server" \
  --env FINNAI_API_TOKEN=your_token_here

Poi claude da qualsiasi directory — gli strumenti Finn sono disponibili.

Altri client MCP (Continue, Cursor, personalizzati):

Usa lo stesso comando npx nella configurazione del server MCP del tuo client. Il server usa MCP standard su stdio.

Passaggio 3 — Testare la connessione

In Claude (qualsiasi client), chiedi:

"Quali Finn ho configurato?"

Se la connessione funziona, Claude chiama lo strumento list_finns e risponde con dati reali.

Strumenti esposti dall'MCP

Il server fornisce circa 30 strumenti. In evidenza:

Gestione dei Finn

• list_finns — elenca tutti i Finn dell'account.
• get_finn — recupera la configurazione completa di un Finn.
• create_finn — crea un nuovo Finn (avanzato).
• update_finn — modifica le impostazioni di un Finn.

Gestione delle audience

• list_audiences — elenca tutte le audience.
• get_audience_stats — conteggi, stato di validazione, importazioni recenti.
• add_contacts — aggiunta massiva di contatti.
• remove_contact — rimuove un singolo contatto.

Ciclo di vita del deployment

• list_deployments — elenca i deployment passati e attivi.
• launch_deployment — ne avvia uno nuovo.
• pause_deployment / resume_deployment / stop_deployment.
• get_deployment_status — stato in tempo reale con il conteggio delle chiamate correnti.

Analytics

• get_deployment_analytics — metriche complete di un deployment.
• search_calls — trova le chiamate che corrispondono a determinati pattern di contenuto.
• get_call — recupera la trascrizione e l'analisi di una singola chiamata.
• aggregate_calls — aggregazioni personalizzate per qualsiasi campo e intervallo di tempo.

Conformità

• add_to_suppression_list — blocca un numero a livello globale.
• remove_from_suppression_list — rimuove il blocco.
• check_suppression — verifica se un numero è nella lista.

Fatturazione

• get_usage_this_month — spesa corrente.
• forecast_month_end — proiezione basata sull'andamento.
• set_spend_cap — modifica i limiti.

Schema completo di ogni strumento: api.hirefinn.ai/academy/mcp.

Cose che puoi chiedere a Claude di fare

Prompt reali che funzionano:

"Mostrami i risultati del deployment di ieri e dimmi quale Finn ha ottenuto i risultati migliori."

"Trova tutte le chiamate dell'ultima settimana in cui il chiamante ha detto 'troppo caro' e riassumi il contesto ricorrente."

"Avvia lo stesso deployment di lunedì scorso, ma sulla nuova audience che ho caricato stamattina."

"Quanto abbiamo speso la settimana scorsa ed è in linea con il nostro budget?"

"Aggiungi questi numeri di telefono alla lista di soppressione: [incolla elenco]"

"Qual è la differenza nel tasso di successo tra le chiamate del mattino e quelle del pomeriggio?"

"Genera un riepilogo di 1 pagina della campagna di promemoria appuntamenti del mese scorso per il responsabile della clinica."

L'MCP rende Finn conversazionale. Operazioni che richiederebbero 5-10 clic nella dashboard diventano una singola richiesta in linguaggio naturale.

Considerazioni sulla sicurezza

Cosa può fare il token

Gli scope del token determinano cosa è consentito:

• Token in sola lettura → può interrogare tutto ma non modificare nulla.
• Lettura + scrittura → accesso operativo completo. Trattalo come la password della tua dashboard.
• Token con scope limitato → limitano per ID Finn, ID audience o tipo di operazione.

Best practice

• Non incollare i token nei messaggi di chat. Usa variabili d'ambiente nella configurazione del tuo client MCP.
• Ruota i token periodicamente. Impostazioni → Integrazioni → MCP → Ruota.
• Usa token con scope limitato per i membri del team. Non dare a un collaboratore esterno un token ad accesso completo.
• Log di audit. Ogni chiamata MCP viene registrata. Impostazioni → Integrazioni → MCP → Registro attività.
• Revoca subito i token compromessi. Impostazioni → Integrazioni → MCP → Revoca.

Cosa non può fare Claude

L'MCP non espone:

• Creazione/eliminazione account
• Modifiche ai metodi di pagamento
• Upgrade/downgrade del piano
• Inviti ai membri del team
• Configurazione SSO

Queste richiedono l'accesso alla dashboard. È intenzionale: sono decisioni che vuoi affidare a una persona.

Approvazione delle azioni sensibili

Per impostazione predefinita, l'MCP richiede un'approvazione umana esplicita (tramite il sistema di permessi del tuo client MCP) per qualsiasi operazione di scrittura:

• Avvio di deployment
• Aggiunta/rimozione di contatti
• Modifica delle configurazioni Finn
• Spesa di denaro

Questo è imposto a livello di protocollo: Claude non può eseguire una scrittura senza la tua conferma nell'interfaccia del client. Le operazioni di lettura non richiedono approvazione.

Puoi disattivarlo per singolo strumento in Impostazioni → Integrazioni → MCP → Elenco di approvazione automatica se vuoi che alcuni strumenti vengano eseguiti senza richieste di conferma. Usa questa opzione con parsimonia: approvare automaticamente "launch_deployment" è un modo concreto per spendere molto denaro in fretta.

Schemi comuni

Standup quotidiano

Configura Claude per recuperare le metriche del giorno prima ogni mattina:

"Ogni giorno feriale alle 9, riassumi i risultati dei deployment di ieri, evidenzia eventuali anomalie e pubblicali sul mio Slack."

(Richiede Claude Code con attività pianificate, oppure un tuo cron con wrapper MCP.)

Rilevamento delle anomalie

"Verifica se nelle ultime 24 ore un deployment ha avuto un tasso di successo inferiore al 50% o un costo superiore al doppio della sua media a 7 giorni. Segnalali con i dettagli."

Audit in blocco

"Elenca tutti i Finn che non hanno campi di analisi post-chiamata definiti. Suggerisci valori predefiniti ragionevoli per ciascuno in base alla descrizione dell'identità del Finn."

Esportazioni rapide

"Estrai tutte le chiamate del deployment X in cui qualified=true, esportale in CSV e inviamele via email."

Risoluzione dei problemi

"Claude non trova gli strumenti Finn"

• Riavvia Claude Desktop dopo aver modificato la configurazione.
• Verifica che il JSON di configurazione sia valido (virgole, virgolette).
• Esegui npx -y @finnai/mcp-server --test nel terminale per verificare che il server si avvii.

"Autenticazione non riuscita"

• Token scaduto o revocato. Generane uno nuovo.
• La variabile d'ambiente del token non viene propagata (errore di battitura nella configurazione).

"Timeout della chiamata allo strumento"

• Le query di grandi dimensioni (ad esempio la ricerca nello storico chiamate) possono richiedere più di 30 secondi.
• Il timeout predefinito nella maggior parte dei client è di 30 s. Aumentalo se necessario.

"Permesso negato per lo strumento X"

• L'ambito del tuo token non include questo strumento.
• Genera un nuovo token con un ambito più ampio, oppure usa la dashboard per quell'operazione.

Novità in arrivo

La roadmap MCP (al momento della stesura):

• Strumenti per i workflow — crea e modifica workflow visuali tramite Claude.
• Strumento Test-on-Call — avvia chiamate di prova da Claude.
• Sottoscrizioni in streaming — flussi di eventi in tempo reale per i deployment live.
• Supporto multi-account — gestisci più account Finn da una sola sessione di Claude.
• Riproduzione delle registrazioni — trasmetti l'audio delle chiamate a Claude per l'ascolto diretto (Enterprise).

Proponi gli strumenti che desideri all'indirizzo [email protected].

Oltre Claude

Sebbene questa pagina si concentri su Claude, il server MCP è indipendente dal provider. Funziona con:

• Continue.dev (estensione AI per VS Code)
• Cursor (IDE AI-first)
• OpenAI ChatGPT Desktop (quando arriverà il supporto MCP)
• Client MCP personalizzati basati sulla specifica aperta

Qualsiasi client che parla MCP può usare Finn tramite lo stesso server.

Avanti

• Integrazioni → API REST — l'API sottostante che l'MCP incapsula.
• Integrazioni → Webhook — notifiche push per flussi di lavoro guidati dagli eventi.
• Capacità e scalabilità → — limiti di frequenza applicati alle chiamate MCP.