Servidor MCP de Ciele
Concede a un cliente MCP acceso controlado a las operaciones de administración de Ciele.
El servidor del Protocolo de Contexto de Modelo (MCP) de Ciele expone las operaciones de administración a un agente de IA. Cuenta con dos transportes, y ambos registran las mismas herramientas.
- El hosted endpoint es
POST /api/mcpen tu implementación. Úsalo para un cliente que se conecta a través de HTTP. - El local server es un proceso
stdioque inicias a partir de una clonación del repositorio.
Cada llamada a una herramienta llega a la organización a través de /api/v1,
por lo que una operación tiene una única ruta de ejecución, independientemente
del transporte que la haya solicitado.
Endpoint alojado
Cada implementación de Ciele atiende el endpoint en su propio origen. Esto incluye el servicio alojado, un autoalojamiento con Docker y la pila local de Ciele Desktop. El endpoint no requiere ninguna configuración.
https://ciele.example.edu/api/mcpAutentícate con una Organization API key en el
encabezado Authorization:
Authorization: Bearer ciele_sk_...Si la clave es desconocida o no está presente, se rechaza con 401 antes de que
se muestre ninguna herramienta.
The key Role is the permission boundary
The permissions of the hosted endpoint are the Role of the key. The operations layer refuses a mutation that 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.
A self-hosted deployment can set CIELE_MCP_READ_ONLY=1 on the application. Then the hosted endpoint refuses every mutation action for every key. For one read-only agent on a shared deployment, use CIELE_MCP_READ_ONLY=1 on a stdio server.
Revisiones del protocolo
El servidor utiliza la revisión 2026-07-28 y las revisiones de 2025. Determina
la revisión a partir del intercambio inicial, por lo que un cliente que no haya
migrado a 2026-07-28 sigue funcionando.
La revisión 2026-07-28 eliminó las sesiones de protocolo. Cada solicitud es
autónoma, por lo que el endpoint alojado no necesita enrutamiento persistente ni
almacenamiento de sesiones.
Servidor local de stdio
Requisitos
- Utiliza Node.js 22.6 o una versión posterior.
- Clona el repositorio de Ciele.
- Crea una clave API de la organización.
- Utiliza un cliente MCP que pueda iniciar un servidor local
stdio.
Inicia este programa desde el repositorio:
node <repo>/packages/mcp/bin/ciele-mcp.mjsVariables de entorno
| Variable | Requisito | Finalidad |
|---|---|---|
CIELE_API_KEY | Obligatoria | Autentica a la organización. |
CIELE_BASE_URL | Opcional | Selecciona un origen autoalojado. |
CIELE_MCP_READ_ONLY | Opcional | Rechaza las acciones de mutación cuando el valor es 1. |
CIELE_MCP_MODERN_ONLY | Opcional | Rechaza a los clientes de la revisión 2025 cuando el valor es 1. |
La comprobación de solo lectura se realiza dentro del proceso MCP. Una mutación rechazada no realiza ninguna solicitud a la API.
These variables on a deployment
A Ciele web container obeys CIELE_MCP_READ_ONLY. Then the hosted endpoint refuses mutation actions for every key. The container ignores CIELE_MCP_MODERN_ONLY, and the hosted endpoint always accepts 2025-revision clients.
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.
Herramientas disponibles
| Herramienta | Operaciones actuales |
|---|---|
ciele_identity | Lee la información de la implementación, de la organización y de los roles. |
manage_assistants | Haz una pregunta a un asistente y, a continuación, enumera, lee, crea, actualiza, duplica o elimina asistentes. |
manage_flows | Lee el catálogo de Flows, comprueba un Flow sin guardarlo, lee las ejecuciones de un Flow HTTP y, a continuación, lista, lee, crea, actualiza, reordena o elimina Flows. |
manage_knowledge | Busca en la base de conocimientos y, a continuación, gestiona Collections, Sources y FAQs. |
publish_assistant | Consulta el estado, publica, despublica o restaura una publicación. |
read_inbox | Lista, lee, exporta, ancla, anota, valora o elimina conversaciones. Enumera, lee y decide las solicitudes de revisión humana. |
manage_improvements | Enumera, lee o actualiza Improvements. |
manage_memories | Revisa la configuración y realiza un borrado de memoria con ámbito definido. |
manage_sso | Gestiona las reclamaciones de identidad y la conexión SSO de la organización. |
manage_help_desks | Gestiona los Help Desks, los canales, el orden y el destino de los tickets. |
manage_teammates | Gestiona los AI Teammates, sus grants, sus Routines y su memoria. provision realiza la configuración completa en una sola acción. |
manage_projects | Gestiona los Projects, sus milestones y el documento de memoria de cada Project. |
manage_tasks | Enumera, lee, crea, modifica y elimina Tasks. Comenta las tareas y gestiona las etiquetas de las tareas. |
manage_channels | Lee y da forma a los canales de compañeros de equipo en los que participas. |
manage_configuration | Gestiona Skills, la selección de Skills del asistente, Goals, Alerts y Quick Texts. |
manage_organization | Gestiona la configuración de la organización, los miembros, los roles y sus capacidades, las invitaciones y las claves API. Consulta los medidores de uso y los elementos generadores de gasto del plan, así como el registro de auditoría. |
manage_integrations | Gestiona las integraciones de la API del asistente y los proveedores de modelos. |
El servidor registra diecisiete herramientas: una herramienta de identidad y
dieciséis herramientas de dominio. Cada herramienta de dominio utiliza un campo
action para sus operaciones.
El modo de solo lectura clasifica cada acción. Permite las acciones list, read, status, query, search y export, pero rechaza las mutaciones.
Busca en la base de conocimientos
La acción search de manage_knowledge busca los pasajes que coinciden con una
pregunta. Cada resultado muestra el texto del pasaje, el título del documento,
el nombre de la fuente y, cuando la haya, su URL. Ciele no genera una respuesta.
Tu cliente de IA redacta la respuesta y cita las fuentes.
{ "action": "search", "query": "How do I connect Salesforce?", "assistantId": "<assistant-id>" }Con assistantId, la búsqueda utiliza únicamente las Fuentes vinculadas a ese
Asistente. Sin ella, la búsqueda utiliza la Library completa de la Organization.
Una clave de visor puede realizar búsquedas, y el modo de solo lectura lo
permite. Una búsqueda no crea una Conversation, por lo que no aparece en Inbox
ni en Insights. Cada clave API puede realizar 60 búsquedas en un minuto.
Pregúntale a un asistente
La acción ask de manage_assistants envía una pregunta a un asistente y
devuelve su respuesta junto con las fuentes que ha citado. Úsala cuando el
cliente deba mostrar la respuesta de Ciele, no su propia respuesta.
{ "action": "ask", "id": "<assistant-id>", "question": "How do I connect Salesforce?" }El Asistente responde como lo hace su widget publicado, con sus Flows y su
búsqueda en la base de conocimientos. Si el Assistant no está publicado, la
acción falla. Envía el conversationId de una respuesta junto con la siguiente
pregunta para continuar la misma Conversation. Solo la clave API que inició una
Conversation puede continuarla. Con un ID diferente, la pregunta inicia una
nueva Conversation.
Cada pregunta crea una Conversation. Insights no lo contabiliza. La bandeja de
entrada lo muestra con la etiqueta API key cuando estableces el filtro
Staff conversations en Include staff o Staff only. La pregunta
utiliza un turno de modelo en las Provider Connections de la Organization. Por
este motivo, el modo de solo lectura rechaza ask. Cada clave de API puede
formular 20 preguntas en un minuto. Una respuesta puede tardar cierto tiempo, ya
que el Asistente puede realizar búsquedas más de una vez.
Consulta AI clients para ver la configuración de cada cliente compatible.
Comprueba la conexión
Pídele al cliente que llame a ciele_identity. Confirma el Organization ID, el
Role, la versión de la API y la lista de dominios esperados.
El conjunto de pruebas del repositorio también inicia el proceso real stdio.
Verifica la inicialización, el descubrimiento de herramientas y una llamada a la
API autenticada.