Connetti assistenti IA (MCP) #

Your AI Connector fornisce un server MCP ufficiale — un endpoint del Model Context Protocol che consente ad assistenti IA come Claude Code, Claude Desktop, Cursor e le tue app di gestire direttamente il tuo account Your AI Connector. Chiedi in linguaggio naturale (“elenca i miei agenti IA”, “aggiungi questo lead”, “quanto ho speso per l’IA questa settimana?”) e l’assistente chiamerà l’API Your AI Connector per te.

È la stessa API v1 a cui accedi con una API key, autenticata con la tua API key. Il server MCP crea uno strumento per ogni operazione nella nostra specifica API pubblicata, quindi copre la maggior parte, ma non tutta, l’API v1: contatti, messaggi, campagne, agenti IA, funzioni personalizzate, knowledge base, appuntamenti, analisi, tag, liste, broadcast, trattative, connessioni ai canali e sub-account. Le automazioni possono essere elencate e lette, ma non ancora create o modificate tramite MCP; creale nell’app. All’interno di ciò che espone non ci sono autorizzazioni per singolo strumento e nessuna impostazione predefinita di sola lettura, quindi l’API key rappresenta l’intero controllo di accesso.

• Endpoint: https://mcp.youraiconnector.com/mcp
• Autenticazione: la tua chiave API Your AI Connector (inviata come intestazione X-API-Key)
• Requisiti: un piano con accesso API. Crea una chiave API →

La tua chiave API agisce sul tuo account, con le stesse autorizzazioni del resto dell’API, e può leggere gli account cliente che gestisci, se hai un piano agenzia (vedi sotto). Trattala come una password. Puoi revocarla in qualsiasi momento da Impostazioni → Integrazioni → Chiave API, il che interrompe immediatamente l’accesso dell’assistente.

Claude Code #

claude mcp add --transport http ai-connector https://mcp.youraiconnector.com/mcp \
  --header "X-API-Key: YOUR_API_KEY"

Quindi esegui /mcp all’interno di Claude Code per confermare che mostri ai-connector ✓ connected.

Per impostazione predefinita, il server viene aggiunto all’ambito locale (solo tu, questo progetto). Usa --scope user per renderlo disponibile in tutti i tuoi progetti, oppure --scope project to commit it to a repo’s .mcp.json per il tuo team:

