🔌 Itential - MCP Server

A Model Context Protocol (MCP) server that provides tools for connecting LLMs to Itential Platform. Enable AI assistants to manage network automations, orchestrate workflows, and monitor platform health.

📒 Features

• Multiple Transport Methods: Choose between stdio (default) or SSE transport for MCP server
• Dynamic Tool Loading: Automatically discovers and registers tools without modifying core code
• Flexible Authentication: Supports both basic authentication and OAuth for Itential Platform
• Configurable: Set options via command line parameters or environment variables
• Containerized: Run as a Docker container with configurable environment
• Extensible: Easy to add new tools without deep knowledge of the code base

🔍 Requirements

• Python 3.10 or higher
• Access to an Itential Platform Instance
• For development - uv and make

🔧 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:

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.

git clone https://github.com/itential/itential-mcp
cd itential-mcp
make build

Build Container Image

Build and run as a container:

# Build the container image
make container

# Run the container with environment variables
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=URL \
  --env ITENTIAL_MCP_PLATFORM_CLIENT_ID=CLIENT_ID \
  --env ITENTIAL_MCP_PLATFORM_CLIENT_SECRET=CLIENT_SECRET \
  itential-mcp:devel

📝 Basic Usage

Start the MCP server with default settings (stdio transport):

itential-mcp --transport --host 0.0.0.0 --port 8000

Start with SSE transport:

itential-mcp --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, streamable-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:

export ITENTIAL_MCP_SERVER_TRANSPORT=sse
export ITENTIAL_MCP_PLATFORM_HOST=platform.example.com
itential-mcp  # 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

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

💡 Available Tools

The MCP server provides the following tools for interaction with Itential Platform:

System Tools

• get_health: Retrieve platform health status including memory, CPU usage, and service status

Workflow Engine Tools

• get_job_metrics: Get aggregated workflow job metrics
• get_task_metrics: Get aggregated workflow task metrics

Workflow Management Tools

• get_workflows: List available workflows
• start_workflow: Start a workflow with provided variables and permissions

Job Tools

• get_jobs: List all jobs (with optional filtering)
• describe_job: Get details about a specific job (based on job_id)

Command Template Tools

• get_command_templates: List all configured command templates
• describe_command_template: Get details about a specific command template
• run_command_template: Run a command template against a set of devices

Device Tools

• get_devices: Get a list of devices from Itential Platform
• run_command: Run a command against one or more devices

Note: See here for information about how to properly expose workflows to the MCP server

🛠️ 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:

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:

make test

For test coverage information:

make coverage

Contributing

Contributions are welcome! Please read our Code of Conduct 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 file for details.

Copyright (c) 2025 Itential, Inc