Ciele MCP server
Give an MCP client controlled access to Ciele administration operations.
The Ciele Model Context Protocol (MCP) server exposes the administration operations to an AI agent. It has two transports, and both register the same tools.
- The hosted endpoint is
POST /api/mcpon your deployment. Use it for a client that connects over HTTP. - The local server is a
stdioprocess that you start from a repository checkout.
Every tool call reaches the Organization through /api/v1, so an operation has one execution path whichever transport asked for it.
Hosted endpoint
Each Ciele deployment serves the endpoint at its own origin. This includes the hosted service, a Docker self-host, and the local stack of Ciele Desktop. The endpoint needs no configuration.
https://ciele.example.edu/api/mcpAuthenticate with an Organization API key in the Authorization header:
Authorization: Bearer ciele_sk_...An unknown or absent key is refused with 401 before any tool is listed.
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.
Protocol revisions
The server speaks the 2026-07-28 revision and the 2025 revisions. It decides the revision from the opening exchange, so a client that has not moved to 2026-07-28 still works.
The 2026-07-28 revision removed protocol sessions. Each request is self-contained, so the hosted endpoint needs no sticky routing and no session store.
Local stdio server
Requirements
- Use Node.js 22.6 or later.
- Clone the Ciele repository.
- Create an Organization API key.
- Use an MCP client that can start a local
stdioserver.
Start this program from the repository:
node <repo>/packages/mcp/bin/ciele-mcp.mjsEnvironment variables
| Variable | Requirement | Purpose |
|---|---|---|
CIELE_API_KEY | Required | Authenticates the Organization. |
CIELE_BASE_URL | Optional | Selects a self-hosted origin. |
CIELE_MCP_READ_ONLY | Optional | Refuses mutation actions when the value is 1. |
CIELE_MCP_MODERN_ONLY | Optional | Refuses 2025-revision clients when the value is 1. |
The read-only check occurs inside the MCP process. A refused mutation does not make an API request.
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.
Available tools
| Tool | Current operations |
|---|---|
ciele_identity | Read deployment, Organization, and Role information. |
manage_assistants | Ask an Assistant a question, then list, read, create, update, duplicate, or delete Assistants. |
manage_flows | Read the Flow catalogue, check a Flow without saving it, read an HTTP Flow's runs, then list, read, create, update, reorder, or delete Flows. |
manage_knowledge | Search the knowledge, then manage Collections, Sources, and FAQs. |
publish_assistant | Read status, publish, unpublish, or restore a publication. |
read_inbox | List, read, export, pin, annotate, rate, or delete Conversations. List, read, and decide Human review requests. |
manage_improvements | List, read, or update Improvements. |
manage_memories | Inspect settings and perform scoped Memory erasure. |
manage_sso | Manage identity claims and the Organization SSO connection. |
manage_help_desks | Manage Help Desks, channels, ordering, and ServiceNow. |
manage_teammates | Manage AI Teammates, their grants, their Routines and their memory. provision does the full setup in one action. |
manage_projects | Manage Projects and the memory document of each Project. |
manage_channels | Read and shape the teammate channels you are in. |
manage_configuration | Manage Skills, Assistant Skill selection, Goals, and Alerts. |
manage_organization | Manage Organization settings, Members, Invites, and API keys. Read the usage meters and spenders of the plan. |
manage_integrations | Manage Assistant API integrations and model providers. |
The server registers sixteen tools: one identity tool and fifteen domain tools. Each domain tool uses an action field for its operations.
Read-only mode classifies each action. It permits list, read, status, query, search, and export actions while refusing mutations.
Search the knowledge
The search action of manage_knowledge finds the passages that match a question. Each result
gives the passage text, its Document title, its Source name, and its URL when it has one. Ciele
does not generate an answer. Your AI client writes the answer and cites the Sources.
{ "action": "search", "query": "How do I connect Salesforce?", "assistantId": "<assistant-id>" }With assistantId, the search uses only the Sources linked to that Assistant. Without it, the
search uses the full Library of the Organization. A viewer key can search, and read-only mode
permits it. A search does not create a Conversation, so it does not appear in the Inbox or in
Insights. Each API key can make 60 searches in one minute.
Ask an Assistant
The ask action of manage_assistants sends a question to an Assistant and returns its answer
with the Sources that it cited. Use it when the client must show the answer of Ciele, not its own
answer.
{ "action": "ask", "id": "<assistant-id>", "question": "How do I connect Salesforce?" }The Assistant answers as its published widget does, with its Flows and its knowledge search. If
the Assistant is not published, the action fails. Send the conversationId of an answer with the
next question to continue the same Conversation. Only the API key that started a Conversation can
continue it. With a different ID, the question starts a new Conversation.
Each question creates a Conversation. Insights does not count it. The Inbox shows it with the
API key label when you set the Staff conversations filter to Include staff or Staff
only. The question uses a model turn on the Provider Connections of the
Organization. For this reason, read-only mode refuses ask. Each API key can ask 20 questions in
one minute. An answer can take some time, because the Assistant can search more than one time.
See AI clients for the configuration of each supported client.
Check the connection
Ask the client to call ciele_identity. Confirm the expected Organization ID, Role, API version, and domain list.
The repository test suite also starts the real stdio process. It verifies initialization, tool discovery, and an authenticated API call.