{
  "mcpServers": {
    "ai-connector": {
      "type": "http",
      "url": "https://mcp.youraiconnector.com/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}

Claude Desktop #

Aggiungi il server come connettore personalizzato. È configurato nel tuo account Claude, quindi funziona sia in Claude Desktop che su claude.ai (gli account Claude gratuiti possono aggiungere un connettore personalizzato).

1. Apri Personalizza → Connettori, fai clic su + Aggiungi, quindi su Aggiungi connettore personalizzato.
2. Assegna un nome e inserisci https://mcp.youraiconnector.com/mcp come URL.
3. In Autenticazione, scegli Nessun accesso. Il server MCP non ha una pagina di accesso: la selezione di un’opzione di accesso termina con “Impossibile registrarsi con… servizio di accesso”.
4. In Intestazioni di richiesta, aggiungi un’intestazione denominata X-API-Key con la tua chiave API come valore.
5. Fai clic su Aggiungi. Gli strumenti Your AI Connector appariranno nel menu degli strumenti di una nuova chat.

Campo Intestazioni di richiesta mancante? La tua versione di Claude Desktop è obsoleta: aggiornala o usa invece il file di configurazione. Il file di configurazione (claude_desktop_config.json, Impostazioni → Sviluppatore → Modifica configurazione) esegue solo programmi sul tuo computer e ignora una voce url, quindi necessita del piccolo bridge mcp-remote, che richiede Node.js 18 o versioni successive:

{
  "mcpServers": {
    "ai-connector": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.youraiconnector.com/mcp",
        "--header",
        "X-API-Key:${AI_CONNECTOR_KEY}"
      ],
      "env": { "AI_CONNECTOR_KEY": "YOUR_API_KEY" }
    }
  }
}

Mantieni X-API-Key:${AI_CONNECTOR_KEY} esattamente come scritto, senza spazi dopo i due punti (su Windows uno spazio divide l’intestazione), e inserisci la tua chiave solo in env. Quindi chiudi completamente Claude Desktop (su Windows, fai clic con il tasto destro sull’icona nella barra delle applicazioni → Esci) e riaprilo.

ChatGPT #

ChatGPT non può connettersi al server MCP al momento. Il suo modulo per connettori personalizzati offre solo OAuth o Nessuna autenticazione, e il server MCP Your AI Connector effettua l’accesso con la tua chiave API, inviata come intestazione di richiesta. Scegliendo OAuth fallisce con “could not discover OAuth settings”, e Nessuna autenticazione viene respinta perché ogni richiesta necessita della chiave.

Utilizza un assistente che ti permetta di impostare un’intestazione di richiesta: Claude Code, Claude Desktop, Cursor o un altro client MCP, oppure l’API di Claude.

ChatGPT può comunque leggere la documentazione di aiuto senza una connessione: vedi La documentazione di aiuto è integrata per i file pubblici llms.txt.

Cursor e altri client MCP #

La maggior parte degli editor compatibili con MCP utilizza la stessa forma .mcp.json mostrata sopra (un server HTTP con un url e un’intestazione X-API-Key). Aggiungi un server ai-connector che punta a https://mcp.youraiconnector.com/mcp e incolla la tua chiave API nell’intestazione.

L’API di Claude (integrala nella tua app) #

Puoi connettere il server MCP a livello programmatico con il connettore MCP dell’API di Claude, in modo che un agente creato da te possa utilizzare gli strumenti Your AI Connector senza un client separato:

{
  "model": "claude-opus-4-8",
  "messages": [{ "role": "user", "content": "List my AI agents" }],
  "mcp_servers": [
    {
      "type": "url",
      "name": "ai-connector",
      "url": "https://mcp.youraiconnector.com/mcp",
      "authorization_token": "YOUR_API_KEY"
    }
  ]
}

Cosa puoi fare #

All’interno della parte dell’API v1 esposta dal server MCP, l’assistente seleziona automaticamente lo strumento corretto:

• Agenti IA: elenca, crea, aggiorna, metti in pausa/riprendi, ispeziona la configurazione.
• Contatti: cerca, crea, etichetta, aggiungi a liste, importa.
• Knowledge base / FAQ: aggiungi, modifica, importa in blocco, approva i suggerimenti dell’IA.
• Messaggi: leggi le conversazioni, invia un messaggio a un contatto.
• Appuntamenti: elenca, prenota, annulla.
• Attività: crea, completa, elenca.
• Analisi: statistiche dei messaggi, utilizzo dei crediti, costo dell’IA.
• Canali: controlla lo stato della connessione, avvia un flusso di connessione.

Chiedere informazioni sugli account dei propri clienti (agenzie) #

Una singola connessione copre ogni account che gestisci. Non è necessario aggiungere una seconda connessione per cliente: con un piano agenzia, l’assistente può leggere qualsiasi account cliente sotto di te, così puoi chiedere informazioni su tutti loro in un’unica conversazione.

Basta nominare il cliente:

• “Quanti contatti ha Bella’s Bistro?”
• “Quanto è costata l’IA per ciascuno dei miei clienti questa settimana?”
• “Qual è lo stato dei canali di Northside Dental e quante chat sono arrivate questa settimana?”

Questo copre la lettura di contatti, messaggi, chat, campagne, appuntamenti, attività, tag, eventi, FAQ, fonti della knowledge base, numeri di telefono, canali, webhook e analisi. Verifichiamo che l’account sia effettivamente tuo prima di eseguire qualsiasi operazione: se ne richiedi uno che non lo è, riceverai un errore di “non trovato”. Se non specifichi il cliente, l’assistente leggerà il tuo account, esattamente come prima.

Modificare l’account di un cliente funziona allo stesso modo. Ogni azione che accetta un account cliente nell’API è disponibile per un cliente designato: configurazione di agenti IA, knowledge base, funzioni personalizzate, modelli WhatsApp, punti di ingresso, connessioni ai canali, contatti, tag, trasmissioni, appuntamenti, trattative e attività, e invio di messaggi. Le eccezioni sono le azioni a livello di agenzia, che vengono eseguite sempre sul proprio account agenzia: gestione degli account cliente stessi (limiti, funzionalità, prezzi, sospensione), snapshot, il proprio team e chiavi API. L’aggiunta o la rimozione di contatti dall’elenco di un cliente non è ancora disponibile per un cliente designato; è necessario farlo dalla chiave specifica di quel cliente o nel suo account. La guida all’API per agenzie elenca ciò che è supportato.

Questa è anche la risposta per un cliente che gestisce diverse attività con un unico accesso. Assegna a ogni attività il proprio account, quindi invita l’email del cliente come membro del team su tutti loro: accederanno una volta e passeranno da un brand all’altro con il selettore di account nella barra laterale.

Testare l’agente di un cliente #

Chiedi all’assistente di provare l’agente di un cliente (“invia ‘consegnate la domenica?’ all’agente Bakery del cliente X e mostrami cosa ha fatto”). Invia un messaggio di prova (Try Out) con la tua chiave di agenzia e l’sub_account_id del cliente, attende e legge la risposta insieme a qualsiasi azione intrapresa dall’agente. Non è necessaria alcuna copia dell’agente. Se l’assistente dice che non sei un account di agenzia, significa che è collegato con la chiave di un cliente: ricollegalo con la chiave del tuo account di agenzia. Vedi Try Out.

Client con un limite di strumenti #

https://mcp.youraiconnector.com/mcp?tags=SubAccounts,Contacts,Messages

I documenti di aiuto sono integrati #

Il server MCP fornisce all’assistente il tuo account e questa documentazione. Tre strumenti leggono i documenti di aiuto in tempo reale, così l’assistente può cercare come funziona una funzionalità o cosa è cambiato di recente, invece di tirare a indovinare:

• docs_search: trova le sezioni che rispondono a una domanda e le restituisce con il link alla pagina.
• docs_read: legge una pagina per intero o una sua sezione.
• docs_list: elenca ogni pagina per area.

Non c’è nulla da configurare e gli strumenti per i documenti non toccano mai i dati del tuo account. Chiedi “come funzionano i punti di ingresso?” o “cosa c’è di nuovo nelle automazioni?” e l’assistente cercherà prima nei documenti. Poiché gli strumenti leggono il sito di aiuto stesso, una funzionalità è nota al tuo assistente non appena la sua guida viene pubblicata.

Un assistente non connesso tramite MCP può comunque leggere i documenti: puntalo su https://docs.youraiconnector.com/llms.txt (un indice di ogni pagina di aiuto con un link alla versione Markdown di ciascuna pagina) o https://docs.youraiconnector.com/llms-full.txt (l’intera documentazione in un unico file Markdown). Entrambi sono pubblici, non richiedono chiavi e vengono ricostruiti a ogni modifica della documentazione.

Trovare o generare la tua chiave API #

La chiave API utilizzata da questa connessione si trova in Impostazioni → Integrazioni → Chiave API — una sezione dedicata, separata dai Webhook. Consulta Accesso API per i passaggi esatti.

Risoluzione dei problemi #

• “Connessione rifiutata” o “non trovato” — all’indirizzo manca /mcp alla fine. Usa https://mcp.youraiconnector.com/mcp, non https://mcp.youraiconnector.com.
• Needs authentication / 401 — la tua chiave API è mancante o errata. Aggiungi nuovamente il server con una X-API-Key valida.
• “Impossibile rilevare le impostazioni OAuth” (ChatGPT) — ChatGPT supporta solo OAuth o nessuna autenticazione per i connettori personalizzati, e il server MCP utilizza una chiave API, quindi ChatGPT non può connettersi per il momento. Vedi ChatGPT.
• “Impossibile registrarsi con… servizio di accesso” o “aggiungi un ID client OAuth” (Claude Desktop) — il connettore personalizzato è stato aggiunto con un’opzione di accesso. Non c’è alcun ID client OAuth da inserire: rimuovi il connettore e aggiungilo di nuovo con Autenticazione → Nessun accesso e la tua chiave API come intestazione di richiesta X-API-Key, come in Claude Desktop.
• Claude Desktop non mostra strumenti dopo la modifica del file di configurazione — il file di configurazione ignora una voce "url"; usa il connettore personalizzato o il modulo mcp-remote in Claude Desktop, quindi chiudi completamente e riapri l’app.
• Uno strumento restituisce 403 — il tuo piano o ruolo nel team non consente tale azione; il server MCP non impone nulla di aggiuntivo, è lo stesso controllo dei permessi dell’API.
• Strumento non trovato — l’elenco degli strumenti viene generato in tempo reale dall’API, quindi corrisponde sempre alla versione corrente; riconnettiti per aggiornare.
• Un avviso di sicurezza o di certificato sul tuo dominio — puntare un record DNS verso di noi non è sufficiente di per sé: il sottodominio deve anche essere verificato nella dashboard prima di poter servire una connessione sicura. Le agenzie white-label possono inserire l’indirizzo MCP sul proprio dominio (ad es. mcp.youragency.com) dalla scheda Dominio personalizzato in Impostazioni → White Labeling — aggiungi prima il CNAME presso il tuo registrar, quindi inserisci il nome host nel blocco Dominio MCP (assistenti AI) e fai clic su Verifica, lo stesso flusso degli altri tuoi sottodomini brandizzati. L’indirizzo brandizzato esclude gli strumenti dell’agenzia; continua a utilizzare l’indirizzo standard non brandizzato per quelli. Finché il tuo indirizzo brandizzato non sarà verificato, utilizza l’indirizzo standard non brandizzato: è sicuro condividerlo con i clienti.

Prossimi passi #

• Accesso API — genera o ruota la chiave utilizzata da questa connessione.
• Webhook — la controparte basata su push di questa connessione MCP basata su pull.