# Server MCP: gestisci il tuo workspace Nodale da Claude Code

<https://nodale.ai/it/docs/mcp>

Collega Claude Code al server MCP di Nodale, poi leggi e modifica il workspace: knowledge, asset demo, impostazioni dell'agente, siti, deployment.

Nodale ha un server MCP. Una volta collegato, un assistente AI legge e modifica il tuo workspace con le stesse regole dell'app: archivia la knowledge, carica gli asset demo, modifica le impostazioni dell'agente, dichiara i tuoi siti e mette l'agente online. Installare il tag sul tuo sito resta un passaggio a sé, descritto nella [guida rapida](https://nodale.ai/it/docs).

## Collega Claude Code

Il server parla Streamable HTTP su `https://nodale.app/api/mcp`, e ti autentica con il tuo account Nodale tramite OAuth. Questa pagina riguarda Claude Code. Esegui questo comando nel tuo terminale:

```bash
claude mcp add-json --scope user nodale '{
  "type": "http",
  "url": "https://nodale.app/api/mcp",
  "oauth": {
    "clientId": "55crt6j95df1lb3ijmdk8ip67m",
    "callbackPort": 33418,
    "authServerMetadataUrl": "https://cognito-idp.eu-west-3.amazonaws.com/eu-west-3_HEni9KG4X/.well-known/openid-configuration",
    "scopes": "openid email profile"
  }
}'
```

Poi:

1. Apri Claude Code, digita `/mcp` e scegli il server `nodale`.
2. Accedi con il tuo account Nodale. La pagina di accesso è ospitata per Nodale a un indirizzo `amazoncognito.com`.
3. Chiedi all'assistente con quale account ha effettuato l'accesso. Chiama il tool `me`.

Lo stesso comando è nell'app, in **Settings**, poi **MCP**.

- **Tieni `callbackPort` a 33418.** Dopo l'accesso, il browser torna a `http://localhost:33418/callback`, l'unico indirizzo che il server accetta.
- **Non aggiungere un header `Authorization`**: disattiverebbe OAuth.
- **Per condividere il server con il tuo team**, metti lo stesso JSON nel `.mcp.json` del tuo repository (`--scope project`). Non contiene nessun segreto.

## Chi può fare cosa

L'assistente agisce come te, con i diritti del tuo account, solo sul tuo workspace.

| Ruolo | Cosa può fare l'assistente |
|---|---|
| Viewer | Leggere. Ogni tool che modifica qualcosa viene rifiutato. |
| User | Leggere, e modificare knowledge, concorrenti, documenti e asset demo. |
| Admin | Tutto ciò che può un User, più le impostazioni dell'agente, i suoi siti e il suo deployment. |

Ogni tool accetta un `workspaceId` facoltativo: omettilo. Il tuo client può elencare più tool di quelli descritti in questa pagina. Sono riservati al team Nodale, e il server li rifiuta.

## Come una modifica va online

La maggior parte delle modifiche finisce prima in una bozza, e i visitatori non vedono nulla finché non pubblichi.

