# 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](api-access.md), 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 →](api-access.md#generating-your-api-key) > 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 ```bash 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: ```json { "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](https://nodejs.org) 18 o versioni successive: ```json { "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-code), [Claude Desktop](#claude-desktop), [Cursor o un altro client MCP](#cursor--other-mcp-clients), oppure [l'API di Claude](#the-claude-api-build-it-into-your-own-app). ChatGPT può comunque leggere la documentazione di aiuto senza una connessione: vedi [La documentazione di aiuto è integrata](#the-help-docs-are-built-in) 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: ```json { "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](../agency/api-for-agencies.md#where-sub_account_id-is-supported) elenca ciò che è supportato. ::: neutral-mcp Gli strumenti per le agenzie si trovano solo all'indirizzo standard, non brandizzato, `https://mcp.youraiconnector.com/mcp`. Un indirizzo MCP white-label sul tuo dominio (`mcp.youragency.com`) è creato per i tuoi clienti e li esclude, quindi connettiti con l'indirizzo standard, non brandizzato, quando gestisci gli account dei clienti. ::: 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](../chats/playground.md#testing-an-agent-from-the-api-or-an-ai-assistant). ## Client con un limite di strumenti ::: neutral-mcp Alcuni client AI accettano solo un server con un numero limitato di strumenti. Composio, ad esempio, rifiuta un server che elenca più di 500 strumenti e non ne importa nessuno. La connessione completa dell'agenzia ne elenca di più, quindi aggiungi `?tags=` all'indirizzo solo con i gruppi di strumenti di cui hai bisogno. Per un'agenzia che desidera elencare i propri account cliente, leggere i loro contatti, chat e messaggi, e inviare messaggi: ``` https://mcp.youraiconnector.com/mcp?tags=SubAccounts,Contacts,Messages ``` Questo carica circa 80 strumenti. Indica il cliente nella tua richiesta e l'assistente agirà sull'account di quel cliente, come descritto sopra. - Separa i gruppi con virgole; sia le maiuscole che le minuscole funzionano. - Per aggiungere singoli strumenti, elenca i loro nomi esatti con `tools=`, ad esempio `?tags=Contacts&tools=list_or_get_subaccounts`. Otterrai ogni strumento da entrambi gli elenchi. - Gli strumenti della documentazione di aiuto sono sempre inclusi. - La chiave API va comunque nell'intestazione `X-API-Key` (o `Authorization: Bearer YOUR_API_KEY`), mai nell'indirizzo. ::: ## 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](api-access.md#generating-your-api-key) 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](#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). - **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](#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](api-access.md) — genera o ruota la chiave utilizzata da questa connessione. - [Webhook](webhooks.md) — la controparte basata su push di questa connessione MCP basata su pull.