Ciele MCP server

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/mcp on your deployment. Use it for a client that connects over HTTP.
The local server is a stdio process 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/mcp

Authenticate 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 stdio server.

Start this program from the repository:

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

Environment 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`	List, read, create, update, duplicate, or delete Assistants.
`manage_flows`	List, read, create, update, reorder, or delete Flows.
`manage_knowledge`	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.
`manage_improvements`	List, read, or update Improvements.
`manage_entities`	Manage Organization Entities and typed Records.
`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 and read your own Teammate conversations.
`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.
`manage_integrations`	Manage Assistant API integrations and model providers.

The server registers sixteen tools. Each domain tool uses an action field for its operations.

Read-only mode classifies each action. It permits list, read, status, query, and export actions while refusing mutations.

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.