Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 11. Using the MCP server for RHEL to enable AI assistants to run, discover, and troubleshoot complex issues

By using the Model Context Protocol (MCP) server for RHEL, you can enable LLMs to act as system administrators, capable of discovering and troubleshooting complex issues across your infrastructure.

Important

Red Hat Enterprise Linux (RHEL) command-line assistant is Developer Preview software only. Developer Preview software is not supported by Red Hat in any way and is not functionally complete or production-ready. Do not use Developer Preview software for production or business-critical workloads. Developer Preview software provides early access to upcoming product software in advance of its possible inclusion in a Red Hat product offering. Customers can use this software to test functionality and provide feedback during the development process. This software might not have any documentation, is subject to change or removal at any time, and has received limited testing. Red Hat might provide ways to submit feedback on Developer Preview software without an associated SLA. For more information about the support scope of Red Hat Developer Preview software, see Developer Preview Support Scope.

11.1. How MCP servers on RHEL work
Copy link

The MCP server for RHEL runs locally on the same machine as the AI client. The tool runs through SSH by using your account and follows the same security restrictions.

By default, the MCP server operates in read-only mode to ensure safe system diagnostics. If you need to make administrative changes, you can explicitly enable read/write mode.

The server runs on RHEL 10 Base operating system on-premise hosts. Access the MCP server through the RHEL Developer Subscription for production testing on RHEL, Linux, macOS, or Windows 11.

The MCP server for RHEL has the following capabilities:

  • Inspect local and target systems for troubleshooting.
  • Public key discovery to list available public keys from the local ~/.ssh directory.
  • Comprehensive error handling with clear error messages for connection and execution issues.

The MCP server for RHEL has the following system management features:

  • Read-only operations: All tools are strictly read-only for safe diagnostics.
  • Remote SSH execution: Inspect systems by using SSH with key-based authentication.
  • Local execution: Inspect the local system (when the MCP server is not running in a container).
  • Multi-host management: Connect to different target system hosts in the same LLM session.
  • Comprehensive diagnostics: System information, services, processes, logs, network, and storage.
  • Configurable log access: Use environment variables to control which log files are accessible.

To enable the RHEL MCP server to connect to your target machine with SSH, use an account with key-based authentication.

Prerequisites

  • A client machine with the operating system of your choice.
  • A RHEL target machine.
  • SSH connectivity between the host running the MCP server and the RHEL target machine.

Procedure

  1. On the client machine, generate an SSH keypair: 

    $ ssh-keygen -t ed25519 -C "<your-email@example.com>" -f id_ed25519_mcp

  2. On the RHEL target machine, create a non-root user:

    1. Access the VM by SSH and run the following commands: 

      $ sudo useradd mcp
$ sudo passwd mcp

  3. On the client machine, add the target machine to your SSH configuration file:

    1. Edit the ~/.ssh/config configuration file and add the following information: 

      Host <rhel-10-0>
HostName <target-machine-ip-address>
User <user-test>
Port 22
IdentityFile <path-to-your-ssh-pub-key>
StrictHostKeyChecking no

  4. Copy your public key from your client machine to the target machine. 

    $ ssh-copy-id -i ~/.ssh/id_ed25519_mcp.pub mcp@<vm_ip_address>

  5. Restart the SSH service: 

    $ sudo systemctl restart sshd

11.3. Installing the RHEL MCP server
Copy link

You can install the RHEL MCP server on your host to use it with any AI client. Choose one of the following methods to perform the installation based on your security requirements.

  • Running the MCP server from a container for enhanced security.
  • Installing the MCP server locally by using pip package manager for direct host administration.

You can run the MCP server on your system by using a container image. The MCP server uses SSH to connect to target system hosts. You must make the SSH keys available inside the container. If the SSH key is encrypted, you must provide a passphrase to decrypt the key.

Note

In container-based scenarios, you cannot use the MCP server for RHEL to inspect the local system.

Prerequisites

  • The container-tools meta-package is installed.
  • Podman is installed on your host machine.
  • A target machine where the MCP server for RHEL executes commands by SSH.

Procedure

  • On the LLM client, run the container image: 

    podman run --rm --interactive --userns keep-id:uid=1001,gid=0 -e LINUX_MCP_KEY_PASSPHRASE -e LINUX_MCP_USER -v $HOME/.ssh/id_ed25519_mcp:/var/lib/mcp/.ssh/id_ed25519:ro,Z -v $HOME/.local/share/linux-mcp-server/logs:/var/lib/mcp/.local/share/linux-mcp-server/logs:rw,Z quay.io/redhat-services-prod/rhel-lightspeed-tenant/linux-mcp-server:latest

    The --rm option removes the container image after the container exits.

Verification

  • List the running containers: 

    $ podman ps

The MCP server for RHEL runs locally on the same machine as your AI agent. The MCP server for RHEL is responsible for connecting to your target RHEL machine. Your AI agent communicates with this local server by standard I/O (stdio).

