Connetti i client AI

Il server MCP di Ciele dispone di due transport. Entrambi registrano gli stessi strumenti.

• L'endpoint ospitato è POST /api/mcp sulla tua distribuzione. Qualsiasi client che accetta un URL MCP remoto può utilizzarlo.
• Il local server è un processo stdio che il client avvia come processo figlio.

Dai la preferenza all'hosted endpoint. Non richiede alcun checkout, né Node.js sulla macchina client, né un percorso da mantenere aggiornato.

Questa pagina riflette la documentazione client verificata il 6 agosto 2026. Le interfacce client e i formati di configurazione possono cambiare.

Compatibilità

Connettiti all'endpoint ospitato

1. Crea una API key per un viewer.
2. Fornisci al client l'URL dell'endpoint per la tua distribuzione.
3. Configura l'intestazione Authorization come Bearer <key>.

claude mcp add --transport http ciele https://ciele.example.edu/api/mcp \
  --header "Authorization: Bearer ciele_sk_..."

Le autorizzazioni dell'endpoint ospitato corrispondono al Role della chiave. Tuttavia, una chiave Viewer non è un agente di sola lettura. La revisione delle conversazioni rientra nella curatela, pertanto una chiave Viewer può bloccare una conversazione, lasciare un feedback ed eliminare una conversazione. Un deployment self-hosted può impostare CIELE_MCP_READ_ONLY=1 in modo da rifiutare ogni mutazione per ogni chiave. Per un agente che non deve modificare nulla, utilizza un server stdio locale con CIELE_MCP_READ_ONLY=1.

Prepara una connessione locale

1. Installa Node.js 22.6 o versione successiva.
2. Clona il repository di Ciele.
3. Crea una API key per il viewer.
4. Risolvi il percorso assoluto a packages/mcp/bin/ciele-mcp.mjs.
5. Imposta CIELE_MCP_READ_ONLY=1 per la prima connessione.

Sostituisci <repo> e l'origin di esempio in ogni configurazione.

Claude Code

Esegui questo comando:

claude mcp add ciele \
  --env CIELE_API_KEY=ciele_sk_... \
  --env CIELE_BASE_URL=https://ciele.example.edu \
  --env CIELE_MCP_READ_ONLY=1 \
  -- node <repo>/packages/mcp/bin/ciele-mcp.mjs

Apri /mcp in Claude Code. Verifica che il server ciele mostri diciassette strumenti.

Consulta la Claude Code MCP guide per le opzioni client e gli ambiti di configurazione.

Codex e ChatGPT desktop

Esegui questo comando per Codex CLI:

codex mcp add ciele \
  --env CIELE_API_KEY=ciele_sk_... \
  --env CIELE_BASE_URL=https://ciele.example.edu \
  --env CIELE_MCP_READ_ONLY=1 \
  -- node <repo>/packages/mcp/bin/ciele-mcp.mjs

Codex CLI, l'app Codex, l'estensione Codex per IDE e ChatGPT desktop condividono la stessa configurazione Codex MCP.

Puoi anche modificare ~/.codex/config.toml:

[mcp_servers.ciele]
command = "node"
args = ["<repo>/packages/mcp/bin/ciele-mcp.mjs"]
default_tools_approval_mode = "writes"

[mcp_servers.ciele.env]
CIELE_API_KEY = "ciele_sk_..."
CIELE_BASE_URL = "https://ciele.example.edu"
CIELE_MCP_READ_ONLY = "1"

Esegui codex mcp list oppure apri /mcp per verificare la connessione.

Consulta la Codex MCP guide per le impostazioni client attualmente in uso.

Cursor

Crea .cursor/mcp.json in un progetto. Puoi anche utilizzare la configurazione globale di Cursor.

