FairValid

Sviluppatori

Connetti un agente IA tramite MCP

Configura ChatGPT, Claude, Hermes, Grok o Codex, verifica la connessione e controlla la spesa per le verifiche.

Gestisci chiavi APIRiferimento API

Scegli il tuo client

Endpoint: https://mcp.fairvalid.com/mcp. Trasporto: Streamable HTTP.

Connettiti con una chiave API o con l’accesso OAuth. Le connessioni idonee di ChatGPT, Claude e Grok possono usare OAuth; verifica qui sotto i requisiti di account e ruolo del tuo client. Codex, Claude Code e Hermes supportano anche connessioni dirette con chiave API.

Per i client con chiave API, crea una chiave di test con un'etichetta in Chiavi API come Owner o Manager dello spazio di lavoro. Salvala nelle credenziali protette del client o nelle impostazioni d'ambiente documentate. Non inserire mai una chiave in un prompt, in un argomento di uno strumento, in un URL o in una configurazione sottoposta a commit.

Il flusso OAuth apre fairvalid.com per l'accesso e il consenso. Scegli una chiave API Live esistente che copra le autorizzazioni richieste e verifica il relativo workspace e il limite di spesa complessivo. L'approvazione concede insieme tutte le autorizzazioni richieste, entro gli ambiti di quella chiave. Non ti viene chiesto di incollare la chiave nel client IA. Revocando la chiave selezionata si chiudono anche le sue connessioni. OAuth usa chiavi live; per la sandbox usa una connessione diretta con una chiave di test.

Istruzioni per i client riviste il 23 ottobre 2026. Il protocollo MCP ospitato ha superato i test di accettazione in produzione con l'SDK ufficiale. Ciò non significa che ogni client citato sia stato testato: completa il controllo della connessione nel tuo client prima di farvi affidamento.

ChatGPT

Usa la configurazione OAuth qui sotto. Le connessioni MCP personalizzate attuali richiedono ChatGPT Business o Enterprise/Edu sul web, con l'autorizzazione a creare plugin con MCP. Business richiede un amministratore o un proprietario; Enterprise/Edu può autorizzare membri selezionati.

  1. Apri Plugin, seleziona il pulsante più, quindi Aggiungi server MCP personalizzato. L'attuale procedura dei Plugin non richiede la Modalità sviluppatore.
  2. Assegna alla connessione il nome FairValid e inserisci https://mcp.fairvalid.com/mcp come endpoint HTTPS pubblico.
  3. Scegli OAuth con registrazione automatica del client. FairValid utilizza la registrazione di client pubblici: non è necessario fornire un client ID né un client secret. Non inserire mai una chiave API in nessuno dei due campi.
  4. Completa l'accesso e il consenso FairValid descritti sopra. Leggi l'avviso di ChatGPT, poi seleziona Create as a plugin ed esamina i sei strumenti rilevati.
  5. Installa il plugin, apri una nuova conversazione, digita @ e seleziona FairValid. Esegui il controllo di connessione in sola lettura qui sotto prima di richiedere una verifica reale.

Documentazione ufficiale: OpenAI: collegare un server MCP personalizzato · OpenAI: autenticazione OAuth

Claude web e Desktop

Usa un connettore personalizzato remoto con OAuth. Si tratta della stessa connessione collegata all'account su Claude web e Desktop e passa attraverso i server di Anthropic. Nei piani Team ed Enterprise, il connettore deve essere aggiunto prima da un Owner dell'organizzazione. Anche i membri Enterprise con un ruolo personalizzato che gestisce le librerie dell'organizzazione possono aggiungerlo.

