# Connetti assistenti IA (MCP)

<span data-t="appName">DM Champ</span> fornisce un **server MCP** ufficiale — un endpoint del Model Context Protocol
che consente ad assistenti IA come **Claude Code**, **Claude Desktop**, **ChatGPT**,
**Cursor** e alle tue app di gestire direttamente il tuo account <span data-t="appName">DM Champ</span>. Chiedi in linguaggio naturale
("elenca le mie campagne attive", "aggiungi questo lead", "quanto ho speso in IA questa settimana?")
e l'assistente chiamerà l'API <span data-t="appName">DM Champ</span> per te.

Si tratta della stessa API v1 documentata nella [sezione API](../api/getting-started.md), autenticata
con la propria chiave API. 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, knowledge base, appuntamenti, analisi, tag, liste e sub-account. Broadcast, automazioni e trattative non sono ancora disponibili come strumenti MCP: per questi, utilizza direttamente l'API REST.
All'interno di ciò che espone non ci sono autorizzazioni per singolo strumento né impostazioni predefinite di sola lettura, quindi la chiave API rappresenta l'intero controllo di accesso.

- **Endpoint:** `https://mcp.youraiconnector.com/mcp`
- **Autenticazione:** la tua chiave API <span data-t="appName">DM Champ</span> (inviata come header `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 dm-champ https://mcp.youraiconnector.com/mcp \
  --header "X-API-Key: YOUR_API_KEY"
```

Quindi esegui `/mcp` all'interno di Claude Code per confermare che venga visualizzato **dm-champ ✓ connesso**.

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": {
    "dm-champ": {
      "type": "http",
      "url": "https://mcp.youraiconnector.com/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}
```

## Claude Desktop

Modifica il tuo `claude_desktop_config.json` (Impostazioni → Sviluppatore → Modifica configurazione) e
aggiungi:

```json
{
  "mcpServers": {
    "dm-champ": {
      "type": "http",
      "url": "https://mcp.youraiconnector.com/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}
```

Riavvia Claude Desktop. Gli strumenti <span data-t="appName">DM Champ</span> appariranno nel menu degli strumenti.

## ChatGPT

I connettori MCP personalizzati sono disponibili su ChatGPT Business, Enterprise e Pro. Un
proprietario o un amministratore dell'area di lavoro deve prima attivare la **modalità sviluppatore / connettori personalizzati**
nelle impostazioni dell'area di lavoro; senza questa operazione, l'opzione per creare un connettore
non apparirà mai.

Quindi crea il connettore con:

- **URL:** `https://mcp.youraiconnector.com/mcp`
- **Autenticazione:** Header personalizzati
- **Nome header:** `X-API-Key`
- **Valore header:** la tua chiave API <span data-t="appName">DM Champ</span>

L'URL deve terminare con `/mcp`. Incollare solo `https://mcp.youraiconnector.com` è l'errore più
comune: ChatGPT controlla quell'indirizzo esatto, non trova nulla e
mostra **"Impossibile aggiungere l'URL del connettore"**.

## Cursor e altri client MCP

La maggior parte degli editor compatibili con MCP utilizza la stessa struttura `.mcp.json` mostrata sopra (un server HTTP
con un `url` e un header `X-API-Key`). Aggiungi un server `dm-champ` puntando
a `https://mcp.youraiconnector.com/mcp` e incolla la tua chiave API nell'header.

## 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 <span data-t="appName">DM Champ</span> senza un client separato:

```json
{
  "model": "claude-opus-4-8",
  "messages": [{ "role": "user", "content": "List my live campaigns" }],
  "mcp_servers": [
    {
      "type": "url",
      "name": "dm-champ",
      "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:

- **Campagne:** elenca, crea, aggiorna, metti in pausa/riprendi, ispeziona la configurazione del bot.
- **Contatti:** cerca, crea, aggiungi tag, 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 a ciascuno dei miei clienti questa settimana?"
- "Quali campagne sono attive per Northside Dental e qual è lo stato dei loro canali?"

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.

**La modifica dell'account di un cliente** è più limitata. La configurazione di agenti IA, funzioni personalizzate, modelli WhatsApp, punti di ingresso, connessioni ai canali, stato della campagna e l'acquisto di un numero funzionano tutti per un cliente specifico; la maggior parte delle altre operazioni di scrittura viene comunque eseguita sul proprio account, quindi è preferibile effettuarle utilizzando la chiave del cliente stesso o tramite la [REST API](../agency/api-for-agencies.md), che offre una copertura maggiore.

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.

## Fornire all'assistente la documentazione di supporto

Il server MCP fornisce all'assistente il tuo **account**; non gli fornisce questa documentazione. Se vuoi che risponda correttamente anche a domande del tipo "come faccio a...", puntalo a `https://docs.dmchamp.com/llms.txt` (un indice di ogni pagina di aiuto con un link alla versione Markdown di ciascuna pagina) o a `https://docs.dmchamp.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. Vedi [Leggere questa documentazione in formato Markdown](../api/getting-started.md#reading-these-docs-as-markdown).

## 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

- **"Unable to add connector URL" (ChatGPT) / "connection refused"** — 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.
- **Uno strumento restituisce `403`** — il tuo piano o il tuo ruolo nel team non consentono tale azione; il server MCP non impone nulla di aggiuntivo, si tratta dello 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 offrire 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**, seguendo la stessa procedura degli altri tuoi sottodomini brandizzati. Fino alla verifica, utilizza l'indirizzo standard indicato sopra: non è brandizzato, quindi è sicuro da condividere 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.