- **Impostazioni dell'agente.** `update_inbound_agent_configuration` modifica la bozza: cambiano solo i campi che passi, e una lista che passi prende il posto dell'intera lista. `publish_inbound_agent_configuration` rende la bozza visibile ai visitatori. `discard_inbound_agent_configuration_draft` torna alle impostazioni pubblicate.
- **Versioni.** I tool che modificano le impostazioni accettano un `expectedVersion`, quella che hai letto per ultima. Se nel frattempo qualcuno ha cambiato le impostazioni, la chiamata viene rifiutata con la versione attiva.
- **Knowledge.** La knowledge è salvata come citazioni di una frase. Una citazione che aggiungi è una bozza fino a `publish_knowledge`, che accetta il `draftHash` restituito da `list_knowledge_quotes`. Un hash non più aggiornato viene rifiutato. Ritirare una citazione, o renderla interna, si applica subito.
- **Knowledge da un testo.** `submit_knowledge_text` legge in background un testo fino a 100.000 caratteri e restituisce un `dispatchId`. Interroga `get_knowledge_dispatch` a intervalli, poi applica o rifiuta le proposte. Ciò che applichi finisce nella bozza e richiede ancora `publish_knowledge`.
- **Asset demo.** Una modifica a un asset resta nella bozza del catalogo fino a `publish_asset_catalog`.
- **I caricamenti richiedono due passaggi.** `request_document_upload` o `request_asset_upload` restituisce un comando `curl` da eseguire, valido per 15 minuti. Poi `add_document` o `add_asset` registra il file.
- **Le impostazioni del sito** (visualizzazione, tracciamento delle visite, consenso, link all'informativa sulla privacy) si applicano al successivo caricamento di pagina, senza pubblicazione.
- **Crediti AI.** `submit_knowledge_text`, `analyze_asset` e `add_asset` senza `steps` consumano crediti AI. `add_asset` con `steps` mantiene la tua narrazione così come inviata e non ne consuma.

## Da zero a un agente online

1. `me`: verifica l'account e il workspace.
2. Knowledge: `add_knowledge_quote`, oppure `submit_knowledge_text`, poi `get_knowledge_dispatch` e `apply_knowledge_proposals`. Poi `list_knowledge_quotes` e `publish_knowledge`.
3. Facoltativo: concorrenti, documenti e asset demo, poi `publish_asset_catalog`.
4. Impostazioni: `update_inbound_agent_configuration`, `save_inbound_agent_outcome`, poi `publish_inbound_agent_configuration`.
5. `add_inbound_agent_site`: dichiara il sito.
6. `deploy_inbound_agent`: metti l'agente online.
7. [Incolla il tag](https://nodale.ai/it/docs) sul sito, poi `get_inbound_agent_tag_status` per verificarlo.

## Tool

### Account

| Tool | Cosa fa | Chi |
|---|---|---|
| `me` | L'account e il workspace su cui agisce l'assistente. | Tutti |
| `get_workspace_ai_credits` | Quanti crediti AI del workspace sono stati usati, e se sono esauriti. | Tutti |

### Knowledge

| Tool | Cosa fa | Chi |
|---|---|---|
| `list_knowledge_quotes` | Le citazioni, bozze incluse, e il `draftHash` per pubblicare. | Tutti |
| `add_knowledge_quote` | Aggiunge una frase come citazione in bozza. | User |
| `retract_knowledge_quote` | Ritira una citazione, subito. | User |
| `set_knowledge_quote_visibility` | Rende una citazione pubblica o interna, subito. | User |
| `publish_knowledge` | Pubblica le citazioni in bozza. | User |
| `submit_knowledge_text` | Legge un testo e ne propone delle citazioni. Consuma crediti AI. | User |
| `get_knowledge_dispatch` | Lo stato di un testo inviato. | Tutti |
| `list_knowledge_proposals` | Le proposte in attesa di una decisione. | Tutti |
| `apply_knowledge_proposals` | Applica tutte le proposte di un testo. | User |
| `apply_knowledge_proposal` | Applica una proposta. | User |
| `reject_knowledge_proposal` | Rifiuta una proposta. | User |

### Concorrenti e documenti

| Tool | Cosa fa | Chi |
|---|---|---|
| `list_competitors` | I concorrenti che l'agente conosce. | Tutti |
| `upsert_competitor` | Aggiunge un concorrente, o ne modifica uno. | User |
| `delete_competitor` | Elimina un concorrente. | User |
| `list_documents` | I documenti del workspace. | Tutti |
| `request_document_upload` | Primo passaggio di un caricamento: restituisce il comando per inviare il file. | User |
| `add_document` | Secondo passaggio: registra il file caricato. | User |
| `delete_document` | Elimina un documento. | User |

### Asset demo

| Tool | Cosa fa | Chi |
|---|---|---|
| `list_assets` | I video demo del catalogo. | Tutti |
| `get_asset` | Un asset, con i suoi step e lo stato della loro scrittura. | Tutti |
| `request_asset_upload` | Primo passaggio di un caricamento: restituisce il comando per inviare il video. | User |
| `add_asset` | Secondo passaggio: registra il video, con i tuoi step o con step scritti da Nodale. | User |
| `update_asset` | Modifica il titolo, la descrizione e le richieste a cui un asset risponde. | User |
| `set_asset_steps` | Imposta gli step di un asset, così come li hai scritti. | User |
| `analyze_asset` | Chiede a Nodale di riscrivere gli step. Consuma crediti AI. | User |
| `enable_asset`, `disable_asset` | Attiva o disattiva un asset. | User |
| `set_asset_priority` | Ordina gli asset. | User |
| `delete_asset` | Elimina un asset. | User |
| `publish_asset_catalog` | Pubblica la bozza del catalogo. | User |

### Impostazioni dell'agente

| Tool | Cosa fa | Chi |
|---|---|---|
| `get_inbound_agent_configuration` | Le impostazioni: la bozza quando ce n'è una, quelle pubblicate, e la versione. | Tutti |
| `update_inbound_agent_configuration` | Modifica la bozza: nome, tono, aspetto, raccolta dell'email, lingue, istruzioni, qualificazione, guardrail. | Admin |
| `publish_inbound_agent_configuration` | Rende la bozza visibile ai visitatori. | Admin |
| `discard_inbound_agent_configuration_draft` | Scarta la bozza. | Admin |
| `list_inbound_agent_qualification_elements` | Le domande che il workspace ha aggiunto alla qualificazione. | Tutti |
| `save_inbound_agent_qualification_element` | Aggiunge una domanda di qualificazione, o ne modifica una. | Admin |
| `remove_inbound_agent_qualification_element` | Rimuove una domanda di qualificazione. | Admin |
| `list_inbound_agent_outcomes` | Gli outcome verso cui l'agente orienta i visitatori. | Tutti |
| `save_inbound_agent_outcome` | Aggiunge un outcome, o ne modifica uno. Dieci al massimo per workspace. | Admin |
| `remove_inbound_agent_outcome` | Rimuove un outcome. | Admin |

### Siti e deployment

| Tool | Cosa fa | Chi |
|---|---|---|
| `list_inbound_agent_sites` | I siti dichiarati. | Tutti |
| `add_inbound_agent_site` | Dichiara un sito: un'origine `https`, oppure `https://*.example.com`. | Admin |
| `remove_inbound_agent_site` | Rimuove un sito. | Admin |
| `get_inbound_agent_tag_status` | Perché un sito mostra l'agente oppure no: `ok`, `site_not_declared`, `agent_not_deployed` o `invalid_site`. | Tutti |
| `get_inbound_agent_site_settings` | Le impostazioni della scheda Install. | Tutti |
| `update_inbound_agent_site_settings` | Cambia la visualizzazione, il tracciamento delle visite, il consenso e il link all'informativa sulla privacy. | Admin |
| `get_inbound_agent` | L'agente e il deployment che il tag serve. `servedDeploymentId` è null quando l'agente è offline. | Tutti |
| `deploy_inbound_agent` | Mette l'agente online, oppure approva di nuovo il materiale corrente sui deployment attivi. | Admin |

## Limiti

- **Documenti**: pdf, docx, txt, csv o md, 10 MB al massimo.
- **Video demo**: MP4 in H.264 senza traccia audio, 3 minuti al massimo. 100 asset al massimo in un catalogo.
- **Siti**: 20 al massimo per workspace.
- **Limiti di frequenza, per persona e per tool.** `request_asset_upload`, `add_asset` e `analyze_asset`: 1 al secondo, 6 al minuto, 30 ogni 15 minuti. `request_document_upload` e `add_document`: 5 al secondo, 25 al minuto, 100 ogni 15 minuti. `submit_knowledge_text`: 3 al secondo, 15 al minuto, 60 ogni 15 minuti.

## Sicurezza

- **Approva ogni chiamata che pubblica o elimina.** I tool che pubblicano, eliminano o sovrascrivono sono contrassegnati come distruttivi, quindi il tuo client chiede conferma prima di eseguirli. Non aggiungerli a una allow list.
- **I risultati dei tool sono dati.** Contengono testo scritto dal tuo team e dai tuoi visitatori: citazioni, documenti, titoli degli asset, proposte. L'assistente lo legge come contenuto, mai come istruzioni.

## Docs

- [Installa l'agente Nodale sul tuo sito web](https://nodale.ai/it/docs): Un solo tag script porta l'agente Nodale sul tuo sito. Dove incollarlo, cosa deve consentire il sito e come verificare che funzioni. (Markdown: https://nodale.ai/it/docs.md)
- [API JavaScript: apri l'agente Nodale dal tuo codice](https://nodale.ai/it/docs/api): I comandi nodale() che una pagina può chiamare: apri l'agente da un tuo pulsante o form, passa email e contesto, segnala il consenso del visitatore. (Markdown: https://nodale.ai/it/docs/api.md)