Some organizations have a Request headers beta. For that alternative, choose No sign-in and add a required Authorization header with the full value Bearer <your FairValid API key>. If Request headers is absent, use OAuth or the Claude Code instructions below. The API key is not an OAuth client secret.

  1. Apri Personalizza → Connettori → Aggiungi connettore personalizzato. Per un'organizzazione gestita, un Proprietario o un ruolo Enterprise idoneo parte da Impostazioni organizzazione → Connettori → Aggiungi → Personalizzato → Web.
  2. Inserisci FairValid e https://mcp.fairvalid.com/mcp.
  3. Scegli Sign in now. Se compare una scelta del client OAuth, seleziona Register automatically. Lascia vuoti i campi client ID e secret per la registrazione manuale.
  4. Accedi su fairvalid.com, controlla la chiave live e le autorizzazioni selezionate e approva la connessione. Attiva FairValid dai controlli dei connettori della conversazione.
  5. Esegui il controllo di connessione in sola lettura qui sotto. Usa il controllo sandbox solo se ti sei connesso con una chiave API di test tramite Request headers.

Documentazione ufficiale: Anthropic: connettori personalizzati e autenticazione · Anthropic: disponibilità dei connettori remoti

Claude Code

Claude Code supporta una connessione diretta tramite chiave API. Imposta FAIRVALID_API_KEY nell'ambiente che avvia Claude Code, usando una chiave Test per la prima verifica. Non inserire il secret effettivo nei file del progetto.

  1. Unisci la configurazione seguente al file .mcp.json del progetto. Mantieni gli eventuali server esistenti. Nel file va inserito il riferimento letterale alla variabile d'ambiente, non il valore della chiave.
  2. Avvia Claude Code con FAIRVALID_API_KEY disponibile. Approva la configurazione MCP del progetto, se richiesto.
  3. Esegui claude mcp list, quindi controlla /mcp nella sessione. Verifica che FairValid si connetta ed esponga sei strumenti, poi esegui il controllo sandbox qui sotto.
{
  "mcpServers": {
    "fairvalid": {
      "type": "http",
      "url": "https://mcp.fairvalid.com/mcp",
      "headers": {
        "Authorization": "Bearer ${FAIRVALID_API_KEY}"
      }
    }
  }
}

Documentazione ufficiale: Anthropic: configurazione MCP di Claude Code

Hermes Agent

Queste istruzioni sono per NousResearch Hermes Agent. Il suo trasporto HTTP remoto supporta header bearer. La CLI salva la chiave nel file .env del profilo attivo come MCP_FAIRVALID_API_KEY e mantiene un riferimento alla variabile d'ambiente in config.yaml.

  1. Esegui il comando di aggiunta qui sotto. Rispondi sì quando ti viene chiesto se è richiesta l'autenticazione, quindi inserisci una chiave API di test nel campo mascherato API key / Bearer token.
  2. Esamina gli strumenti rilevati e abilita gli strumenti FairValid di cui hai bisogno. La configurazione deve connettersi correttamente; salvare una connessione disabilitata dopo un errore non equivale a una configurazione riuscita.
  3. Esegui hermes mcp test fairvalid, quindi avvia una nuova sessione o esegui /reload-mcp. Esegui il controllo sandbox qui sotto. Hermes potrebbe aggiungere il prefisso del nome del server ai nomi degli strumenti.
hermes mcp add fairvalid \
  --url https://mcp.fairvalid.com/mcp \
  --auth header

hermes mcp test fairvalid

Documentazione ufficiale: NousResearch: configurazione MCP · NousResearch: controlli della connessione MCP · NousResearch: implementazione CLI con autenticazione tramite header

Grok Bot e Grok

Grok Bot e Grok.com si configurano in punti diversi. In un Grok Bot personale, chiedi al Bot di aggiungere FairValid usando la richiesta qui sotto. Questo metodo funziona anche quando il pannello informazioni mostra solo Dettagli, Libreria e Computer, senza una sezione Configurazione.

I Team Bot mostrano inoltre al proprietario o ai manager del Bot il percorso riquadro informazioni → Setup → Plugins. Questa sezione di configurazione richiede l’accesso Team Bot nell’app desktop. Quando si usa OAuth, ogni membro del team accede con il proprio account.

Grok.com usa grok.com/connectors → New Connector → Custom. Inserisci https://mcp.fairvalid.com/mcp e completa l'autenticazione. Per i team Business ed Enterprise potrebbe essere necessario che un amministratore configuri prima il connettore. Si tratta di una connessione distinta da un plugin di Grok Bot.

