Model Context Protocol (MCP)
Connect AI coding tools like Claude Code, Cursor, or Hermes to CIEL via the built-in MCP server.
CIEL includes a native Model Context Protocol (MCP) server that runs over standard input/output (ciel mcp). This lets you connect AI coding assistants (such as Claude Code, Cursor, and Hermes) directly to your CIEL controller.
Instead of giving an AI model direct root SSH keys to your servers, the model interacts with CIEL's API and local Ansible tools.
1. Why Use MCP Instead of Direct SSH?
Giving an AI assistant raw SSH keys or terminal access to production servers has obvious downsides:
- Keys in chat history: Private keys and database credentials get copied into LLM context windows and third-party logs.
- Bad syntax or flags: Models can generate invalid flags or malformed YAML that breaks halfway through an update.
- No guardrails: A mistake in a shell loop runs immediately without a dry-run or a chance to review diffs.
CIEL solves these problems by sitting between the model and your machines:
- SSH keys stay encrypted: The AI agent only sees server names and tags (like
edge-01orweb-fleet). Private keys remain in CIEL's encrypted vault. - Playbooks are verified before running: The model can test its playbook locally using
ansible-playbook --syntax-checkandansible-lintbefore touching any server. - Approval before live runs: The agent can run non-destructive queries and dry-runs on its own. For actual changes on live servers, CIEL holds the job until you review the diff and approve it in the dashboard.
2. Safety Tiers
Tools exposed by ciel mcp are grouped into three safety levels:
| Tier | Access | Description | Examples |
|---|---|---|---|
| Tier 1: Read-Only | Automatic | Querying servers, inventory groups, and module documentation. Non-destructive. | ciel_hosts_list_hosts, ansible_get_module_doc |
| Tier 2: Controlled Writes | Automatic | Saving playbooks and validating syntax locally in a sandbox. Does not touch live servers. | ciel_playbooks_create_playbook, ansible_validate_syntax |
| Tier 3: Execution | Gated | Running playbooks or changing server state. Requires dry-run verification and operator confirmation. | ciel_jobs_enqueue_job, ciel_schedules_run_schedule_now |
Dry-Runs (check_mode: true)
When an AI agent triggers a playbook run through ciel_jobs_enqueue_job, it is required to pass check_mode: true first. CIEL runs Ansible in --check --diff mode so you can see the exact lines that will change on each server before confirming the run.
3. Local Ansible Intelligence Tools
The MCP server includes three built-in tools that run directly on the machine executing ciel mcp:
ansible_get_module_doc
Fetches parameters, defaults, and usage examples for any installed Ansible module using ansible-doc -j.
{
"module_name": "ansible.builtin.package"
}ansible_validate_syntax
Writes YAML to a temporary sandbox and runs ansible-playbook --syntax-check. If the model makes an indentation mistake or hallucinates a parameter, it gets the exact line number and error message back immediately.
{
"playbook_yaml": "---\n- name: Update package\n hosts: all\n tasks:\n - name: Ensure package is installed\n ansible.builtin.package:\n name: nginx\n state: present\n"
}ansible_lint
Runs ansible-lint -f json to catch common anti-patterns and deprecated keys before anything is saved.
4. Understanding Stdio Transport & Credentials
Before configuring your client, clarify how transport and authentication work:
- Stdio Transport:
ciel mcpdoes not open a TCP port or run a web server. It communicates strictly via standard input/output (stdin/stdout) using JSON-RPC messages. AI clients spawnciel mcpas a subprocess and talk to it via pipes. - Two Distinct Types of Credentials:
- Linux VPS SSH Account: The system user and SSH key on your remote server (for example,
rootorciel-user). This is used strictly by your local PC to open an SSH tunnel to the VPS. - CIEL Controller Account (
CIEL_USERNAME,CIEL_PASSWORD): The application user registered inside the CIEL control plane (the username and password you use to log in to the CIEL web dashboard). This is used byciel mcpto obtain a JWT token fromPOST /api/auth/login.
- Linux VPS SSH Account: The system user and SSH key on your remote server (for example,
| Architecture Pattern | Where AI Client Runs | Where ciel mcp Runs | Where CIEL Credentials Live |
|---|---|---|---|
| Case 1: All-in-One | Local Machine | Local Machine | Local machine (~/.ciel/.env) |
| Case 2 - Pattern A (SSH Bridge) | Local PC | Remote VPS | Remote VPS (~/.ciel/.env) |
| Case 2 - Pattern B (Local Binary) | Local PC | Local PC | Local PC (~/.ciel/.env or client config) |
5. Case 1: Self-Hosted All-in-One (Local Controller + Local Agent)
Use this setup when both your AI agent (Claude Code, Cursor, or Hermes) and the CIEL controller daemon run on the same physical machine or dev server.
1. Prerequisites
- The CIEL controller daemon is active locally (
http://127.0.0.1:8137). - The
cielbinary is in your$PATH(/usr/local/bin/cielor~/.local/bin/ciel). - Ansible is installed locally for syntax checking (
ansible-core,ansible-lint).
2. Authentication
ciel mcp reads credentials from ~/.ciel/.env on the local machine:
# ~/.ciel/.env
CIEL_API_URL=http://127.0.0.1:8137
CIEL_USERNAME=admin
CIEL_PASSWORD=your_ciel_web_password3. Local Client Configuration
Claude Code CLI
claude mcp add ciel -- ciel mcpClaude Desktop (claude_desktop_config.json)
Location:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"ciel": {
"command": "ciel",
"args": ["mcp"],
"env": {
"CIEL_API_URL": "http://127.0.0.1:8137"
}
}
}
}Cursor (.cursor/mcp.json)
{
"mcpServers": {
"ciel": {
"command": "ciel",
"args": ["mcp"],
"env": {
"CIEL_API_URL": "http://127.0.0.1:8137"
}
}
}
}Hermes Agent (config.yaml)
mcp_servers:
ciel:
command: ciel
args: ["mcp"]
env:
CIEL_API_URL: "http://127.0.0.1:8137"6. Case 2: Remote VPS Controller + Local PC Agent
Use this setup when CIEL is deployed on a remote Linux VPS (managing staging or production fleets), while you work locally on your laptop or desktop using Claude Code, Cursor, or Hermes.
Pattern A: SSH Stdio Bridge (Zero Local Dependencies, Recommended)
You do not need to install Python, Ansible, or the ciel executable on your local computer.
Your local AI client spawns ssh as its child process. The SSH tunnel transparently pipes standard input and output between your local client and the remote ciel mcp process on the VPS.
1. How Credentials Work in Pattern A
- Local PC: Needs SSH key-based access to the VPS. No CIEL passwords are stored locally.
- Remote VPS: The
ciel mcpprocess runs locally on the VPS, talks tohttp://127.0.0.1:8137, and readsCIEL_USERNAMEandCIEL_PASSWORDdirectly from~/.ciel/.envon the VPS filesystem.
2. Configure Passwordless SSH
AI clients execute commands non-interactively. If SSH prompts for a password, the agent will hang. Verify that passwordless key-based login works:
# Test direct execution over SSH
ssh -C user@vps-ip "/usr/local/bin/ciel --version"If using a custom SSH key or port, configure ~/.ssh/config on your local PC:
Host ciel-vps
HostName 198.51.100.10
User root
Port 22
IdentityFile ~/.ssh/id_ed255193. Client Configuration (Pattern A - SSH Stdio Bridge)
Always specify the absolute path /usr/local/bin/ciel to ensure non-login SSH shells locate the binary.
Claude Code CLI
claude mcp add ciel -- ssh -C user@vps-ip /usr/local/bin/ciel mcpClaude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"ciel": {
"command": "ssh",
"args": ["-C", "user@vps-ip", "/usr/local/bin/ciel", "mcp"]
}
}
}Cursor (.cursor/mcp.json)
{
"mcpServers": {
"ciel": {
"command": "ssh",
"args": ["-C", "user@vps-ip", "/usr/local/bin/ciel", "mcp"]
}
}
}Hermes Agent (config.yaml)
mcp_servers:
ciel:
command: ssh
args: ["-C", "user@vps-ip", "/usr/local/bin/ciel", "mcp"]Pattern B: Local Binary with Remote REST API
Use this pattern if you already have the ciel binary and Ansible installed on your local machine, and want local syntax checking while sending controller commands to the remote VPS over HTTPS.
1. How Credentials Work in Pattern B
- Local PC: Stores your CIEL web dashboard credentials (
CIEL_USERNAMEandCIEL_PASSWORD). - Remote VPS: Must expose the CIEL API port (8137) or route it behind an HTTPS reverse proxy (NGINX or Caddy).
2. Local Environment Configuration
On your local machine, set ~/.ciel/.env:
# ~/.ciel/.env on your local PC
CIEL_API_URL=https://ciel.example.com
CIEL_USERNAME=admin
CIEL_PASSWORD=your_ciel_web_password3. Client Configuration (Pattern B - Local Binary with Remote API)
Claude Code CLI
claude mcp add ciel -- ciel mcp --api-url https://ciel.example.comClaude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"ciel": {
"command": "ciel",
"args": ["mcp", "--api-url", "https://ciel.example.com"],
"env": {
"CIEL_USERNAME": "admin",
"CIEL_PASSWORD": "your_ciel_web_password"
}
}
}
}Cursor (.cursor/mcp.json)
{
"mcpServers": {
"ciel": {
"command": "ciel",
"args": ["mcp", "--api-url", "https://ciel.example.com"],
"env": {
"CIEL_USERNAME": "admin",
"CIEL_PASSWORD": "your_ciel_web_password"
}
}
}
}Hermes Agent (config.yaml)
mcp_servers:
ciel:
command: ciel
args: ["mcp", "--api-url", "https://ciel.example.com"]
env:
CIEL_USERNAME: "admin"
CIEL_PASSWORD: "your_ciel_web_password"7. Case 3: Containerized Controller (Podman / Docker) + Host Agent
Use this setup when CIEL runs inside a local container (such as rootless Podman or Docker), while your AI agent runs directly on the host machine.
Because the ciel binary resides inside the container, configure your AI client to invoke podman exec -i or docker exec -i.
1. Container Prerequisites
Ensure the container runs with internal API credentials so ciel mcp can authenticate:
podman run -d \
--name ciel \
-p 8137:8137 \
-v ciel_data:/root/.ciel \
-e CIEL_API_URL=http://127.0.0.1:8137 \
-e CIEL_USERNAME=admin \
-e CIEL_PASSWORD=admin_password \
cielstack/ciel:latest2. Testing MCP via Inspector
Verify that the MCP server responds over stdio:
npx @modelcontextprotocol/inspector podman exec -i ciel ciel mcp3. Container Client Configuration (Podman / Docker)
Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"ciel": {
"command": "podman",
"args": ["exec", "-i", "ciel", "ciel", "mcp"]
}
}
}Hermes Agent (config.yaml)
mcp_servers:
ciel:
command: podman
args:
- exec
- -i
- ciel
- ciel
- mcpCursor (.cursor/mcp.json)
{
"mcpServers": {
"ciel": {
"command": "podman",
"args": ["exec", "-i", "ciel", "ciel", "mcp"]
}
}
}8. Walkthrough: Patching a Fleet with an AI Agent
Here is how a real workflow looks when patching an OpenSSH vulnerability across a server cluster:
- Find targets: The agent queries servers tagged
edge-proxy. It gets host names and IPs, but no credentials. - Validate YAML: The agent drafts an update playbook and tests the syntax locally.
- Preview diffs: The agent runs a dry-run with
check_mode: trueto generate package diffs. - Approve run: CIEL pauses the job. You review the diff in the web dashboard and click Approve.
- Apply update: CIEL connects over SSH in parallel, applies the patch, and streams the output to your screen.
9. External References
For upstream specifications and client setup guides:
- Model Context Protocol Specification: Official open standard for connecting AI models to development tools and data sources.
- Anthropic Claude Code MCP Integration: Running MCP tools within the Claude command line interface.
- Cursor MCP Documentation: Connecting external MCP servers to Cursor IDE.
- Ansible Core CLI Documentation: CLI options for playbook syntax checking and check-mode verification.