Server Ciele MCP

Concedi a un client MCP l'accesso controllato alle operazioni di amministrazione di Ciele.

Il server Ciele Model Context Protocol (MCP) espone le operazioni di amministrazione a un agente IA. Dispone di due trasporti, ed entrambi registrano gli stessi strumenti.

L'endpoint ospitato è POST /api/mcp sulla tua distribuzione. Usalo per un client che si connette tramite HTTP.
Il server locale è un processo stdio che avvii da un checkout del repository.

Ogni chiamata dello strumento raggiunge l'Organizzazione tramite /api/v1, quindi un'operazione ha un unico percorso di esecuzione, indipendentemente dal trasporto richiesto.

Endpoint in hosting

Ogni distribuzione Ciele serve l'endpoint presso la propria origine. Ciò include il servizio ospitato, un self-host Docker e lo stack locale di Ciele Desktop. L'endpoint non necessita di configurazione.

https://ciele.example.edu/api/mcp

Effettua l'autenticazione con una chiave API dell'organizzazione nell'intestazione Authorization:

Authorization: Bearer ciele_sk_...

Una chiave sconosciuta o assente viene rifiutata con 401 prima che venga elencato qualsiasi strumento.

The key Role is the permission boundary

The hosted endpoint has no read-only switch. Its permissions are the Role of the key: the operations layer refuses a mutation the Role does not cover with 403. A Viewer key is not a read-only agent, though. Reviewing conversations counts as curation, so a Viewer key can pin a conversation, leave feedback, and delete a conversation. Use CIELE_MCP_READ_ONLY=1 on a stdio server when you need an agent that cannot write at all.

Revisioni del protocollo

Il server supporta la revisione 2026-07-28 e le revisioni 2025. Decide la revisione in base allo scambio iniziale, quindi un client che non è passato a 2026-07-28 funziona comunque.

La revisione 2026-07-28 ha rimosso le sessioni di protocollo. Ogni richiesta è indipendente, pertanto l'endpoint ospitato non necessita di sticky routing né di un archivio di sessione.

Server `stdio` locale

Requisiti

Usa Node.js 22.6 o versioni successive.
Clona il repository Ciele.
Crea una chiave API dell'organizzazione.
Utilizza un client MCP in grado di avviare un server stdio locale.

Avvia questo programma dal repository:

node <repo>/packages/mcp/bin/ciele-mcp.mjs

Variabili di ambiente

Variabile	Requisito	Scopo
`CIELE_API_KEY`	Obbligatoria	Autentica l'organizzazione.
`CIELE_BASE_URL`	Opzionale	Seleziona un'origine self-hosted.
`CIELE_MCP_READ_ONLY`	Opzionale	Rifiuta le azioni di modifica quando il valore è `1`.
`CIELE_MCP_MODERN_ONLY`	Opzionale	Rifiuta i client della revisione 2025 quando il valore è `1`.

Il controllo di sola lettura avviene all'interno del processo MCP. Una modifica rifiutata non genera una richiesta API.

These variables apply to the local server only

A Ciele web container ignores CIELE_MCP_READ_ONLY and CIELE_MCP_MODERN_ONLY. Do not set them on a deployment and expect the hosted endpoint to obey.

Recommended first connection

Use a viewer key and set CIELE_MCP_READ_ONLY=1. Remove one restriction only when the agent must change Ciele data.

Strumenti disponibili

Strumento	Operazioni correnti
`ciele_identity`	Leggi le informazioni su distribuzione, organizzazione e ruolo.
`manage_assistants`	Elenca, leggi, crea, aggiorna, duplica o elimina gli Assistenti.
`manage_flows`	Leggi il catalogo dei Flow, controlla un Flow senza salvarlo, leggi le esecuzioni di un Flow HTTP, quindi elenca, leggi, crea, aggiorna, riordina o elimina i Flow.
`manage_knowledge`	Gestisci Collections, Sources e FAQ.
`publish_assistant`	Leggi lo stato, pubblica, annulla la pubblicazione o ripristina una pubblicazione.
`read_inbox`	Elenca, leggi, esporta, metti in evidenza, annota, valuta o elimina le Conversazioni.
`manage_improvements`	Elenca, leggi o aggiorna gli Improvements.
`manage_entities`	Gestisci le entità dell'organizzazione e i record tipizzati.
`manage_memories`	Ispeziona le impostazioni ed esegui la cancellazione della memoria con ambito.
`manage_sso`	Gestisci le richieste di identità e la connessione SSO dell'organizzazione.
`manage_help_desks`	Gestisci Help Desk, canali, ordinamento e ServiceNow.
`manage_teammates`	Gestisci gli AI Teammate, i loro grant, le loro Routine e la loro memoria. `provision` esegue la configurazione completa con una sola azione.
`manage_projects`	Gestisci i Progetti e il documento di memoria di ciascun Progetto.
`manage_channels`	Leggi e personalizza i canali dei colleghi di cui fai parte.
`manage_configuration`	Gestisci le competenze, la selezione delle competenze dell'assistente, gli obiettivi e gli avvisi.
`manage_organization`	Gestisci le impostazioni dell'organizzazione, i membri, gli inviti e le chiavi API.
`manage_integrations`	Gestisci le integrazioni API degli assistenti e i provider di modelli.

Il server registra sedici strumenti. Ogni strumento di dominio utilizza un campo action per le sue operazioni.

La modalità di sola lettura classifica ogni azione. Consente le azioni di elenco, lettura, stato, query ed esportazione, ma rifiuta le mutazioni.

Vedi AI clients per la configurazione di ciascun client supportato.

Verifica la connessione

Chiedi al client di chiamare ciele_identity. Conferma l'Organization ID, il Role, la versione dell'API e l'elenco dei domini previsti.

La suite di test del repository avvia anche il vero processo stdio. Verifica l'inizializzazione, il rilevamento degli strumenti e una chiamata API autenticata.