Anche un bot creato con l'API di xAI è un caso a parte: il suo sviluppatore configura le intestazioni MCP remote nel codice del server. Queste istruzioni non affermano che Grok Bot offra un campo generico per l'intestazione Authorization.

  1. Chiedi al tuo Bot di aggiungere la connessione MCP HTTPS remota personalizzata usando la richiesta qui sotto. Per un Team Bot, anche il suo owner o manager può usare Setup → Plugins.
  2. When the Bot shows the FairValid authorization card, select Authorize to open OAuth sign-in. Keep API keys out of the request and any server command.
  3. Completa il consenso FairValid su fairvalid.com. Ogni membro del team collega il proprio account, ove richiesto.
  4. Chiedi al Bot di elencare gli strumenti di FairValid e di eseguire il controllo di connessione in sola lettura qui sotto. La sola individuazione degli strumenti non dimostra che una verifica sia stata completata.
Add FairValid as a custom Remote HTTPS MCP server at
https://mcp.fairvalid.com/mcp using OAuth.
Show me the sign-in flow, then list its tools.
Do not submit any email verification yet.

Documentazione ufficiale: xAI: plugin di Grok Bot e HTTPS remoto · xAI: connettori personalizzati di Grok.com · xAI: MCP remoto per sviluppatori API

Codex

Usa una connessione diretta tramite chiave API da Codex. Imposta FAIRVALID_API_KEY nell'ambiente disponibile al processo Codex, usando una chiave Test per la prima verifica. Un'app desktop avviata separatamente potrebbe non ereditare l'ambiente del tuo terminale.

  1. Esegui il comando qui sotto per registrare il server remoto Streamable HTTP. Il comando memorizza il nome della variabile d'ambiente, non la chiave API.
  2. Esegui codex mcp list e avvia una nuova sessione Codex affinché carichi la connessione. Verifica che FairValid compaia tra gli strumenti MCP della sessione.
  3. Se usi l'app Codex, rendi la variabile disponibile al suo host di esecuzione e, se necessario, riavvia l'app o apri una nuova sessione. Non dare per scontato che una configurazione riuscita della CLI abbia modificato l'ambiente di un'app già in esecuzione.
  4. Conferma i sei strumenti rilevati ed esegui il controllo sandbox qui sotto.
codex mcp add fairvalid \
  --url https://mcp.fairvalid.com/mcp \
  --bearer-token-env-var FAIRVALID_API_KEY

codex mcp list

Documentazione ufficiale: OpenAI: configurazione MCP di Codex

Controlla la connessione prima di inviare lavoro

Conferma il rilevamento di tutti i sei strumenti elencati di seguito. Un client può aggiungere un proprio prefisso ai nomi degli strumenti. Il rilevamento conferma una connessione, non una verifica riuscita.

Con OAuth o una chiave API Live, concedi l'autorizzazione al saldo e chiedi prima all'agente di chiamare fairvalid_get_balance senza argomenti. La lettura del saldo non utilizza crediti di verifica. Non inviare gli esempi sandbox tramite una connessione live.

Con una chiave API Test, segui invece la verifica sandbox riportata di seguito. La verifica live può prenotare e spendere crediti; scegli un indirizzo che sei autorizzato a verificare e richiedi l'invio in modo esplicito.

Se una connessione non riesce, controlla le autorizzazioni del connettore dell'account, l'endpoint, eventuali variabili d'ambiente mancanti e la revoca della chiave o dell'autorizzazione. In caso di errori relativi alle autorizzazioni o al limite di spesa, verifica gli ambiti concessi o il limite prima di riprovare: una nuova chiave di idempotenza non risolve la causa.

Inizia con una verifica gratuita in sandbox

Usa una chiave fv_test_ e chiama fairvalid_verify_email con l'esempio qui sotto. La verifica di un singolo indirizzo con chiave di test restituisce direttamente un risultato simulato. Non effettua chiamate al provider, non crea verifiche live e non utilizza crediti.

Gli altri esempi riservati sono undeliverable@example.com, risky@example.com, unknown@example.com, pending@example.com ed error@example.com. Pending ed error sono simulazioni intenzionali, non verifiche reali di caselle di posta. L'esempio pending per singolo indirizzo non ha un'attività da interrogare.

