# Server MCP

> Collega Claude Code, Cursor e altri strumenti di IA al tuo account intoCHAT tramite il suo server MCP remoto: l'endpoint, chiavi API e scope, la configurazione per ogni client, gli strumenti e i limiti.

intoCHAT ha un server MCP remoto. MCP (Model Context Protocol) è il modo standard con cui strumenti di IA come Claude Code e Cursor si collegano ad altri servizi. Una volta collegato il tuo, puoi chiedergli a parole di elencare i tuoi agenti, leggere le loro conversazioni e i loro lead, aggiungere testi e coppie di Q&A, eliminare fonti o inviare a un agente un messaggio di prova, e lui chiama intoCHAT al posto tuo.

Il server MCP usa le stesse chiavi API, gli stessi scope, lo stesso piano e lo stesso limite di frequenza della [REST API](/it/docs/rest-api), e i suoi strumenti fanno esattamente ciò che fanno gli endpoint REST corrispondenti.

## Endpoint

```text
https://www.intochat.ai/api/mcp
```

Il server usa il trasporto Streamable HTTP. Ogni richiesta ha bisogno della tua chiave API nell'intestazione `Authorization`:

```text
Authorization: Bearer ic_live_YOUR_KEY
```

Usa l'indirizzo con `www`, come sopra.

> L'accesso con OAuth non è ancora supportato. I client che possono collegarsi solo tramite OAuth, come i connettori personalizzati di Claude.ai e dell'app desktop di Claude, o i connettori di ChatGPT, per ora non possono usare il server. Funzionano i client che permettono di impostare un'intestazione: Claude Code, Cursor, l'MCP Inspector e l'app desktop di Claude tramite un bridge locale (vedi [Altri client](#altri-client)).

## Prima di iniziare

Il server MCP è incluso nei piani **Starter**, **Pro** ed **Enterprise**, come la REST API. Con **Free** non puoi creare chiavi API, e un account che torna al piano Free riceve un errore a ogni richiesta finché non passa di nuovo a Starter o a un piano superiore.

Ti serve una chiave API. Solo il proprietario dell'account e gli admin possono crearne una.

## Creare una chiave API

