Connetti i client IA

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

• L'endpoint in hosting è 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'endpoint in hosting. Non richiede alcun checkout, né Node.js sul computer 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 visualizzatore.
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_..."

L'endpoint in hosting non ha un interruttore di sola lettura: le sue autorizzazioni sono determinate dal ruolo della chiave. Una chiave Viewer non è però un agente di sola lettura: la revisione delle conversazioni conta come curation, quindi può fissare una conversazione, lasciare un feedback ed eliminarla. Utilizza un server stdio locale con CIELE_MCP_READ_ONLY=1 quando l'agente non deve apportare alcuna modifica.

Prepara una connessione locale

1. Installa Node.js 22.6 o una versione successiva.
2. Clona il repository 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 quattordici strumenti.

Consulta la guida MCP di Claude Code per le opzioni del 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 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 o apri /mcp per verificare la connessione.

Consulta la guida Codex MCP per le impostazioni client correnti.

Cursore

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 controlla ogni chiamata allo 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 guida OpenCode MCP per lo schema attuale della 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 fallisce.

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 controllo del codice sorgente.

Consulta la guida GitHub Copilot CLI MCP per il formato di configurazione corrente.

Prompt copiabili

Avvia ogni nuova connessione con questo controllo di 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 Assistenti:

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 verificare l'acquisizione della conoscenza:

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 processo locale

ChatGPT web non può avviare un server stdio locale. Indirizzalo invece all'endpoint in hosting. La distribuzione deve essere raggiungibile dalla rete Internet pubblica, cosa che uno stack Ciele Desktop locale non è.

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