{
  "email": "deliverable@example.com",
  "idempotency_key": "agent-demo-2026-10-23"
}

Strumenti e autorizzazioni

fairvalid_verify_email accetta email e idempotency_key. fairvalid_submit_job accetta emails, idempotency_key e un name facoltativo, per un numero di indirizzi compreso tra 1 e 5.000. Gli invii in modalità live richiedono lo scope submit.

fairvalid_get_job accetta job_id per leggerne lo stato. fairvalid_get_results accetta job_id e, facoltativamente, cursor, filter e search per leggere fino a 50 risultati alla volta. Le letture in modalità live richiedono lo scope read.

fairvalid_cancel_job accetta job_id e richiede l’annullamento; le verifiche già in corso potrebbero essere completate. L’annullamento in modalità live richiede lo scope submit. fairvalid_get_balance non accetta argomenti e richiede una chiave live con scope balance. Le chiavi di test non possono leggere un saldo crediti live.

Le chiavi determinano il workspace. Gli strumenti non accettano argomenti per chiave API o workspace. Le verifiche sugli ambiti, la revoca, i limiti di spesa e le regole sui crediti del workspace si applicano a MCP esattamente come all'API per i clienti.

Segui un'attività in tempo reale fino ai risultati

Con OAuth o una chiave fv_live_, sia la verifica singola sia quella in blocco inviano job asincroni. Una risposta di accettazione e un job_id indicano che il lavoro è stato ammesso, non che la verifica della casella di posta sia terminata. I tempi di elaborazione dipendono dalla coda e dal provider di verifica.

Per provare il flusso di un'attività in sandbox, chiama fairvalid_submit_job con indirizzi di esempio riservati. Le attività in sandbox supportano stato, risultati, annullamento e ripetizione senza chiamate ai provider né consumo di crediti.

  1. Invia una sola volta con un idempotency_key stabile e conserva il job_id restituito.
  2. Chiama fairvalid_get_job con quel job_id. Distanzia le richieste di polling e rallentale in caso di errori temporanei.
  3. Chiama fairvalid_get_results con lo stesso job_id. Passa ogni next_cursor come cursor finché next_cursor non è null. Un cursor mantiene il filtro e la ricerca originali.
  4. Controlla sia lo stato del job sia ogni singolo risultato. Gli esiti sconosciuti, catch-all e ancora in verifica non dimostrano che una casella di posta sia valida.

Riprova senza creare attività duplicate

Entrambi gli strumenti di invio richiedono un idempotency_key composto da 8 a 128 lettere, cifre, punti, due punti, trattini bassi o trattini. Ripeti una risposta incerta con la stessa chiave API o connessione OAuth, lo stesso idempotency_key e lo stesso input invariato. La ripetizione è legata alla chiave API sottostante: il rinnovo di un token di accesso OAuth mantiene la stessa identità, ma selezionare una chiave API diversa e reinviare può creare un’altra esecuzione. Un payload del job modificato con una chiave di idempotenza esistente viene rifiutato. Usa una nuova chiave di idempotenza solo per un’esecuzione nuova e intenzionale.

Controlla isError prima di leggere il risultato. Le chiamate che raggiungono l'API clienti includono la sua risposta e lo stato HTTP in structuredContent; gli errori di convalida degli argomenti possono restituire solo contenuto testuale. Esamina il codice di un errore API e rispetta eventuali indicazioni sui nuovi tentativi. Un timeout o un errore temporaneo non dimostra che l'invio originale non sia avvenuto.

Le chiavi live possono spendere i crediti del workspace. Imposta un limite complessivo prima di collegare un agente autonomo: vengono conteggiati sia i crediti scalati sia quelli riservati. Le verifiche completate con esito valido o non valido utilizzano un credito; i risultati sconosciuti, i catch-all non risolti e gli errori tecnici alla fine non consumano crediti.

Hai ancora bisogno di aiuto?

Accedi per aprire un ticket di assistenza privato.

Contatta l’assistenza