Prerequisites

  • Python 3.10 or higher. 

    $ sudo dnf install python3 python3-pip

Procedure

  • Install the package from PyPI: 

    $ pip install --user linux-mcp-server

Verification

  • Test the server: 

    $ ~/.local/bin/linux-mcp-server

    The server starts and displays initialization messages.

  • To stop the MCP server, press the Ctrl+C keys, then the Return key.

Next steps

By configuring your AI client to communicate with the RHEL Model Context Protocol (MCP) server, you enable the client to run Linux system diagnostics and management tasks as a background process using the standard I/O (stdio) transport.

Integrate the RHEL MCP server into your AI application using one of the following methods, depending on whether you are running the server locally or by using a container. The MCP server for RHEL JSON configuration requires the following parameters:

Expand

MCP Server or Connection Type

Standard IO (STDIO)

ID / Name

linux-tools

Description

Linux system diagnostics

Command

/home/<your-username>/.local/bin/linux-mcp-server

Arguments

[] (Empty array)

Environment Variables

LINUX_MCP_USER=<your-ssh-username>

Prerequisites

  • An MCP-compatible AI client installed and active on your workstation.
  • A RHEL system with the MCP server installed.

Procedure

  • Option 1: Local configuration with pip. Add the mcpServers JSON configuration to integrate into your AI application:

    1. Open your AI client’s configuration file.

    2. Add the following JSON object to the mcpServers section: 

      {
 "mcpServers": {
   "linux-mcp-server": {
     "command": "~/.local/bin/linux-mcp-server",
     "args": [],
     "env": {
       "LINUX_MCP_USER": "<your-ssh-username>"
     }
   }
 }
}

  • Option 2: Container I/O (stdio) transport. Add the mcpServers JSON configuration to integrate into your AI application:

    1. Open your AI client’s configuration file.

    2. Add the following JSON object, ensuring you replace YOUR_USER with your actual local system username: 

      {
  "mcpServers": {
    "Linux Tools": {
      "command": "podman",
      "args": [
        "run",
        "--rm",
        "--interactive",
        "--userns", "keep-id:uid=1001,gid=0",
        "-e", "LINUX_MCP_KEY_PASSPHRASE",
        "-e", "LINUX_MCP_USER",
        "-v", "/home/YOUR_USER/.ssh/id_ed25519:/var/lib/mcp/.ssh/id_ed25519:ro,Z",
        "-v", "/home/YOUR_USER/.ssh/config:/var/lib/mcp/.ssh/config:ro,Z",
        "-v", "/home/YOUR_USER/.local/share/linux-mcp-server/logs:/var/lib/mcp/.local/share/linux-mcp-server/logs:rw,Z",
        "quay.io/redhat-services-prod/rhel-lightspeed-tenant/linux-mcp-server:latest"
      ],
      "env": {
        "LINUX_MCP_KEY_PASSPHRASE": "<secret>",
        "LINUX_MCP_USER": "YOUR_USER"
      }
    }
  }
}
      Important

      The examples provided are representative. Depending on your specific AI client, such as Claude Desktop, or Gemini, you might need to adjust the JSON structure or the paths to the executable. Check your AI client’s documentation for exact configuration syntax.

Verification

  1. Restart your AI client.
  2. Check the client’s logs or Server Status dashboard to confirm the RHEL MCP server is listed as Connected.

  3. In the AI assistant chat, ask a test question such as: 

    "What is the status of the firewall on my RHEL system?"

Use the MCP server for RHEL to enable an LLM to obtain and analyze RHEL system logs, including journald and syslog data. The LLM can detect anomalies, identify security threats, and perform AI-driven root cause analysis.

You can also use the MCP server for RHEL to enable an LLM to run commands on the RHEL system.

Prerequisites

  • You installed the MCP server for RHEL.

Procedure

  1. Optional: Configure environment variables to select which log files the MCP server for RHEL can access, and the logging level required. 

    export LINUX_MCP_ALLOWED_LOG_PATHS="/var/log/messages,/var/log/secure,/var/log/audit/audit.log"
export LINUX_MCP_LOG_LEVEL="INFO"

  2. Run the RHEL MCP server. 

    $ linux-mcp-server

  3. Ask questions, for example: 

    "What version of RHEL is this system running?"
"Show me the current CPU load and usage per core."
"How much memory is being used on this system?"
"Which filesystems are running out of space?"
"What hardware is installed in this system?"
"Show me all critical and error logs since yesterday."
    Warning

    Current known issues and limitations:

    You might experience issues getting the SSH authentication working in the container, especially with Docker, because it does not support user namespace mapping. To workaround this issue, the SSH key file must be owned by UID 1001 on the container host.

    When you run the MCP server for RHEL in a container, it cannot inspect the local system because of container isolation.

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top