Automation & Integrations•6 min read•MCP

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.

Interactive Architecture Diagram(Mermaid)
Rendering diagram...

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:

  1. SSH keys stay encrypted: The AI agent only sees server names and tags (like edge-01 or web-fleet). Private keys remain in CIEL's encrypted vault.
  2. Playbooks are verified before running: The model can test its playbook locally using ansible-playbook --syntax-check and ansible-lint before touching any server.
  3. 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:

TierAccessDescriptionExamples
Tier 1: Read-OnlyAutomaticQuerying servers, inventory groups, and module documentation. Non-destructive.ciel_hosts_list_hosts, ansible_get_module_doc
Tier 2: Controlled WritesAutomaticSaving playbooks and validating syntax locally in a sandbox. Does not touch live servers.ciel_playbooks_create_playbook, ansible_validate_syntax
Tier 3: ExecutionGatedRunning 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.

json
{
  "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.

json
{
  "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:

  1. Stdio Transport: ciel mcp does 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 spawn ciel mcp as a subprocess and talk to it via pipes.
  2. Two Distinct Types of Credentials:
    • Linux VPS SSH Account: The system user and SSH key on your remote server (for example, root or ciel-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 by ciel mcp to obtain a JWT token from POST /api/auth/login.
Architecture PatternWhere AI Client RunsWhere ciel mcp RunsWhere CIEL Credentials Live
Case 1: All-in-OneLocal MachineLocal MachineLocal machine (~/.ciel/.env)
Case 2 - Pattern A (SSH Bridge)Local PCRemote VPSRemote VPS (~/.ciel/.env)
Case 2 - Pattern B (Local Binary)Local PCLocal PCLocal 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.

Interactive Architecture Diagram(Mermaid)
Rendering diagram...

1. Prerequisites

  • The CIEL controller daemon is active locally (http://127.0.0.1:8137).
  • The ciel binary is in your $PATH (/usr/local/bin/ciel or ~/.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:

ini
# ~/.ciel/.env
CIEL_API_URL=http://127.0.0.1:8137
CIEL_USERNAME=admin
CIEL_PASSWORD=your_ciel_web_password

3. Local Client Configuration

Claude Code CLI

Terminal(bash)
claude mcp add ciel -- ciel mcp

Claude 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
json
{
  "mcpServers": {
    "ciel": {
      "command": "ciel",
      "args": ["mcp"],
      "env": {
        "CIEL_API_URL": "http://127.0.0.1:8137"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

json
{
  "mcpServers": {
    "ciel": {
      "command": "ciel",
      "args": ["mcp"],
      "env": {
        "CIEL_API_URL": "http://127.0.0.1:8137"
      }
    }
  }
}

Hermes Agent (config.yaml)

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.

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.

Interactive Architecture Diagram(Mermaid)
Rendering diagram...

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 mcp process runs locally on the VPS, talks to http://127.0.0.1:8137, and reads CIEL_USERNAME and CIEL_PASSWORD directly from ~/.ciel/.env on 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:

Terminal(bash)
# 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:

text
Host ciel-vps
    HostName 198.51.100.10
    User root
    Port 22
    IdentityFile ~/.ssh/id_ed25519

3. 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
Terminal(bash)
claude mcp add ciel -- ssh -C user@vps-ip /usr/local/bin/ciel mcp
Claude Desktop (claude_desktop_config.json)
json
{
  "mcpServers": {
    "ciel": {
      "command": "ssh",
      "args": ["-C", "user@vps-ip", "/usr/local/bin/ciel", "mcp"]
    }
  }
}
Cursor (.cursor/mcp.json)
json
{
  "mcpServers": {
    "ciel": {
      "command": "ssh",
      "args": ["-C", "user@vps-ip", "/usr/local/bin/ciel", "mcp"]
    }
  }
}
Hermes Agent (config.yaml)
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.

Interactive Architecture Diagram(Mermaid)
Rendering diagram...

1. How Credentials Work in Pattern B

  • Local PC: Stores your CIEL web dashboard credentials (CIEL_USERNAME and CIEL_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:

ini
# ~/.ciel/.env on your local PC
CIEL_API_URL=https://ciel.example.com
CIEL_USERNAME=admin
CIEL_PASSWORD=your_ciel_web_password

3. Client Configuration (Pattern B - Local Binary with Remote API)

Claude Code CLI
Terminal(bash)
claude mcp add ciel -- ciel mcp --api-url https://ciel.example.com
Claude Desktop (claude_desktop_config.json)
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)
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)
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:

Terminal(bash)
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:latest

2. Testing MCP via Inspector

Verify that the MCP server responds over stdio:

Terminal(bash)
npx @modelcontextprotocol/inspector podman exec -i ciel ciel mcp

3. Container Client Configuration (Podman / Docker)

Claude Desktop (claude_desktop_config.json)

json
{
  "mcpServers": {
    "ciel": {
      "command": "podman",
      "args": ["exec", "-i", "ciel", "ciel", "mcp"]
    }
  }
}

Hermes Agent (config.yaml)

yaml
mcp_servers:
  ciel:
    command: podman
    args:
      - exec
      - -i
      - ciel
      - ciel
      - mcp

Cursor (.cursor/mcp.json)

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:

Interactive Architecture Diagram(Mermaid)
Rendering diagram...
  1. Find targets: The agent queries servers tagged edge-proxy. It gets host names and IPs, but no credentials.
  2. Validate YAML: The agent drafts an update playbook and tests the syntax locally.
  3. Preview diffs: The agent runs a dry-run with check_mode: true to generate package diffs.
  4. Approve run: CIEL pauses the job. You review the diff in the web dashboard and click Approve.
  5. 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: