Se sei arrivato qui probabilmente hai già visto il **[server MCP](/it/mcp/getting-started/)** e la
**[referenza API](/it/api/getting-started/)** separatamente. Sono due facce della stessa superficie
`/public/v1` — questa pagina è il ponte che le collega, per il caso reale «voglio il mio assistente IA
(Claude, Cursor) che parla con i miei dati di Aymar Agents, E anche il mio backend che chiama
direttamente l'API pubblica».

## Perché sono la stessa cosa internamente

Il server MCP **non ha logica propria**: i suoi tool sono generati leggendo la stessa definizione OpenAPI
che documenta questa referenza REST, e ogni chiamata di un tool inoltra la tua stessa chiave API a
`/public/v1`, così com'è. Tutto il controllo reale — permessi, piano, limiti, isolamento per account — lo
applica l'API, mai l'adattatore MCP. Per questo: **una sola chiave, un solo insieme di scope, due modi di
usarli.**

## Il ponte in 3 passi

1. **Crea una chiave API con gli scope che servono a entrambi gli usi.** Vedi **[Chiavi API](/it/guides/claves-api/)**
   — viene mostrata per intero una sola volta, conservala. Se il tuo assistente IA deve solo leggere i lead
   e il tuo backend deve anche creare ticket, assegna alla chiave entrambi gli scope:
   `tenant:leads.read` e `tenant:tickets.manage`, per esempio — la stessa chiave serve entrambi gli usi
   contemporaneamente.
2. **Collega il tuo assistente IA tramite MCP** con quella chiave — Claude Desktop, Claude Code o Cursor
   parlano `Streamable HTTP` su `https://mcp.aymaragents.com/mcp` con l'header `X-Api-Key`. Vedi **[Collega il tuo
   assistente](/it/mcp/connect/)**. Da qui, il tuo assistente può leggere e (con la tua conferma, vedi **[La
   conferma nelle scritture](/it/mcp/confirm/)**) scrivere nel tuo account durante la conversazione.
3. **Collega il tuo backend direttamente all'API pubblica**, con la stessa chiave, nell'header `X-API-Key`
   di ogni richiesta HTTP — senza MCP in mezzo, per il codice che gira senza supervisione umana turno per
   turno. Vedi i **[5 casi d'uso con esempi di codice](/it/api/use-cases/)**.

## Quando usare ciascun percorso

| Percorso | A cosa serve | Conferma |
| --- | --- | --- |
| **MCP** (`https://mcp.aymaragents.com/mcp`) | Il tuo assistente conversazionale (Claude, Cursor) esplora e agisce sul tuo account dentro una sessione con una persona presente. | Ogni scrittura richiede `confirm: true` — pensato perché la persona veda il riepilogo dell'azione prima di approvarla. |
| **API pubblica** (`https://api.aymaragents.com/public/v1`) | Il tuo backend, uno script programmato, o un'integrazione con un altro sistema (CRM, helpdesk, Zapier…) che gira senza supervisione turno per turno. | Nessun passaggio di conferma intermedio — il tuo codice decide ed esegue direttamente. |

Un esempio reale che usa entrambi insieme: il tuo assistente Claude Code, collegato tramite MCP, consulta
e qualifica i lead mentre ci parli; il tuo stesso backend, con la stessa chiave ma tramite l'API diretta,
sincronizza quegli stessi lead verso il tuo CRM ogni ora senza che nessuno lo guardi — vedi
**[Sincronizzare i lead verso il tuo CRM](/it/api/use-cases/)**.

## Vedi anche

- **[Cos'è e cosa non è](/it/mcp/getting-started/)** — il server MCP spiegato, e con cosa non confonderlo
  (BYO-MCP).
- **[Iniziare con l'API](/it/api/getting-started/)** — autenticazione, prima richiesta, formato della
  risposta.
- **[Chiavi API](/it/guides/claves-api/)** — scope, origini consentite e revoca.
- **[Catalogo dei tool](/it/mcp/tools/)** — ogni tool MCP con la sua operazione REST equivalente.