1. Nella barra laterale, sotto **Settings**, clicca su **API keys**.
2. In **Create a key**, dai alla chiave un **Name**, per esempio `Claude Code`.
3. In **Access**, scegli che cosa può fare lo strumento di IA. **Every scope, including ones added later** consente tutti gli strumenti. Per limitarlo alla sola lettura, scegli **Only the scopes I choose** e seleziona solo gli scope `:read`. Vedi [Strumenti](#strumenti) per lo scope richiesto da ogni strumento.
4. Clicca su **Create key**, poi su **Copy**, e clicca su **I've saved it**. La chiave viene mostrata una sola volta.

Una chiave funziona per tutti gli agenti dell'account. Trattala come una password: tienila fuori dai file che committi o condividi, e revocala nella pagina **API keys** se qualcun altro potrebbe averla. Per saperne di più vedi [Creare una chiave API](/it/docs/rest-api#creare-una-chiave-api) nella documentazione della REST API.

## Collegare Claude Code

Esegui questo comando in un terminale, con la tua chiave al posto di `ic_live_YOUR_KEY`:

```bash
claude mcp add --transport http intochat https://www.intochat.ai/api/mcp \
  --header "Authorization: Bearer ic_live_YOUR_KEY"
```

Così il server viene aggiunto per il progetto corrente, solo sul tuo computer. Per usarlo in tutti i progetti, aggiungi `--scope user` prima di `--transport`.

Per condividere la configurazione con il tuo team nel file `.mcp.json` del progetto senza la chiave stessa, leggi la chiave da una variabile d'ambiente:

```json
{
  "mcpServers": {
    "intochat": {
      "type": "http",
      "url": "https://www.intochat.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${INTOCHAT_API_KEY}"
      }
    }
  }
}
```

Poi digita `/mcp` in Claude Code per controllare che **intochat** sia collegato, e chiedi per esempio: "List my intoCHAT agents."

## Collegare Cursor

Nelle impostazioni di Cursor, apri la sezione MCP e aggiungi un server, oppure modifica `~/.cursor/mcp.json` (tutti i progetti) o `.cursor/mcp.json` in un progetto:

```json
{
  "mcpServers": {
    "intochat": {
      "url": "https://www.intochat.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ic_live_YOUR_KEY"
      }
    }
  }
}
```

Gli strumenti di intoCHAT compaiono quindi nell'elenco degli strumenti MCP, e l'agente di Cursor può usarli.

## Altri client

Può collegarsi qualsiasi client MCP che supporti il trasporto Streamable HTTP e permetta di aggiungere un'intestazione. Indicagli l'[endpoint](#endpoint) e l'intestazione `Authorization`.

**App desktop di Claude.** Le sue impostazioni **Connectors** richiedono OAuth, che non è ancora supportato. Aggiungi invece il server a `claude_desktop_config.json` tramite il bridge open source `mcp-remote`, che richiede Node.js sul tuo computer:

```json
{
  "mcpServers": {
    "intochat": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.intochat.ai/api/mcp", "--header", "Authorization:${INTOCHAT_AUTH}"],
      "env": {
        "INTOCHAT_AUTH": "Bearer ic_live_YOUR_KEY"
      }
    }
  }
}
```

**MCP Inspector.** Esegui `npx @modelcontextprotocol/inspector`, scegli **Streamable HTTP**, inserisci l'endpoint e aggiungi l'intestazione `Authorization`. Collegati tramite il proxy dell'Inspector: il server rifiuta le richieste fatte direttamente da una pagina web di un altro sito.

**Provare con curl.** Ogni richiesta è un messaggio JSON-RPC in una POST:

```bash
curl https://www.intochat.ai/api/mcp \
  -H "Authorization: Bearer ic_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
```

Il server parla le versioni MCP `2026-07-28` e da `2025-03-26` a `2025-11-25`, risponde a ogni richiesta in JSON e non mantiene una sessione tra una richiesta e l'altra.

## Strumenti

| Strumento | Scope | Che cosa fa |
| --- | --- | --- |
| `list_agents` | `agents:read` | Elenca gli agenti dell'account con i loro ID, lo stato dell'addestramento e i conteggi. |
| `get_agent` | `agents:read` | Legge un agente. |
| `chat_with_agent` | `chat` | Invia un messaggio a un agente e restituisce la sua risposta. Ogni risposta conta come un messaggio del tuo piano. |
| `list_conversations` | `conversations:read` | Elenca le conversazioni di un agente, dalla più recente, senza trascrizioni. |
| `get_conversation` | `conversations:read` | Legge una conversazione con la sua trascrizione. |
| `list_leads` | `leads:read` | Elenca i lead raccolti da un agente, dal più recente. |
| `list_contacts` | `leads:read` | Elenca i [contatti](/it/docs/contacts) di un agente, dal più recente, oppure ne cerca uno tramite `email` o `external_id`. |
| `upsert_contact` | `contacts:write` | Crea o aggiorna un contatto tramite `external_id`, altrimenti `email`, con `phone`, `name` e `attributes` (un oggetto; `null` rimuove un attributo). |
| `list_sources` | `sources:read` | Elenca le fonti di conoscenza di un agente, l'avanzamento dell'addestramento e i caratteri che usa. |
| `add_text_source` | `sources:write` | Aggiunge un testo con un titolo e avvia l'addestramento. |
| `add_qa_pair` | `sources:write` | Aggiunge una domanda e una risposta e avvia l'addestramento. Se l'agente ha già la stessa domanda, la sua risposta viene sostituita. |
| `delete_source` | `sources:write` | Elimina una fonte e ciò che l'agente ha imparato da essa. L'operazione non si può annullare. |

Ogni strumento restituisce gli stessi dati del suo endpoint REST, in JSON. `list_conversations`, `list_leads` e `list_contacts` accettano `limit` (da 1 a 100), `cursor` e `since`, tutti facoltativi, come descritto in [Paginazione](/it/docs/rest-api#paginazione).

Gli strumenti sono indicati come di sola lettura o no, e `delete_source`, `add_qa_pair` e `upsert_contact` come capaci di modificare ciò che esiste già, così il tuo strumento di IA può chiederti conferma prima di usarli. Molti strumenti di IA chiedono la tua conferma prima di eseguire qualsiasi strumento.

Se la chiave non ha lo scope richiesto da uno strumento, lo strumento risponde con un errore che indica lo scope, e non succede nulla. Un agente, una conversazione o una fonte di un altro account risulta "non trovato", come uno che non esiste.

Non ci sono strumenti per creare agenti o modificarne le impostazioni o le istruzioni. Fallo nella dashboard.

## Chattare con un agente

`chat_with_agent` invia un messaggio reale, a cui risponde lo stesso codice del widget di chat, in base alla conoscenza, alle istruzioni e alle azioni dell'agente. Usalo per provare come risponde un agente.

- Ogni risposta conta come un messaggio del tuo piano e per il [tetto mensile di messaggi](/it/docs/limits-and-access#tetto-mensile-di-messaggi) dell'agente, se ne hai impostato uno. Vedi [Che cosa conta come messaggio](/it/docs/plans-and-limits#che-cosa-conta-come-messaggio).
- Ometti `conversationId` per avviare una nuova conversazione. Per continuarne una, passa il `conversationId` della risposta precedente.
- Le conversazioni compaiono nella scheda **Conversations** dell'agente come tutte le altre.
- Un agente privato non si può raggiungere in questo modo. Vedi [Agenti privati](/it/docs/allowed-domains#agenti-privati).

Chiedi al tuo strumento di IA di non inviare molti messaggi di fila a meno che tu non lo voglia: ognuno consuma i messaggi del tuo piano.

## Limiti

- **Piano:** Starter, Pro o Enterprise. Con Free le richieste vengono rifiutate.
- **Limite di frequenza:** 60 richieste al minuto per chiave, condivise con la REST API. Il collegamento richiede alcune richieste, e lo stesso vale per ogni chiamata a uno strumento. Oltre il limite, le richieste vengono rifiutate per il resto del minuto. Una chiave separata per il tuo strumento di IA evita che consumi le richieste del tuo server.
- **Messaggi:** ogni risposta di `chat_with_agent` conta come un messaggio del tuo piano. Una risposta deve terminare entro 55 secondi.
- **Accesso:** solo chiavi API. OAuth non è ancora supportato, quindi i client che lo richiedono non possono collegarsi.
- **Fonti:** solo testi e coppie di Q&A. Pagine web, file e pagine Notion si aggiungono nella dashboard.
- **Nessun aggiornamento in tempo reale:** il server risponde a ogni richiesta e non invia notifiche.

Se il tuo client non riesce a collegarsi, controlla l'errore che mostra: una chiave non valida o revocata viene rifiutata con `401`, un account sul piano Free con `403` e troppe richieste con `429`.

## Passi successivi

- Chiama intoCHAT dal tuo codice: [REST API](/it/docs/rest-api).
- Ricevi lead e passaggi sul tuo server nel momento in cui avvengono: [Webhook](/it/docs/webhooks).
- Scrivi buoni testi e coppie di Q&A: [Testo e Q&A](/it/docs/text-and-qa).