<div align="left">
[](https://badge.fury.io/py/itential-mcp)
[](https://www.python.org/downloads/)
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://github.com/itential/itential-mcp)
[](https://github.com/itential/itential-mcp)
</div>
# 🔌 Itential - MCP Server
A Model Context Protocol _(MCP)_ server that provides comprehensive tools for connecting LLMs to Itential Platform. Enable AI assistants to manage network automations, orchestrate workflows, monitor platform health, and perform advanced network operations.
## 🎯 Who This Is For
### **Platform Engineers**
Manage infrastructure, monitor system health, configure devices, and orchestrate network operations through AI-powered automation.
### **Developers**
Build automation workflows, integrate with external systems, manage application lifecycles, and extend platform capabilities.
## 📒 Key Features
### **Core Capabilities**
- **Advanced Tool Selection**: Filter and control available tools using flexible tagging system with 10+ tag groups
- **Multiple Transport Methods**: stdio, SSE, and HTTP transports for different deployment scenarios
- **Dynamic Tool Discovery**: Automatically discovers and registers tools without code modifications
- **Flexible Authentication**: Supports both basic authentication and OAuth 2.0 for Itential Platform
- **Comprehensive Configuration**: CLI parameters, environment variables, or configuration files
- **Role-Based Access**: Tailored tool configurations for Platform SREs, Builders, Developers, and Operators
### **Network Automation & Device Management**
- **Device Configuration**: Apply configurations, backup device settings, and retrieve current configurations
- **Command Execution**: Run single commands or command templates across multiple devices with rule validation
- **Device Groups**: Create and manage logical device collections for streamlined operations
- **Compliance Management**: Automated compliance plan execution and detailed reporting
- **Golden Configuration**: Hierarchical template-based configuration management with version control
### **Workflow & Orchestration**
- **Workflow Execution**: Start workflows via API endpoints and monitor execution status
- **Job Management**: Track workflow jobs with comprehensive status, metrics, and task details
- **Workflow Exposure**: Convert workflows into REST API endpoints for external consumption
- **Template Management**: Create, update, and execute Jinja2 and TextFSM templates
- **Performance Metrics**: Detailed job and task execution metrics for workflow optimization
### **Platform Operations & Monitoring**
- **Health Monitoring**: Real-time platform health including system resources, applications, and adapters
- **Component Lifecycle**: Start, stop, and restart applications and adapters with status monitoring
- **Integration Management**: Create and manage OpenAPI-based integration models
- **Gateway Services**: Execute external services (Ansible, Python scripts, OpenTofu) through Gateway Manager
### **Lifecycle & Resource Management**
- **Resource Models**: Define JSON Schema-based resource structures with lifecycle workflows
- **Instance Management**: Full CRUD operations on resource instances with state tracking
- **Action Execution**: Run lifecycle actions with comprehensive execution history
- **Data Validation**: Schema-based validation for resource data and action parameters
## 🔍 Requirements
- Python _3.10_ or higher
- Access to an [Itential Platform Instance](https://www.itential.com/)
- For _development_ - `uv` and `make`
### Tested Python Versions
This project is automatically tested against the following Python versions:
- Python 3.10
- Python 3.11
- Python 3.12
- Python 3.13
## 🔧 Installation
The `itential-mcp` application can be installed using either PyPI or it can be
run directly from source.
### PyPI Installation
To install it from PyPI, simply use `pip`:
```bash
pip install itential-mcp
```
### Local Development
The repository can also be clone the repository to your local environment to
work with the MCP server. The project uses `uv` and `make` so both tools
would need to be installed and available in your environment.
The following commands can be used to get started.
```bash
git clone https://github.com/itential/itential-mcp
cd itential-mcp
make build
```
For development, you can run the server directly using `uv`:
```bash
# Run with stdio transport (default)
uv run itential-mcp run
# Run with SSE transport
uv run itential-mcp run --transport sse --host 0.0.0.0 --port 8000
# Run with specific configuration
uv run itential-mcp run --include-tags "system,devices" --exclude-tags "experimental"
```
### Container Usage
#### Pull from GitHub Container Registry
Pull and run the latest release:
```bash
# Pull the latest image
docker pull ghcr.io/itential/itential-mcp:latest
# Run with SSE transport
docker run -p 8000:8000 \
--env ITENTIAL_MCP_SERVER_TRANSPORT=sse \
--env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \
--env ITENTIAL_MCP_SERVER_PORT=8000 \
--env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \
--env ITENTIAL_MCP_PLATFORM_USER=your-username \
--env ITENTIAL_MCP_PLATFORM_PASSWORD=your-password \
ghcr.io/itential/itential-mcp:latest
# Or with OAuth authentication
docker run -p 8000:8000 \
--env ITENTIAL_MCP_SERVER_TRANSPORT=sse \
--env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \
--env ITENTIAL_MCP_SERVER_PORT=8000 \
--env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \
--env ITENTIAL_MCP_PLATFORM_CLIENT_ID=CLIENT_ID \
--env ITENTIAL_MCP_PLATFORM_CLIENT_SECRET=CLIENT_SECRET \
ghcr.io/itential/itential-mcp:latest
# Run with stdio transport (for MCP clients)
docker run -i \
--env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \
--env ITENTIAL_MCP_PLATFORM_USER=your-username \
--env ITENTIAL_MCP_PLATFORM_PASSWORD=your-password \
ghcr.io/itential/itential-mcp:latest
```
#### Build Container Image Locally
Build and run from source:
```bash
# Build the container image
make container
# Run the locally built container
docker run -p 8000:8000 \
--env ITENTIAL_MCP_SERVER_TRANSPORT=sse \
--env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \
--env ITENTIAL_MCP_SERVER_PORT=8000 \
--env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \
--env ITENTIAL_MCP_PLATFORM_USER=your-username \
--env ITENTIAL_MCP_PLATFORM_PASSWORD=your-password \
itential-mcp:devel
```
## 🚀 Quick Start
### **1. Install the Server**
```bash
pip install itential-mcp
```
### **2. Configure Platform Connection**
Set your Itential Platform credentials:
```bash
export ITENTIAL_MCP_PLATFORM_HOST="your-platform.example.com"
export ITENTIAL_MCP_PLATFORM_USER="your-username"
export ITENTIAL_MCP_PLATFORM_PASSWORD="your-password"
```
### **3. Start the Server**
```bash
# Basic stdio transport (default)
itential-mcp run
# Or with SSE transport for web clients
itential-mcp run --transport sse --host 0.0.0.0 --port 8000
```
### **4. Configure Your MCP Client**
Follow the [integration guide](docs/integration.md) to connect Claude, Continue.dev, or other MCP clients.
## 📝 Basic Usage
Start the MCP server with default settings _(stdio transport)_:
```bash
itential-mcp run
```
Start with SSE transport:
```bash
itential-mcp run --transport sse --host 0.0.0.0 --port 8000
```
### General Options
| Option | Description | Default |
|------------|-------------------------|---------|
| `--config` | Path to the config file | none |
### Server Options
| Option | Description | Default |
|------------------|---------------------------------------------------|-------------------|
| `--transport` | Transport protocol (stdio, sse, http) | stdio |
| `--host` | Host address to listen on | localhost |
| `--port` | Port to listen on | 8000 |
| `--path` | The streamable HTTP path to use | /mcp |
| `--log-level` | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | INFO |
| `--include-tags` | Tags to include registered tools | none |
| `--exclude-tags` | Tags to exclude registered tools | experimental,beta |
### Platform Configuration
| Option | Description | Default |
|-----------------------------|-------------------------------------|-----------|
| `--platform-host` | Itential Platform hostname | localhost |
| `--platform-port` | Platform port (0 = auto-detect) | 0 |
| `--platform-disable-tls` | Disable TLS for platform connection | false |
| `--platform-disable-verify` | Disable certificate verification | false |
| `--platform-timeout` | Connection timeout | 30 |
| `--platform-user` | Username for authentication | admin |
| `--platform-password` | Password for authentication | admin |
| `--platform-client-id` | OAuth client ID | none |
| `--platform-client-secret` | OAuth client secret | none |
### Environment Variables
All command line options can also be set using environment variables prefixed with `ITENTIAL_MCP_SERVER_`. For example:
```bash
export ITENTIAL_MCP_SERVER_TRANSPORT=sse
export ITENTIAL_MCP_PLATFORM_HOST=platform.example.com
itential-mcp run # Will use the environment variables
```
### Configuration file
The server configuration can also be specified using a configuration file. The
configuration file can be used to pass in all the configuration parameters. To
use a configuration file, simply pass in the `--config <path>` command line
argument where `<path>` points to the configuration file to load.
The format and values for the configuration file are documented
[here](docs/mcp.conf.example)
When configuration options are specified in multiple places the following
precedence for determinting the value to be used will be honored from highest
to lowest:
1. Environment variable
2. Command line option
3. Configuration file
4. Default value
## 🎛️ Tool Selection & Tagging
The Itential MCP server provides powerful tool filtering capabilities through a comprehensive tagging system. This allows you to customize which tools are available based on your specific needs and security requirements.
### **Tag-Based Filtering**
Control tool availability using include and exclude tags:
```bash
# Include only system and device management tools
itential-mcp run --include-tags "system,configuration_manager,devices"
# Exclude experimental and beta tools (default behavior)
itential-mcp run --exclude-tags "experimental,beta,lifecycle_manager"
```
### **Available Tag Groups**
| Tag Group | Description | Use Case |
|-----------|-------------|----------|
| `system` | Platform health and monitoring | Platform administrators |
| `configuration_manager` | Device and compliance management | Network engineers |
| `devices` | Device-specific operations | NOC teams |
| `operations_manager` | Workflow and job management | Automation developers |
| `adapters` | Adapter lifecycle management | Integration specialists |
| `applications` | Application lifecycle management | Application owners |
| `automation_studio` | Command templates and automation | Network operators |
| `gateway_manager` | External service management | System integrators |
| `integrations` | External system integrations | API developers |
| `lifecycle_manager` | Stateful product CRUD operations and state tracking | Product managers |
| `workflow_engine` | Workflow execution metrics | Performance analysts |
### **Role-Based Configurations**
The following role-based configurations provide tailored tool access based on specific job functions and responsibilities:
**Platform SRE:**
*Use Cases: Platform & application administration, Adapter management, Integration management, Troubleshooting, Platform overall health and functionality*
```bash
itential-mcp run --include-tags "system,adapters,applications,integrations"
```
*Available Tools: get_health, restart_application, start_application, stop_application, create_integration_model, get_job_metrics, get_task_metrics, restart_adapter, start_adapter, stop_adapter, get_task_metrics_for_app, get_task_metrics_for_task, get_task_metrics_for_workflow*
**Platform Builder:**
*Use Cases: Asset development, Asset promotion, Workflow metrics analysis, Resource lifecycle management*
```bash
itential-mcp run --include-tags "operations_manager,automation_studio,configuration_manager,workflow_engine,lifecycle_manager"
```
*Available Tools: create_resource, get_workflows, describe_command_template, run_command_template, run_command, render_template, create_device_group, get_resources, describe_resource, get_instances, backup_device_configuration, apply_device_configuration, get_compliance_plans, run_compliance_plan, get_adapters, get_applications, get_integration_models, get_job_metrics, get_job_metrics_for_workflow, get_task_metrics, get_task_metrics_for_workflow, get_task_metrics_for_app, get_task_metrics_for_task, describe_instance, run_action*
**Automation Developer:**
*Use Cases: Asset development, Asset promotion, External service management*
```bash
itential-mcp run --include-tags "operations_manager,gateway_manager"
```
*Available Tools: create_resource, get_services, get_gateways, run_service*
**Platform Operator:**
*Use Cases: Execute jobs, Run compliance, Consume data*
```bash
itential-mcp run --include-tags "operations_manager,devices,configuration_manager,automation_studio"
```
*Available Tools: get_workflows, start_workflow, get_jobs, describe_job, get_devices, get_device_configuration, get_device_groups, get_command_templates, run_command_template, describe_compliance_report*
## 📚 Documentation & Integration
### **Complete Tool Reference**
The entire list of available tools can be found in the [tools documentation](docs/tools.md) along with detailed tag associations.
### **Client Integration Guides**
- [MCP Client Integration](docs/integration.md) - Configure Claude, Continue.dev, and other MCP clients
- [Configuration Examples](docs/mcp.conf.example) - Complete configuration file reference
- [Tagging System](docs/tags.md) - Advanced tagging and filtering guide
- [Workflow Execution](docs/exposing-workflows.md) - Running automation workflows
### **Example Prompts**
- [Claude Desktop Prompt](docs/claude-example.prompt) - Optimized prompt for Claude integration
- [GPT Integration Prompt](docs/gpt-example.prompt) - Optimized prompt for GPT integration
## 💡 Available Tools
The entire list of available tools can be found in the [tools](docs/tools.md)
file along with the tag groups associated with those tools.
## 🛠️ Adding new Tools
Adding a new tool is simple:
1. Create a new Python file in the `src/itential_mcp/tools/` directory or add a function to an existing file
2. Define an async function with a `Context` parameter annotation:
```python
from fastmcp import Context
async def my_new_tool(ctx: Context) -> dict:
"""
Description of what the tool does
Args:
ctx (Context): The FastMCP Context object
Returns:
dict: The response data
Raises:
None
"""
# Get the platform client
client = ctx.request_context.lifespan_context.get("client")
# Make API requests
res = await client.get("/your/api/path")
# Return JSON-serializable results
return res.json()
```
Tools are automatically discovered and registered when the server starts.
### Running Tests
Run the test suite with:
```bash
make test
```
For test coverage information:
```bash
make coverage
```
## Contributing
Contributions are welcome! Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Commit your changes: `git commit -am 'Add new feature'`
4. Push to the branch: `git push origin feature/my-feature`
5. Submit a pull request
Before submitting:
- Run `make premerge` to ensure tests pass and code style is correct
- Add documentation for new features
- Add tests for new functionality
## License
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
Copyright (c) 2025 Itential, Inc
Raw data
{
"_id": null,
"home_page": null,
"name": "itential-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "agent, fastmcp, llm, mcp, mcp client, mcp server, model context protocol",
"author": null,
"author_email": "Itential <opensource@itential.com>",
"download_url": "https://files.pythonhosted.org/packages/1f/f5/d06524b0be7204492c6160af06ed0854183a18ec9b5e8411b085f737636b/itential_mcp-0.8.0.tar.gz",
"platform": null,
"description": "<div align=\"left\">\n\n[](https://badge.fury.io/py/itential-mcp)\n[](https://www.python.org/downloads/)\n[](https://www.gnu.org/licenses/gpl-3.0)\n[](https://github.com/itential/itential-mcp)\n[](https://github.com/itential/itential-mcp)\n\n</div>\n\n# \ud83d\udd0c Itential - MCP Server\n\nA Model Context Protocol _(MCP)_ server that provides comprehensive tools for connecting LLMs to Itential Platform. Enable AI assistants to manage network automations, orchestrate workflows, monitor platform health, and perform advanced network operations.\n\n## \ud83c\udfaf Who This Is For\n\n### **Platform Engineers**\nManage infrastructure, monitor system health, configure devices, and orchestrate network operations through AI-powered automation.\n\n### **Developers**\nBuild automation workflows, integrate with external systems, manage application lifecycles, and extend platform capabilities.\n\n## \ud83d\udcd2 Key Features\n\n### **Core Capabilities**\n- **Advanced Tool Selection**: Filter and control available tools using flexible tagging system with 10+ tag groups\n- **Multiple Transport Methods**: stdio, SSE, and HTTP transports for different deployment scenarios\n- **Dynamic Tool Discovery**: Automatically discovers and registers tools without code modifications\n- **Flexible Authentication**: Supports both basic authentication and OAuth 2.0 for Itential Platform\n- **Comprehensive Configuration**: CLI parameters, environment variables, or configuration files\n- **Role-Based Access**: Tailored tool configurations for Platform SREs, Builders, Developers, and Operators\n\n### **Network Automation & Device Management**\n- **Device Configuration**: Apply configurations, backup device settings, and retrieve current configurations\n- **Command Execution**: Run single commands or command templates across multiple devices with rule validation\n- **Device Groups**: Create and manage logical device collections for streamlined operations\n- **Compliance Management**: Automated compliance plan execution and detailed reporting\n- **Golden Configuration**: Hierarchical template-based configuration management with version control\n\n### **Workflow & Orchestration**\n- **Workflow Execution**: Start workflows via API endpoints and monitor execution status\n- **Job Management**: Track workflow jobs with comprehensive status, metrics, and task details\n- **Workflow Exposure**: Convert workflows into REST API endpoints for external consumption\n- **Template Management**: Create, update, and execute Jinja2 and TextFSM templates\n- **Performance Metrics**: Detailed job and task execution metrics for workflow optimization\n\n### **Platform Operations & Monitoring**\n- **Health Monitoring**: Real-time platform health including system resources, applications, and adapters\n- **Component Lifecycle**: Start, stop, and restart applications and adapters with status monitoring\n- **Integration Management**: Create and manage OpenAPI-based integration models\n- **Gateway Services**: Execute external services (Ansible, Python scripts, OpenTofu) through Gateway Manager\n\n### **Lifecycle & Resource Management**\n- **Resource Models**: Define JSON Schema-based resource structures with lifecycle workflows\n- **Instance Management**: Full CRUD operations on resource instances with state tracking\n- **Action Execution**: Run lifecycle actions with comprehensive execution history\n- **Data Validation**: Schema-based validation for resource data and action parameters\n\n## \ud83d\udd0d Requirements\n- Python _3.10_ or higher\n- Access to an [Itential Platform Instance](https://www.itential.com/)\n- For _development_ - `uv` and `make`\n\n### Tested Python Versions\nThis project is automatically tested against the following Python versions:\n- Python 3.10\n- Python 3.11\n- Python 3.12\n- Python 3.13\n\n## \ud83d\udd27 Installation\nThe `itential-mcp` application can be installed using either PyPI or it can be\nrun directly from source.\n\n### PyPI Installation\nTo install it from PyPI, simply use `pip`:\n\n```bash\npip install itential-mcp\n```\n\n### Local Development\nThe repository can also be clone the repository to your local environment to\nwork with the MCP server. The project uses `uv` and `make` so both tools\nwould need to be installed and available in your environment.\n\nThe following commands can be used to get started.\n\n```bash\ngit clone https://github.com/itential/itential-mcp\ncd itential-mcp\nmake build\n```\n\nFor development, you can run the server directly using `uv`:\n\n```bash\n# Run with stdio transport (default)\nuv run itential-mcp run\n\n# Run with SSE transport\nuv run itential-mcp run --transport sse --host 0.0.0.0 --port 8000\n\n# Run with specific configuration\nuv run itential-mcp run --include-tags \"system,devices\" --exclude-tags \"experimental\"\n```\n\n### Container Usage\n\n#### Pull from GitHub Container Registry\nPull and run the latest release:\n\n```bash\n# Pull the latest image\ndocker pull ghcr.io/itential/itential-mcp:latest\n\n# Run with SSE transport\ndocker run -p 8000:8000 \\\n --env ITENTIAL_MCP_SERVER_TRANSPORT=sse \\\n --env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \\\n --env ITENTIAL_MCP_SERVER_PORT=8000 \\\n --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \\\n --env ITENTIAL_MCP_PLATFORM_USER=your-username \\\n --env ITENTIAL_MCP_PLATFORM_PASSWORD=your-password \\\n ghcr.io/itential/itential-mcp:latest\n\n# Or with OAuth authentication\ndocker run -p 8000:8000 \\\n --env ITENTIAL_MCP_SERVER_TRANSPORT=sse \\\n --env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \\\n --env ITENTIAL_MCP_SERVER_PORT=8000 \\\n --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \\\n --env ITENTIAL_MCP_PLATFORM_CLIENT_ID=CLIENT_ID \\\n --env ITENTIAL_MCP_PLATFORM_CLIENT_SECRET=CLIENT_SECRET \\\n ghcr.io/itential/itential-mcp:latest\n\n# Run with stdio transport (for MCP clients)\ndocker run -i \\\n --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \\\n --env ITENTIAL_MCP_PLATFORM_USER=your-username \\\n --env ITENTIAL_MCP_PLATFORM_PASSWORD=your-password \\\n ghcr.io/itential/itential-mcp:latest\n```\n\n#### Build Container Image Locally\nBuild and run from source:\n\n```bash\n# Build the container image\nmake container\n\n# Run the locally built container\ndocker run -p 8000:8000 \\\n --env ITENTIAL_MCP_SERVER_TRANSPORT=sse \\\n --env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \\\n --env ITENTIAL_MCP_SERVER_PORT=8000 \\\n --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \\\n --env ITENTIAL_MCP_PLATFORM_USER=your-username \\\n --env ITENTIAL_MCP_PLATFORM_PASSWORD=your-password \\\n itential-mcp:devel\n```\n\n## \ud83d\ude80 Quick Start\n\n### **1. Install the Server**\n```bash\npip install itential-mcp\n```\n\n### **2. Configure Platform Connection**\nSet your Itential Platform credentials:\n\n```bash\nexport ITENTIAL_MCP_PLATFORM_HOST=\"your-platform.example.com\"\nexport ITENTIAL_MCP_PLATFORM_USER=\"your-username\"\nexport ITENTIAL_MCP_PLATFORM_PASSWORD=\"your-password\"\n```\n\n### **3. Start the Server**\n```bash\n# Basic stdio transport (default)\nitential-mcp run\n\n# Or with SSE transport for web clients\nitential-mcp run --transport sse --host 0.0.0.0 --port 8000\n```\n\n### **4. Configure Your MCP Client**\nFollow the [integration guide](docs/integration.md) to connect Claude, Continue.dev, or other MCP clients.\n\n## \ud83d\udcdd Basic Usage\nStart the MCP server with default settings _(stdio transport)_:\n\n```bash\nitential-mcp run\n```\n\nStart with SSE transport:\n\n```bash\nitential-mcp run --transport sse --host 0.0.0.0 --port 8000\n```\n\n### General Options\n\n| Option | Description | Default |\n|------------|-------------------------|---------|\n| `--config` | Path to the config file | none |\n\n### Server Options\n\n | Option | Description | Default |\n |------------------|---------------------------------------------------|-------------------|\n | `--transport` | Transport protocol (stdio, sse, http) | stdio |\n | `--host` | Host address to listen on | localhost |\n | `--port` | Port to listen on | 8000 |\n | `--path` | The streamable HTTP path to use | /mcp |\n | `--log-level` | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | INFO |\n | `--include-tags` | Tags to include registered tools | none |\n | `--exclude-tags` | Tags to exclude registered tools | experimental,beta |\n\n### Platform Configuration\n\n| Option | Description | Default |\n|-----------------------------|-------------------------------------|-----------|\n| `--platform-host` | Itential Platform hostname | localhost |\n| `--platform-port` | Platform port (0 = auto-detect) | 0 |\n| `--platform-disable-tls` | Disable TLS for platform connection | false |\n| `--platform-disable-verify` | Disable certificate verification | false |\n| `--platform-timeout` | Connection timeout | 30 |\n| `--platform-user` | Username for authentication | admin |\n| `--platform-password` | Password for authentication | admin |\n| `--platform-client-id` | OAuth client ID | none |\n| `--platform-client-secret` | OAuth client secret | none |\n\n### Environment Variables\n\nAll command line options can also be set using environment variables prefixed with `ITENTIAL_MCP_SERVER_`. For example:\n\n```bash\nexport ITENTIAL_MCP_SERVER_TRANSPORT=sse\nexport ITENTIAL_MCP_PLATFORM_HOST=platform.example.com\nitential-mcp run # Will use the environment variables\n```\n\n### Configuration file\n\nThe server configuration can also be specified using a configuration file. The\nconfiguration file can be used to pass in all the configuration parameters. To\nuse a configuration file, simply pass in the `--config <path>` command line\nargument where `<path>` points to the configuration file to load.\n\nThe format and values for the configuration file are documented\n[here](docs/mcp.conf.example)\n\nWhen configuration options are specified in multiple places the following\nprecedence for determinting the value to be used will be honored from highest\nto lowest:\n\n1. Environment variable\n2. Command line option\n3. Configuration file\n4. Default value\n\n\n## \ud83c\udf9b\ufe0f Tool Selection & Tagging\n\nThe Itential MCP server provides powerful tool filtering capabilities through a comprehensive tagging system. This allows you to customize which tools are available based on your specific needs and security requirements.\n\n### **Tag-Based Filtering**\n\nControl tool availability using include and exclude tags:\n\n```bash\n# Include only system and device management tools\nitential-mcp run --include-tags \"system,configuration_manager,devices\"\n\n# Exclude experimental and beta tools (default behavior)\nitential-mcp run --exclude-tags \"experimental,beta,lifecycle_manager\"\n```\n\n### **Available Tag Groups**\n\n| Tag Group | Description | Use Case |\n|-----------|-------------|----------|\n| `system` | Platform health and monitoring | Platform administrators |\n| `configuration_manager` | Device and compliance management | Network engineers |\n| `devices` | Device-specific operations | NOC teams |\n| `operations_manager` | Workflow and job management | Automation developers |\n| `adapters` | Adapter lifecycle management | Integration specialists |\n| `applications` | Application lifecycle management | Application owners |\n| `automation_studio` | Command templates and automation | Network operators |\n| `gateway_manager` | External service management | System integrators |\n| `integrations` | External system integrations | API developers |\n| `lifecycle_manager` | Stateful product CRUD operations and state tracking | Product managers |\n| `workflow_engine` | Workflow execution metrics | Performance analysts |\n\n### **Role-Based Configurations**\n\nThe following role-based configurations provide tailored tool access based on specific job functions and responsibilities:\n\n**Platform SRE:**\n*Use Cases: Platform & application administration, Adapter management, Integration management, Troubleshooting, Platform overall health and functionality*\n\n```bash\nitential-mcp run --include-tags \"system,adapters,applications,integrations\"\n```\n\n*Available Tools: get_health, restart_application, start_application, stop_application, create_integration_model, get_job_metrics, get_task_metrics, restart_adapter, start_adapter, stop_adapter, get_task_metrics_for_app, get_task_metrics_for_task, get_task_metrics_for_workflow*\n\n**Platform Builder:**\n*Use Cases: Asset development, Asset promotion, Workflow metrics analysis, Resource lifecycle management*\n\n```bash\nitential-mcp run --include-tags \"operations_manager,automation_studio,configuration_manager,workflow_engine,lifecycle_manager\"\n```\n\n*Available Tools: create_resource, get_workflows, describe_command_template, run_command_template, run_command, render_template, create_device_group, get_resources, describe_resource, get_instances, backup_device_configuration, apply_device_configuration, get_compliance_plans, run_compliance_plan, get_adapters, get_applications, get_integration_models, get_job_metrics, get_job_metrics_for_workflow, get_task_metrics, get_task_metrics_for_workflow, get_task_metrics_for_app, get_task_metrics_for_task, describe_instance, run_action*\n\n**Automation Developer:**\n*Use Cases: Asset development, Asset promotion, External service management*\n\n```bash\nitential-mcp run --include-tags \"operations_manager,gateway_manager\"\n```\n\n*Available Tools: create_resource, get_services, get_gateways, run_service*\n\n**Platform Operator:**\n*Use Cases: Execute jobs, Run compliance, Consume data*\n\n```bash\nitential-mcp run --include-tags \"operations_manager,devices,configuration_manager,automation_studio\"\n```\n\n*Available Tools: get_workflows, start_workflow, get_jobs, describe_job, get_devices, get_device_configuration, get_device_groups, get_command_templates, run_command_template, describe_compliance_report*\n\n## \ud83d\udcda Documentation & Integration\n\n### **Complete Tool Reference**\nThe entire list of available tools can be found in the [tools documentation](docs/tools.md) along with detailed tag associations.\n\n### **Client Integration Guides**\n- [MCP Client Integration](docs/integration.md) - Configure Claude, Continue.dev, and other MCP clients\n- [Configuration Examples](docs/mcp.conf.example) - Complete configuration file reference\n- [Tagging System](docs/tags.md) - Advanced tagging and filtering guide\n- [Workflow Execution](docs/exposing-workflows.md) - Running automation workflows\n\n### **Example Prompts**\n- [Claude Desktop Prompt](docs/claude-example.prompt) - Optimized prompt for Claude integration\n- [GPT Integration Prompt](docs/gpt-example.prompt) - Optimized prompt for GPT integration\n\n## \ud83d\udca1 Available Tools\nThe entire list of available tools can be found in the [tools](docs/tools.md)\nfile along with the tag groups associated with those tools.\n\n## \ud83d\udee0\ufe0f Adding new Tools\nAdding a new tool is simple:\n\n1. Create a new Python file in the `src/itential_mcp/tools/` directory or add a function to an existing file\n2. Define an async function with a `Context` parameter annotation:\n\n```python\nfrom fastmcp import Context\n\nasync def my_new_tool(ctx: Context) -> dict:\n \"\"\"\n Description of what the tool does\n\n Args:\n ctx (Context): The FastMCP Context object\n\n Returns:\n dict: The response data\n\n Raises:\n None\n \"\"\"\n # Get the platform client\n client = ctx.request_context.lifespan_context.get(\"client\")\n\n # Make API requests\n res = await client.get(\"/your/api/path\")\n\n # Return JSON-serializable results\n return res.json()\n```\n\nTools are automatically discovered and registered when the server starts.\n\n### Running Tests\nRun the test suite with:\n\n```bash\nmake test\n```\n\nFor test coverage information:\n\n```bash\nmake coverage\n```\n\n## Contributing\nContributions are welcome! Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/my-feature`\n3. Commit your changes: `git commit -am 'Add new feature'`\n4. Push to the branch: `git push origin feature/my-feature`\n5. Submit a pull request\n\nBefore submitting:\n- Run `make premerge` to ensure tests pass and code style is correct\n- Add documentation for new features\n- Add tests for new functionality\n\n## License\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.\n\nCopyright (c) 2025 Itential, Inc\n",
"bugtrack_url": null,
"license": null,
"summary": "Itential MCP Server",
"version": "0.8.0",
"project_urls": {
"Documentation": "https://github.com/itential/itential-mcp",
"Homepage": "https://itential.com",
"Repository": "https://github.com/itential/itential-mcp"
},
"split_keywords": [
"agent",
" fastmcp",
" llm",
" mcp",
" mcp client",
" mcp server",
" model context protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "25f4e4aa6a2dd36240a2d4ca88357ab17d0e3bc0104428514721b4f6891925cb",
"md5": "baa84e90e3840a2fef98f588319b4949",
"sha256": "c6f626a211fe08838d3fae94f49e65e93278b2a69de29e28b1690523b6fc3e81"
},
"downloads": -1,
"filename": "itential_mcp-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "baa84e90e3840a2fef98f588319b4949",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 152079,
"upload_time": "2025-11-04T12:44:51",
"upload_time_iso_8601": "2025-11-04T12:44:51.432483Z",
"url": "https://files.pythonhosted.org/packages/25/f4/e4aa6a2dd36240a2d4ca88357ab17d0e3bc0104428514721b4f6891925cb/itential_mcp-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1ff5d06524b0be7204492c6160af06ed0854183a18ec9b5e8411b085f737636b",
"md5": "25bbac72f56b138b870d367bb64f16bf",
"sha256": "8cb6ffe7af3fdfca16783e775a3d2b6070ccc360a8f232d58dd897f658f58720"
},
"downloads": -1,
"filename": "itential_mcp-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "25bbac72f56b138b870d367bb64f16bf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 406039,
"upload_time": "2025-11-04T12:44:52",
"upload_time_iso_8601": "2025-11-04T12:44:52.872237Z",
"url": "https://files.pythonhosted.org/packages/1f/f5/d06524b0be7204492c6160af06ed0854183a18ec9b5e8411b085f737636b/itential_mcp-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-04 12:44:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "itential",
"github_project": "itential-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "itential-mcp"
}
JSON
