Cielara Connector

cielara-connector installs the Cielara MCP server into local AI clients and keeps a browser-authorized Cielara connection refreshed.

Install

npm install -g cielara-connector
cielara login --url https://your-cielara.example.com
cielara install

or without a global install:

npx cielara-connector login --url https://your-cielara.example.com
npx cielara-connector install

cielara login opens a browser, runs OAuth authorization-code with PKCE against /api/iam/oauth/*, and stores the connection in:

~/.cielara/connector.json

cielara install writes MCP server entries for:

• Codex: ~/.codex/config.toml
• Claude Code: ~/.claude.json
• Claude Desktop: platform-specific claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json

The installed MCP command is:

npx -y cielara-connector mcp

The mcp command refreshes the stored access token when it is close to expiration, prepares a Python virtualenv for the bundled MCP server, and then starts the server in stdio mode.

Commands

cielara login --url https://your-cielara.example.com
cielara install --target codex
cielara install --target claude
cielara install --target cursor
cielara status
cielara logout
cielara mcp

For local development from this repository, write app configs that point at the checked-out package instead of npm:

node connector/bin/cielara.js install --local

Configuration

Optional login flags:

• --name <name>: store a named connection, default default
• --auth-url <url>: override OAuth/admin URL
• --backend-url <url>: override Cielara backend URL
• --memory-url <url>: override Agent Memory URL; default is direct http://localhost:8001 when logging in via http://localhost:3100, otherwise <backend-url>/api/agent-memory
• --world-model-url <url>: override Agent Fabric World Model base URL; default is <backend-url>/api/world-model (insights backend reverse proxy). Pass an empty value to disable the tool. Same override via env CIELARA_WORLD_MODEL_URL (empty disables).
• --config <path>: override the credential file path

For the local docker/dev stack, this works from the frontend URL:

node connector/bin/cielara.js login --url http://localhost:3100

The connector detects the standard local split ports and uses:

• OAuth/admin: http://localhost:8100
• backend/MCP APIs: http://localhost:8080
• memory API: http://localhost:8001 (direct to agent-memory), or <backend-url>/api/agent-memory when not using the local frontend URL
• world model: http://localhost:8080/api/world-model (same reverse-proxy path as deployed)

Environment overrides used by the installed MCP server:

• CIELARA_CONNECTOR_CONFIG
• CIELARA_BACKEND_URL
• MEMORY_API_URL (also CIELARA_MEMORY_API_URL at login to override defaults)
• WORLD_MODEL_URL (also CIELARA_WORLD_MODEL_URL at login)
• CIELARA_ACCESS_TOKEN
• CIELARA_PYTHON