{"id":50991457,"url":"https://github.com/itential/itential.mcp","last_synced_at":"2026-06-20T03:32:37.332Z","repository":{"id":363406307,"uuid":"1243751636","full_name":"itential/itential.mcp","owner":"itential","description":"Ansible collection for deploying and managing the Itential MCP Server","archived":false,"fork":false,"pushed_at":"2026-06-08T18:45:19.000Z","size":49,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"dev","last_synced_at":"2026-06-08T20:23:00.170Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itential.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-19T16:21:07.000Z","updated_at":"2026-06-08T17:40:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/itential/itential.mcp","commit_stats":null,"previous_names":["itential/itential.mcp"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/itential/itential.mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itential%2Fitential.mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itential%2Fitential.mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itential%2Fitential.mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itential%2Fitential.mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itential","download_url":"https://codeload.github.com/itential/itential.mcp/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itential%2Fitential.mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34556494,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-20T03:32:36.589Z","updated_at":"2026-06-20T03:32:37.319Z","avatar_url":"https://github.com/itential.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ansible Collection - itential.mcp\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Supported Configurations](#supported-configurations)\n    1. [Transport Modes](#transport-modes)\n    2. [Platform Authentication](#platform-authentication)\n    3. [TLS](#tls)\n3. [Prerequisites](#prerequisites)\n    1. [Control Node Requirements](#control-node-requirements)\n    2. [Target Server Requirements](#target-server-requirements)\n    3. [Network Requirements](#network-requirements)\n4. [Installing the Collection](#installing-the-collection)\n5. [Running the Collection](#running-the-collection)\n    1. [Verify Prerequisites](#verify-prerequisites)\n    2. [Create an Inventory](#create-an-inventory)\n    3. [Install and Configure](#install-and-configure)\n    4. [Certify the Installation](#certify-the-installation)\n6. [Inventory Variables Reference](#inventory-variables-reference)\n    1. [Package Installation](#package-installation)\n    2. [Server Configuration](#server-configuration)\n    3. [Platform Connection](#platform-connection)\n    4. [TLS](#tls-variables)\n    5. [Offline Installation](#offline-variables)\n7. [Example Inventories](#example-inventories)\n8. [Offline Installation](#offline-installation)\n9. [TLS Configuration](#tls-configuration)\n10. [High Availability Platform](#high-availability-platform)\n11. [Upgrading](#upgrading)\n\n---\n\n## Overview\n\nThe **Itential MCP Server** is a production-grade [Model Context Protocol](https://modelcontextprotocol.io)\nserver that bridges AI agents with the Itential Platform. It exposes 60+ tools across\ncategories including workflow execution, device configuration, compliance, lifecycle\nmanagement, and platform health — allowing AI assistants to interact with Itential\nPlatform through a standardized interface.\n\nThe `itential.mcp` collection installs and manages the Itential MCP Server as a\n`systemd` service on a Linux VM. It handles:\n\n- Installing Python 3.11 and creating a dedicated virtual environment\n- Installing the `itential-mcp` package and its dependencies\n- Creating a dedicated system user and configuring file permissions\n- Writing the server configuration and credentials files\n- Installing and enabling the `systemd` service\n- Verifying prerequisites before installation\n- Certifying the installation after deployment\n\n**\u0026#9432; Note:**\nThe collection targets VM deployments where multiple AI clients connect to a shared\nMCP server over the network. For single-user local installations (e.g., Claude Desktop\non a developer laptop), install `itential-mcp` directly with `pip` and configure your\nMCP client to run it as a local process.\n\n---\n\n## Supported Configurations\n\n### Transport Modes\n\n| Transport | Description | Use Case |\n|-----------|-------------|----------|\n| `sse` | Server-Sent Events over HTTP | Default. Widely supported by MCP clients. |\n| `http` | Streamable HTTP | Newer MCP transport standard. |\n\n**\u0026#9432; Note:** `stdio` transport is not supported by this role. It is incompatible\nwith `systemd` service management.\n\n### Platform Authentication\n\n| Method | Variables | Description |\n|--------|-----------|-------------|\n| Basic auth | `mcp_platform_user`, `mcp_platform_password` | Default. Username and password. |\n| OAuth | `mcp_platform_client_id`, `mcp_platform_client_secret` | Platform service account OAuth credentials. When both are set, basic auth variables are ignored. |\n\n### TLS\n\nThe role supports connecting to an Itential Platform that uses TLS (HTTPS).\n\n| Scenario | Variables |\n|----------|-----------|\n| Platform on HTTPS, public CA | `mcp_platform_tls: true`, `mcp_platform_port: 3443` |\n| Platform on HTTPS, private CA | Above plus `mcp_platform_ca_bundle: /etc/pki/tls/certs/ca-bundle.crt` |\n| Skip cert verification | `mcp_platform_tls: true`, `mcp_platform_disable_verify: true` |\n\n**\u0026#9432; Note:** The MCP server itself does not terminate TLS. If clients require\nHTTPS to connect to the MCP server, place a reverse proxy (nginx, HAProxy) in front\nof it.\n\n---\n\n## Prerequisites\n\n### Control Node Requirements\n\n| Component | Requirement |\n|-----------|-------------|\n| Ansible | \u003e= 2.14 |\n| Python | \u003e= 3.9 |\n\n### Target Server Requirements\n\n| Component | Requirement |\n|-----------|-------------|\n| OS | RHEL 8/9, Rocky 8/9, Oracle Linux 8/9, Amazon Linux 2023 |\n| Architecture | x86_64, aarch64 |\n| RAM | 1 GB minimum |\n| Disk | 2 GB free in `/opt` |\n| systemd | Required |\n| Privilege escalation | `sudo` access required (`become: true`) |\n\n**\u0026#9432; Note:** On Amazon Linux 2023, `python3.11-pip` must be added to\n`mcp_python_packages` in addition to `python3.11`. See [Example Inventories](#example-inventories).\n\n### Network Requirements\n\nThe target server must be able to reach:\n\n| Destination | Port | Protocol | Required For |\n|-------------|------|----------|--------------|\n| `pypi.org` | 443 | TCP | Installing `itential-mcp` (online installs only) |\n| Itential Platform host | 3000 or 3443 | TCP | Connecting to the Platform API |\n\nMCP clients must be able to reach the target server on `mcp_port` (default: 8000).\n\n---\n\n## Installing the Collection\n\nInstall from Ansible Galaxy:\n\n```bash\nansible-galaxy collection install itential.mcp\n```\n\nTo install a specific version:\n\n```bash\nansible-galaxy collection install itential.mcp:==0.1.0\n```\n\n---\n\n## Running the Collection\n\n### Verify Prerequisites\n\nRun the verify playbook against your target server before installing. It checks\nthat Python 3.11 is available, the Platform host is reachable, and the MCP port\nis not already in use.\n\n```bash\nansible-playbook itential.mcp.verify_mcp -i your_inventory.yaml\n```\n\n### Create an Inventory\n\nCopy one of the [example inventories](#example-inventories) and fill in the\nrequired values:\n\n- `mcp_platform_host` — hostname or IP of your Itential Platform\n- `mcp_platform_user` / `mcp_platform_password` — Platform credentials (or OAuth equivalent)\n\n### Install and Configure\n\n```bash\nansible-playbook itential.mcp.mcp -i your_inventory.yaml\n```\n\nThe playbook will:\n1. Validate all variables\n2. Install `python3.11` via `dnf`\n3. Create a Python virtual environment at `/opt/itential-mcp/venv`\n4. Install `itential-mcp` and its dependencies\n5. Create the `itential-mcp` system user and group\n6. Write `/etc/itential-mcp/mcp.conf` and `/etc/itential-mcp/itential-mcp.env`\n7. Install and enable the `itential-mcp` systemd service\n8. Assert the service is running before completing\n\n### Certify the Installation\n\nAfter a successful install, run the certify playbook to validate the deployment\nand generate a markdown report on the control node.\n\n```bash\nansible-playbook itential.mcp.certify_mcp -i your_inventory.yaml\n```\n\nThe certify playbook checks:\n\n- Service active state and enabled status\n- Process running\n- Port listening\n- Config and credential file presence and permissions\n- Installed version\n- Available tool count\n- Health endpoint (`/status/healthz`) — server liveness\n- Readiness endpoint (`/status/readyz`) — live Platform connectivity\n\nThe markdown report is written to:\n```\n\u003cplaybook_dir\u003e/certify-reports/mcp-certify-\u003chostname\u003e.md\n```\n\n---\n\n## Inventory Variables Reference\n\nAll variables have defaults and can be overridden in your inventory.\n\n### Package Installation\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `mcp_version` | `latest` | Package version. Use `latest` for the newest PyPI release or pin to a specific version (e.g., `0.12.1`). Must be a pinned version for offline installs. |\n| `mcp_python_executable` | `/usr/bin/python3.11` | Python executable used to create the virtual environment. |\n| `mcp_python_packages` | `[python3.11]` | OS packages installed before creating the virtual environment. Add `python3.11-pip` for Amazon Linux 2023. |\n| `mcp_install_dir` | `/opt/itential-mcp` | Root installation directory. |\n| `mcp_venv_dir` | `/opt/itential-mcp/venv` | Python virtual environment path. |\n\n### Server Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `mcp_transport` | `sse` | Transport protocol. Valid values: `sse`, `http`. |\n| `mcp_host` | `0.0.0.0` | IP address the server listens on. |\n| `mcp_port` | `8000` | Port the server listens on. |\n| `mcp_log_level` | `INFO` | Log verbosity. Valid values: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`, `NONE`. |\n| `mcp_response_format` | `json` | Response serialization format. Valid values: `json`, `toon`. |\n| `mcp_include_tags` | `\"\"` | Comma-separated list of tool tags to include. Empty includes all tools. |\n| `mcp_exclude_tags` | `experimental,beta` | Comma-separated list of tool tags to exclude. |\n| `mcp_keepalive_interval` | `300` | Seconds between keepalive requests to the Platform. Set to `0` to disable. |\n| `mcp_conf_dir` | `/etc/itential-mcp` | Directory for configuration files. |\n| `mcp_log_dir` | `/var/log/itential-mcp` | Directory for log files. |\n| `mcp_owner` | `itential-mcp` | System user the service runs as. |\n| `mcp_group` | `itential-mcp` | System group the service runs as. |\n\n### Platform Connection\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `mcp_platform_host` | `localhost` | Hostname or IP of the Itential Platform server. |\n| `mcp_platform_port` | `3000` | Platform API port. Default `3000` (HTTP). Use `3443` for HTTPS. |\n| `mcp_platform_user` | `admin` | Username for basic authentication. Ignored when OAuth credentials are set. |\n| `mcp_platform_password` | `admin` | Password for basic authentication. |\n| `mcp_platform_client_id` | `\"\"` | OAuth client ID. When set, OAuth is used instead of basic auth. |\n| `mcp_platform_client_secret` | `\"\"` | OAuth client secret. |\n| `mcp_platform_timeout` | `30` | Request timeout in seconds. |\n\n**\u0026#9432; Note:** All credentials are written to `/etc/itential-mcp/itential-mcp.env`\nwith mode `0600`. They are never written to `mcp.conf`. Using Ansible Vault for\ncredential values is strongly recommended.\n\n### TLS Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `mcp_platform_tls` | `false` | Set to `true` when the Platform API is served over HTTPS. |\n| `mcp_platform_disable_verify` | `false` | Set to `true` to skip TLS certificate verification. Use only in development environments. |\n| `mcp_platform_ca_bundle` | `\"\"` | Path to a CA certificate bundle on the MCP server. Required when the Platform uses a certificate signed by a private CA. See [TLS Configuration](#tls-configuration). |\n\n### Offline Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `offline_install_enabled` | `false` | Set to `true` to install from a pre-staged package bundle instead of PyPI. |\n| `offline_target_node_root` | `/var/tmp` | Directory on the target server where the package bundle is staged. |\n| `offline_control_node_root` | `{{ playbook_dir }}/files` | Directory on the control node containing the `itential-mcp-packages/` bundle. |\n\n### Certify Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `mcp_certify_report_dir_remote` | `/tmp/itential-mcp-certify` | Directory on the target server where the report is generated. |\n| `mcp_certify_report_dir_local` | `{{ playbook_dir }}/certify-reports` | Directory on the control node where the report is fetched. |\n\n---\n\n## Example Inventories\n\nThree example inventories are provided in `example_inventories/mcp/`:\n\n| File | Use Case |\n|------|----------|\n| `mcp_default_passwords.yaml` | Standard install with minimum required variables |\n| `mcp_override_default_passwords.yaml` | All variables explicitly set |\n| `mcp_offline.yaml` | Air-gapped / offline install |\n\n---\n\n## Offline Installation\n\nFor environments without internet access, pre-stage the package bundle on a\nLinux host matching the target OS and Python version before running the playbook.\n\n**\u0026#9432; Important:** Run `pip download` on a Linux host, not macOS or Windows.\nmacOS does not resolve Linux-specific conditional dependencies correctly, resulting\nin an incomplete bundle.\n\nStage the bundle on a Linux host with internet access:\n\n```bash\npip download 'itential-mcp==0.12.1' 'fastmcp\u003e=3.0,\u003c3.3' \\\n  -d /path/to/playbook/files/itential-mcp-packages/\n```\n\nThen set the following in your inventory:\n\n```yaml\noffline_install_enabled: true\nmcp_version: \"0.12.1\"\noffline_control_node_root: /path/to/playbook/files\n```\n\nRun the install playbook as normal. The role copies the bundle to the target\nserver and installs from it using `--no-index`.\n\n---\n\n## TLS Configuration\n\nWhen connecting to an Itential Platform that uses HTTPS, configure the following:\n\n### Platform with a Public CA Certificate\n\n```yaml\nmcp_platform_tls: true\nmcp_platform_port: 3443\n```\n\nNo additional steps required. The server's Python trust store (certifi) trusts\npublic certificate authorities by default.\n\n### Platform with a Private CA Certificate\n\nThe MCP server's Python HTTP client uses `certifi` for certificate validation, not\nthe OS trust store. After installing the CA cert to the OS, the CA bundle path must\nbe provided so Python uses it.\n\n1. Copy the CA certificate to the MCP server:\n\n```bash\nscp ca.crt user@mcp-server:/tmp/itential-ca.crt\nssh user@mcp-server \"sudo cp /tmp/itential-ca.crt /etc/pki/ca-trust/source/anchors/itential-ca.crt \u0026\u0026 sudo update-ca-trust\"\n```\n\n2. Set the following in your inventory:\n\n```yaml\nmcp_platform_tls: true\nmcp_platform_port: 3443\nmcp_platform_ca_bundle: /etc/pki/tls/certs/ca-bundle.crt\n```\n\nThe role writes `SSL_CERT_FILE={{ mcp_platform_ca_bundle }}` to the service\nenvironment file, directing Python to use the system CA bundle which now includes\nyour private CA.\n\n---\n\n## High Availability Platform\n\nThe MCP server connects to a single `mcp_platform_host`. In a Platform HA\ndeployment, point `mcp_platform_host` at the load balancer VIP or hostname. The\nload balancer handles failover — no additional role configuration is required.\n\n```yaml\nmcp_platform_host: platform-lb.example.com\nmcp_platform_port: 3443\nmcp_platform_tls: true\n```\n\n---\n\n## Upgrading\n\nTo upgrade the `itential-mcp` package to the latest version, change\n`mcp_version: latest` in your inventory and re-run the install playbook:\n\n```bash\nansible-playbook itential.mcp.mcp -i your_inventory.yaml\n```\n\nThe role detects the installed version, upgrades the package if a newer version\nis available, and restarts the service. Run the certify playbook afterward to\nconfirm the upgrade was successful.\n\nTo pin to a specific version, set `mcp_version: \"0.12.1\"`. The role will\ninstall that exact version and leave it unchanged on subsequent runs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitential%2Fitential.mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitential%2Fitential.mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitential%2Fitential.mcp/lists"}