Conectar clientes de IA

El servidor MCP de Ciele dispone de dos transportes. Ambos registran las mismas herramientas.

El punto de conexión alojado es POST /api/mcp en tu implementación. Cualquier cliente que acepte una URL de MCP remota puede usarla.
El local server es un proceso stdio que el cliente inicia como proceso hijo.

Utiliza preferentemente el punto de conexión alojado. No necesita comprobación, ni Node.js en el equipo cliente, ni una ruta para mantenerse actualizado.

Esta página refleja la documentación del cliente revisada el 6 de agosto de 2026. Las interfaces de cliente y los formatos de configuración pueden cambiar.

Compatibilidad

Cliente	Endpoint alojado	Local `stdio`
Claude Code	Sí	Sí
Codex CLI, aplicación Codex y extensión Codex IDE	Sí	Sí
Aplicación de escritorio ChatGPT	Sí	Sí
Cursor	Sí	Sí
OpenCode	Sí	Sí
GitHub Copilot en VS Code	Sí	Sí
GitHub Copilot CLI	Sí	Sí
ChatGPT web	Sí	Sin proceso local
Pi	Sin procedimiento integrado	Sin procedimiento integrado

Conéctate al punto de conexión alojado

Crea una clave de API de visor.
Proporciona al cliente la URL del punto de conexión de tu implementación.
Configura el encabezado Authorization como Bearer <key>.

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

El punto de conexión alojado no tiene un conmutador de solo lectura: sus permisos son el rol de la clave. Sin embargo, una clave de Viewer no es un agente de solo lectura: revisar conversaciones cuenta como curación, por lo que puede anclar una conversación, dejar comentarios y eliminarla. Utiliza un servidor stdio local con CIELE_MCP_READ_ONLY=1 cuando el agente no deba cambiar absolutamente nada.

Prepara una conexión local

Instala Node.js 22.6 o una versión posterior.
Clona el repositorio de Ciele.
Crea una clave de API de visor.
Resuelve la ruta absoluta a packages/mcp/bin/ciele-mcp.mjs.
Establece CIELE_MCP_READ_ONLY=1 para la primera conexión.

Sustituye <repo> y el origen de ejemplo en cada configuración.

Claude Code

Ejecuta este 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

Abre /mcp en Claude Code. Confirma que el servidor ciele muestra catorce herramientas.

Consulta la Claude Code MCP guide para conocer las opciones del cliente y los ámbitos de configuración.

Codex y ChatGPT para escritorio

Ejecuta este comando para 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, la aplicación Codex, la extensión Codex IDE y ChatGPT Desktop comparten la misma configuración de Codex MCP.

También puedes editar ~/.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"

Ejecuta codex mcp list o abre /mcp para comprobar la conexión.

Consulta la Codex MCP guide para conocer la configuración actual del cliente.

Cursor

Crea .cursor/mcp.json en un proyecto. También puedes usar la configuración global de 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"
      }
    }
  }
}

Abre Settings > MCP. Habilita ciele y revisa cada llamada a la herramienta solicitada.

Consulta la guía de Cursor MCP para obtener información sobre la configuración global y la seguridad del cliente.

OpenCode

Añade este servidor 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"
        }
      }
    }
  }
}

Ejecuta opencode2 mcp list para comprobar la conexión.

Consulta la guía de OpenCode MCP para ver el esquema actual de la versión 2.

GitHub Copilot en 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"
      }
    }
  }
}

Ejecuta MCP: List Servers desde la Paleta de comandos. Inicia ciele e inspecciona su salida cuando falle una conexión.

Consulta la guía de VS Code MCP para conocer las ubicaciones de configuración y los controles de confianza.

CLI de GitHub Copilot

Ejecuta el comando interactivo /mcp add. Selecciona un servidor stdio local e introduce el comando Ciele.

También puedes empezar con este comando:

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

Añade las tres variables de entorno de Ciele a través de la configuración de MCP de Copilot. No pongas la clave de la API en el control de versiones.

Consulta la guía de GitHub Copilot CLI MCP para conocer el formato de configuración actual.

Prompts copiables

Inicia cada nueva conexión con esta comprobación de solo lectura:

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

Utiliza esta indicación para revisar a los Asistentes:

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

Utiliza esta indicación para revisar la ingesta de conocimiento:

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.

Utiliza esta indicación después de habilitar el acceso de escritura:

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.

Utiliza esta indicación antes de la publicación:

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

Review write operations

Read the proposed tool input before you approve it. API Roles and MCP read-only mode are independent controls.

Clientes sin proceso local

ChatGPT web no puede iniciar un servidor local stdio. En su lugar, apúntalo al punto de conexión alojado. La implementación debe ser accesible desde la internet pública, lo cual no ocurre con una pila local de Ciele Desktop.

Pi no incluye un procedimiento de conexión MCP integrado. Las extensiones de Pi pueden añadir compatibilidad con MCP, pero Ciele no distribuye ni prueba dicha extensión. Utiliza ciele ... --json a través de un flujo de trabajo de shell aprobado o llama directamente a la HTTP API.

Conectar clientes de IA

En esta página