DocsMCP

Server MCP: gestisci il tuo workspace Nodale da Claude Code

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.

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:

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

Per gli agenti AI: questa pagina in Markdown