{
  "mcpServers": {
    "ciele": {
      "command": "node",
      "args": ["<repo>/packages/mcp/bin/ciele-mcp.mjs"],
      "env": {
        "CIELE_API_KEY": "ciele_sk_...",
        "CIELE_BASE_URL": "https://ciele.example.edu",
        "CIELE_MCP_READ_ONLY": "1"
      }
    }
  }
}

Apri Settings > MCP. Abilita ciele e verifica ogni chiamata di strumento richiesta.

Consulta la guida MCP di Cursor per informazioni sulla configurazione globale e sulla sicurezza del client.

OpenCode

Aggiungi questo server a opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "ciele": {
        "type": "local",
        "command": ["node", "<repo>/packages/mcp/bin/ciele-mcp.mjs"],
        "environment": {
          "CIELE_API_KEY": "{env:CIELE_API_KEY}",
          "CIELE_BASE_URL": "https://ciele.example.edu",
          "CIELE_MCP_READ_ONLY": "1"
        }
      }
    }
  }
}

Esegui opencode2 mcp list per verificare la connessione.

Consulta la OpenCode MCP guide per lo schema dell'attuale versione 2.

GitHub Copilot in VS Code

Crea .vscode/mcp.json:

{
  "inputs": [
    {
      "id": "ciele-key",
      "type": "promptString",
      "password": true,
      "description": "Ciele API key"
    }
  ],
  "servers": {
    "ciele": {
      "type": "stdio",
      "command": "node",
      "args": ["<repo>/packages/mcp/bin/ciele-mcp.mjs"],
      "env": {
        "CIELE_API_KEY": "${input:ciele-key}",
        "CIELE_BASE_URL": "https://ciele.example.edu",
        "CIELE_MCP_READ_ONLY": "1"
      }
    }
  }
}

Esegui MCP: List Servers dalla Command Palette. Avvia ciele e controlla il suo output quando una connessione non riesce.

Consulta la VS Code MCP guide per informazioni sui percorsi di configurazione e sui controlli di attendibilità.

CLI di GitHub Copilot

Esegui il comando interattivo /mcp add. Seleziona un server stdio locale e inserisci il comando Ciele.

Puoi anche iniziare con questo comando:

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

Aggiungi le tre variabili di ambiente Ciele tramite la configurazione MCP di Copilot. Non inserire la chiave API nel sistema di controllo del codice sorgente.

Consulta la GitHub Copilot CLI MCP guide per il formato di configurazione attualmente in uso.

Prompt copiabili

Inizia ogni nuova connessione con questo controllo in sola lettura:

Call ciele_identity. Show the deployment version, available domains,
Organization ID, and Role. Do not change data.

Usa questo prompt per rivedere gli Assistants:

List all Ciele Assistants. For each Assistant, list its enabled Flows.
Identify duplicate or unclear Flow names. Do not change data.

Usa questo prompt per rivedere l'acquisizione delle conoscenze:

List the Sources linked to Assistant <assistant-id>.
List each Source and its ingestion status.
Report Sources that are not ready. Do not retry or delete a Source.

Usa questo prompt dopo aver abilitato l'accesso in scrittura:

Create one FAQ for Assistant <assistant-id>.
Question: "When does enrollment close?"
Answer: "Enrollment closes on <date>."
Show the proposed tool input and ask for approval before the call.

Usa questo prompt prima della pubblicazione:

Read the publication status for Assistant <assistant-id>.
Summarize the current live version. Do not publish or unpublish anything.

Client senza un processo locale

ChatGPT web non può avviare un server stdio locale. Invece, puntalo all'endpoint ospitato. Il deployment deve essere raggiungibile dalla rete internet pubblica, cosa che non avviene per uno stack locale di Ciele Desktop.

Pi non include una procedura di connessione MCP integrata. Le estensioni Pi possono aggiungere il supporto MCP, ma Ciele non distribuisce né testa tali estensioni. Usa ciele ... --json tramite un flusso di lavoro shell approvato oppure chiama direttamente l'HTTP API.