Connect AI clients

The Ciele MCP server has two transports. Both register the same tools.

• The hosted endpoint is POST /api/mcp on your deployment. Any client that accepts a remote MCP URL can use it.
• The local server is a stdio process that the client starts as a child process.

Prefer the hosted endpoint. It needs no checkout, no Node.js on the client machine, and no path to keep current.

This page reflects client documentation checked on August 6, 2026. Client interfaces and configuration formats can change.

Compatibility

Connect to the hosted endpoint

1. Create a viewer API key.
2. Give the client the endpoint URL for your deployment.
3. Configure the Authorization header as Bearer <key>.

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

The hosted endpoint has no read-only switch. Use a Viewer key when the agent must not change data.

Prepare a local connection

1. Install Node.js 22.6 or later.
2. Clone the Ciele repository.
3. Create a viewer API key.
4. Resolve the absolute path to packages/mcp/bin/ciele-mcp.mjs.
5. Set CIELE_MCP_READ_ONLY=1 for the first connection.

Replace <repo> and the example origin in each configuration.

Claude Code

Run this command:

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

Open /mcp in Claude Code. Confirm that the ciele server shows fourteen tools.

See the Claude Code MCP guide for client options and configuration scopes.

Codex and ChatGPT desktop

Run this command for 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, the Codex app, the Codex IDE extension, and ChatGPT desktop share the same Codex MCP configuration.

You can also edit ~/.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"

Run codex mcp list or open /mcp to check the connection.

See the Codex MCP guide for current client settings.

Cursor

Create .cursor/mcp.json in a project. You can also use the global Cursor configuration.

{
  "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"
      }
    }
  }
}

Open Settings > MCP. Enable ciele and review each requested tool call.

See the Cursor MCP guide for global configuration and client security information.

OpenCode

Add this server to 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"
        }
      }
    }
  }
}

Run opencode2 mcp list to check the connection.

See the OpenCode MCP guide for the current version 2 schema.

GitHub Copilot in VS Code

Create .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"
      }
    }
  }
}

Run MCP: List Servers from the Command Palette. Start ciele and inspect its output when a connection fails.

See the VS Code MCP guide for configuration locations and trust controls.

GitHub Copilot CLI

Run the interactive /mcp add command. Select a local stdio server and enter the Ciele command.

You can also start with this command:

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

Add the three Ciele environment variables through the Copilot MCP configuration. Do not put the API key in source control.

See the GitHub Copilot CLI MCP guide for the current configuration format.

Copyable prompts

Start every new connection with this read-only check:

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

Use this prompt to review Assistants:

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

Use this prompt to review Knowledge ingestion:

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.

Use this prompt after you enable write access:

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.

Use this prompt before publication:

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

Clients without a local process

ChatGPT web cannot start a local stdio server. Point it at the hosted endpoint instead. The deployment must be reachable from the public internet, which a local Ciele Desktop stack is not.

Pi does not include a built-in MCP connection procedure. Pi extensions can add MCP support, but Ciele does not ship or test such an extension. Use ciele ... --json through an approved shell workflow, or call the HTTP API directly.