Deploy Ansible MCP server on Ansible Automation Platform

As an organization administrator, you can deploy an Ansible Model Context Protocol (MCP) server on an operator-based installation or container-based installation of Ansible Automation Platform 2.6. This functionality is available as a Technology Preview release.

Overview
Copy link

Model Context Protocol (MCP) is an open standard that enables AI models to use external AI tools and services via a unified interface. Using the Ansible MCP server, you can connect your Ansible Automation Platform with your preferred external AI tool (such as Claude, Cursor, or ChatGPT).

The AI tools can access key information about your Ansible Automation Platform environment and perform tasks. Ansible users can query information, execute workflows, and perform automation tasks using natural language prompts directly within their preferred AI tool.

Note

Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

Benefits
Copy link

The following are the benefits of the Ansible MCP server:

For external AI tools:

  • Provides a standardized interface for securely querying infrastructure data and executing automation workflows within the Ansible Automation Platform.
  • Enables agentic workflows to interact with the Ansible Automation Platform.

For Ansible users:

  • Provides the ability to use the chatbot interface of their preferred external AI tool to get information about their Ansible Automation Platform environment, and run automation jobs directly through that tool.

For developers:

  • Reduces the time and complexity of developing or integrating the Ansible Automation Platform with AI applications or agents.
  • Simplifies AI integration, enabling existing automation through Ansible Automation Platform to be exposed to AI tools without writing custom API code or middleware.

Workflow
Copy link

The standalone Ansible MCP server functions as a secure link between your external AI clients and the Ansible Automation Platform. The AI agent accesses underlying infrastructure only when the Ansible MCP server has appropriate permissions.

The following describes the workflow:

  1. AI client (The requester): The user initiates a request through their external AI agent (for example, Cursor or Claude) using natural-language prompts.
  2. The AI model (The translator): The AI agent receives the request, interprets the intent, and maps it to the appropriate exposed Ansible toolset. It then sends a structured toolset call with the necessary parameters.
  3. Ansible MCP server (The gatekeeper): Upon receiving the call, the Ansible MCP server validates the request. It uses the user’s API token to authenticate with the automation controller.
  4. Ansible controller (The executor): The automation controller accepts the validated command from the MCP server and triggers the appropriate automation job.
  5. Response loop: The automation result is returned to the Ansible MCP server, standardized into a format the AI agent can process, and displayed to the user via the AI client.
Important

Both the Ansible MCP server and the Ansible Automation Platform UI access the Ansible Automation Platform API. However, because the AI tool processes the API output before displaying it in its chat interface, you might observe different results when comparing the output from the AI tool with the Ansible Automation Platform UI.

Ansible MCP server toolsets
Copy link

The Ansible MCP server provides a pre-configured suite of toolsets that effectively act as a bridge between your preferred AI agent and the Ansible Automation Platform. Once configured, these toolsets enable your AI agent to perform specific, authorized actions without requiring you to leave the chat interface.

The Ansible MCP server turns your AI agent from a passive assistant into an active operator that can interact with your Ansible Automation Platform infrastructure and execute workflows or automate tasks based on the permissions you define.

The following toolsets are available in this Technology Preview release:

Expand
Toolset Description Usage examples

Job management

Tools to list available job templates, launch automation jobs, and monitor their real-time status.

Operators can:

  • Launch job templates and workflows to execute automation tasks for their projects and services.
  • View job output and logs to troubleshoot failed automation tasks and understand what went wrong.
  • Relaunch failed jobs to recover from temporary failures and complete necessary automation tasks.

Inventory management

Tools to query your inventory for host details, check group membership, and verify system facts.

Operators can:

  • View and browse inventories across environments to understand which systems they are managing with automation.
  • Manage group assignments to target automation to specific sets of systems.
  • View hosts that are configured for automation.

System monitoring

Tools to retrieve job logs, troubleshoot failed tasks, and check the health of your automation environment.

Administrators can:

  • Perform platform status and health checks across all services to identify issues and ensure the automation platform is running correctly.
  • Monitor service health through the platform gateway to ensure all platform components are functioning correctly.
  • Audit user activity and generate reports to ensure compliance and identify potential security issues.

User management

Tools to allow the AI agent to administer access and organizational structure within the Ansible Automation Platform.

Administrators can:

  • Use natural-language prompts to provision users and enforce hierarchy, rather than manually navigating the UI.
  • Create, modify, and delete users and teams to manage access to the Ansible Automation Platform and support organizational changes.
  • Configure role-based access control to ensure users have the appropriate permissions for their responsibilities while maintaining security.
  • View team memberships and structure to see who else in their organization is working on automation.

Security/compliance

Tools that enable the AI agent to act as a security operator, managing sensitive credentials and verifying platform integrity without exposing raw secrets.

Operators can:

  • View available credentials to understand what authentication options are available for their automation jobs.

Administrators can:

  • Manage credentials and security policies to ensure secure access to external systems while maintaining proper governance.
  • Manage custom credential types for seamless integration with third-party applications.

Platform configuration

Tools that enable organization administrators and developers to inspect and tune the Ansible Automation Platform infrastructure itself.

Administrators can:

  • Manage system settings across all components to configure the platform in line with the organizational requirements and policies.
  • Manage and track licenses to ensure compliance with licensing terms and optimize license utilization.

Developers can:

  • Tune execution environments to optimize the runtime performance of their automation content.

Server-level and user-level permissions
Copy link

The Ansible MCP server employs a dual-layer security model to ensure safe integration between AI tools and your Ansible Automation Platform infrastructure. This approach combines a global administrative safeguard with the granular Role-Based Access Control (RBAC) of the Ansible Automation Platform.

You can grant the following access types to the Ansible MCP server:

  • Server-level permissions: Organization administrators assign a global-level permission while deploying the Ansible MCP server. Administrators can choose one of the following access levels:
    • Read-only access: The default setting that enforces a strict "look but do not touch" policy. The AI agent can retrieve system data, such as logs and inventory, but the agent cannot launch jobs or modify configurations. This global safeguard overrides all individual user permissions to prevent unintended automation.
    • Read-write access: This setting authorizes the AI agent to make changes in your Ansible Automation Platform, such as executing job templates, managing resources, and applying infrastructure changes. However, these actions are subject to the specific RBAC permissions of the user-provided API token.
  • User-level permissions: The AI agent’s specific capabilities are inherited from the user account that generated the authentication API token.
    • Inherited permissions: The AI tool inherits the user’s permissions and performs only the actions the user is authorized to perform. For example, if the user’s token only has permissions to view the "network" inventory, the AI tool cannot access or modify the "database" inventory even if the user requests it.
    • Rejection of unauthorized actions: If the AI tool attempts an action (like launching a job) that the user’s token is not authorized to perform, the Ansible Automation Platform API rejects the request.
Warning

Enabling read-write access for the Ansible MCP server grants the AI agent autonomy to directly make changes in your Ansible Automation Platform environment, for example, executing automation jobs. The AI agent can directly make changes in your Ansible Automation Platform environment only if the user has write permissions. Large Language Models (LLMs) can occasionally misinterpret prompts or hallucinate commands. Therefore, enabling read-write access may introduce a risk of unintended changes to your environment.

Telemetry data collection for Ansible MCP server
Copy link

Red Hat collects anonymized telemetry data from the Ansible MCP server. The telemetry data includes metrics related to MCP server performance, adoption trends, and usage patterns.

Telemetry data will be automatically collected for Ansible MCP server deployments using Ansible Automation Platform patch release on 21 January 2026 and later versions. Red Hat will use this data to monitor the operational health of your MCP servers and to ensure the long-term scalability of the MCP ecosystem.

Important

Telemetry data collection cannot be disabled, but strict user privacy is maintained. Red Hat does not collect users' personal information, such as usernames or passwords. If any personal information is inadvertently received, the data is deleted. For more information, see the Red Hat Privacy Statement under Related Links below.

Prerequisites
Copy link

  • Platform version: An instance of Ansible Automation Platform 2.6 or later.
  • Deployment environment:
    • OpenShift: Access to an OpenShift cluster with permissions to install operators.
    • Containerized: A supported container runtime.
  • Access credentials: A valid user or service account within Ansible Automation Platform with permissions to execute the desired automation jobs. You will need to generate an API token for this account.

Overview of deploying the Ansible MCP server
Copy link

Perform the following tasks to deploy and configure an Ansible MCP server and integrate it with your preferred AI tool:

Expand
Step number Task Description

1

Deploy and configure an Ansible MCP server on container-based installation

An organization administrator deploys and configures the Ansible MCP server on a container-based installation of Ansible Automation Platform 2.6.

2

Create an API token for the Ansible MCP server

An Ansible user creates an API token for their Ansible Automation Platform instance and uses it to connect to their preferred AI tool. The AI tools will inherit the user’s permissions for authentication using the API token.

3

Connect an external AI agent to the Ansible MCP server

The Ansible user then configures an external AI tool with the Ansible MCP server’s API token, enabling the AI tool to connect to the Ansible MCP server and execute workflows and automate tasks.

Deploy the Ansible MCP server on a container-based installation
Copy link

As an organization administrator, you can deploy and configure an Ansible MCP server on a container-based installation of Ansible Automation Platform 2.6. Use the following procedure to deploy and configure the Ansible MCP server.

Before you begin
Copy link

  • You have a valid Ansible Automation Platform 2.6 subscription.

Procedure
Copy link

  1. Configure the Ansible MCP server variables in the inventory file:
    1. Create an [ansiblemcp] group and add a host for the Ansible MCP server.
    2. Add the following installation variables to your inventory file under the [all:vars] group:
      • mcp_allow_write_operations: Use to grant read-only or read-write permissions to the external AI tool.
      • mcp_ignore_certificate_errors: Use to bypass SSL/TLS certificate validation.
    3. To make your system trust a self-signed custom certificate, add the following required variables to your inventory file:
      • mcp_tls_cert: Path to TLS certificate
      • mcp_tls_key: Path to TLS key

        For information about using your own TLS certificates and keys, see Configuring custom TLS certificates. For information about required and optional variables, see Appendix: Ansible MCP server variables.

        # This is the list of inventory file variables required to deploy an Ansible MCP server on a container-based installation.

# This section is for the Ansible MCP server host
# -------------------------------------------------
[ansiblemcp]
aap.example.com

# This section is for Ansible MCP server permissions
# --------------------------------------------------
[all:vars]
mcp_allow_write_operations=false <To enable read-write access, set the "mcp_allow_write_operations" variable to "true">
mcp_ignore_certificate_errors=false
mcp_tls_cert= <path to tls certificate>
mcp_tls_key= <path to tls key>
  2. Run the install playbook to install containerized Ansible Automation Platform.

Results
Copy link

Check the pods after installation is complete. You should see an ansiblemcp pod running with the following command:

$ podman ps

What to do next
Copy link

  1. Obtain the location of the Ansible MCP server:
    • The service is exposed on port 8448 of the host, and HTTPS is enabled.
    • The example above deploys the MCP server on aap.example.com, so the service base URL will be https://aap.example.com:8448.
  2. Create an API token for the Ansible MCP server.

Deploy the Ansible MCP server on operator-based installation
Copy link

As an organization administrator, you can deploy and configure an Ansible MCP server on an operator-based installation of Ansible Automation Platform 2.6. Use the following procedure to deploy and configure the Ansible MCP server.

Before you begin
Copy link

  • You have a valid Ansible Automation Platform 2.6 subscription.

Procedure
Copy link

  1. Log in to Red Hat OpenShift Container Platform as an administrator.
  2. Navigate to the namespace where you want to install the MCP server.
  3. Select Operators > Installed Operators.
  4. From the list of installed operators, select Ansible Automation Platform.
  5. In the Ansible Automation Platform tile, click Create instance.
  6. From the Configure via field, select the Form view, then provide the instance name. For example, aap-mcp.
  7. Select the YAML view, and under the spec: section, add the mcp component: 
    spec:
  mcp:
    disabled: false
    allow_write_operations: false
  8. Use the allow_write_operations variable to configure the operational access level of the Ansible MCP server:
  9. Click Create. The Ansible MCP server is created.
  10. Optional: If you changed the permissions of the Ansible MCP server after it was created and deployed, you must delete the AnsibleMCPServer custom resource and recreate it.

    Perform the following steps:

    1. Go to the Ansible Automation Platform portal.
    2. Under Resources, search for the AnsibleMCPServer custom resource.
    3. Select the active AnsibleMCPServer instance. An active AnsibleMCPServer instance is identified by the -mcp suffix appended to the Ansible Automation Platform custom resource name.
    4. Select the Settings menu on the right side of the instance, and then click Delete AnsibleMCPServer.
    5. After the reconciliation process completes, the existing MCP server instance is deleted, and a new Ansible MCP server instance is created.

Results
Copy link

  1. Navigate to Workloads > Deployments.
  2. Check that the deployment you created is listed there. For example: aap-mcp.
  3. Check one of the pod’s logs and verify there are no errors.

What to do next
Copy link

  1. Obtain the following information:
    • Ansible Automation Platform login screen URL:
      1. Navigate to Networking > Routes.
      2. For the Ansible Automation Platform deployment, click the Copy icon in the Location field. This is the URL of the Ansible Automation Platform login screen.
    • Ansible Automation Platform administrator password:
      1. Navigate to Workloads > Secrets and click aap-admin-password.
      2. Click Reveal values and then use the Copy icon to save the Ansible Automation Platform administrator password for future use.
    • Ansible MCP server URL:
      1. Navigate to Networking > Routes.
      2. For the deployment you recently created (aap-mcp), click the Copy icon from the Location field. This is the URL required to configure your AI agent to connect to the Ansible MCP server.
  2. Create an API token for the Ansible MCP server.

Create an API token for the Ansible MCP server
Copy link

Create an API token for your Ansible Automation Platform instance, so you can use it to connect with your preferred AI agent. The AI tool will inherit the user’s permissions for API token-based authentication.

Before you begin
Copy link

  • Your organization administrator has deployed an Ansible MCP server.

Procedure
Copy link

  1. From the navigation panel, select Access Management > Users.
  2. Select the username for your user profile to configure OAuth 2 tokens.
  3. Select the Tokens tab. When no tokens are present, the Tokens screen prompts you to add them.
  4. Click Create token, and provide the following details:
    • Application: Enter the name of the application with which you want to associate your token. Alternatively, you can search for it by clicking Browse. This opens a separate window that enables you to choose from the available options. Select Name from the filter list to filter by name if the list is extensive. Note

      To create a Personal Access Token (PAT) that is not linked to any application, leave the Application field blank.
    • Description: (Optional) Provide a short description for your token.
    • Scope: (Required) Specify the level of access you want this token to have. The scope of an OAuth 2 token can be set as one of the following:
      • Write: Allows requests sent with this token to add, edit, and delete resources in the system.
      • Read: Limits actions to read only. The write scope includes the read scope.
  5. Click Create token. The token information is displayed.
  6. On the token information page that appears, click the Copy icon and save the token for future use.
    Important

    This will be the only time the token is displayed. Therefore, ensure that you save the token for future use.

Results
Copy link

You can verify that the application now shows the user with the appropriate token by selecting the Tokens tab on the Application Details page:

  1. From the navigation panel, select Access Management > OAuth Applications.
  2. Select the application you want to verify from the Applications list view.
  3. Select the Tokens tab.

    Your token should be displayed in the list of tokens associated with the application you chose.

What to do next
Copy link

Connect an AI agent to the Ansible MCP server
Copy link

Use the API token of the Ansible MCP server to connect it with your preferred AI agent, such as Claude, Cursor, or ChatGPT.

Before you begin
Copy link

  • An Ansible MCP server is deployed on your Ansible Automation Platform 2.6 environment.
  • An API token is created for your Ansible MCP server.

Procedure
Copy link

  1. Go to the AI tool that you want to connect to the Ansible Automation Platform.
  2. Follow your AI client’s instructions to configure the MCP server settings.

    Typically, you must specify the MCP server configurations in the mcp.json file.

  3. When configuring the mcp.json file, add the Ansible MCP server URL in the following format:

    <Ansible MCP server URL>/<toolset>/mcp

    Key:

    • Ansible MCP server URL = The URL of the Ansible MCP server. For example, https://api.example.com/.

      To obtain the Ansible MCP server URL, contact your organization administrator.

    • Toolset = The toolset that you want to connect to. For example, job_management, inventory_management, system_monitoring, user_management, security_compliance, and platform_configuration.
    • Token = The API token of the Ansible MCP server.

      Use the following format to add details about your Ansible MCP server in the the mcp.json file:

      {
  "mcpServers": {
    "aap-mcp-job-mgmt": {
      "type": "http",
      "url": "https://api.example.com/job_management/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    },
    "aap-mcp-inventory-mgmt": {
      "type": "http",
      "url": "https://api.example.com/inventory_management/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    },
    "aap-mcp-system-monitor": {
      "type": "http",
      "url": "https://api.example.com/system_monitoring/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    },
    "aap-mcp-user-mgmt": {
      "type": "http",
      "url": "https://api.example.com/user_management/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    },
    "aap-mcp-security": {
      "type": "http",
      "url": "https://api.example.com/security_compliance/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    },
    "aap-mcp-platform-config": {
      "type": "http",
      "url": "https://api.example.com/platform_configuration/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    }
  }
}
      Important

      Use a concise MCP server name, ideally limited to 20 characters. This is because AI agents combine the MCP server name with the tool name to create a unique identifier, and most AI agents enforce a 64-character limit on this combined identifier.

Results
Copy link

  • Verify that the AI tool successfully connects to the Ansible Automation Platform MCP server using the API token.

    In your AI agent’s chat window, enter a prompt like What MCP tools are available for my Ansible Automation Platform?. The AI agent should return a response with a list of tools that are enabled for the Ansible Automation Platform MCP server.

What to do next
Copy link

  • Open a new chat in your AI agent, and enter your prompt.

    For example: Give me a list of my Ansible Automation Platform jobs. A list of all your Ansible Automation Platform jobs is displayed in the AI agent’s chat window.

Troubleshoot Ansible MCP server errors
Copy link

This section contains information to help you diagnose and resolve issues with deploying the Ansible MCP server and connecting it to an external AI agent.

API output format rejected with 406 Status Code
Copy link

Issue: Ansible Automation Platform rejects an API request (for example, retrieving job stdout) with an HTTP 406 status code if the MCP server’s requested output is not in JSON format.

Workaround: To obtain the output in a specific format, instruct your AI tool to use JSON format first. You can then transform the JSON output into your desired format.

User requests rejected with 400 status code
Copy link

Issue: The Ansible MCP server may reject user requests from the external AI tool with 400 Bad Request status code. This error is encountered when the Ansible Automation Platform uses a self-signed certificate.

Workaround: Configure the Ansible MCP server to ignore certificate errors using the following steps:

  • For container-based installation: Set the value of variable mcp_ignore_certificate_errors to true.
  • For operator-based installation:

    Add the IGNORE_CERTIFICATE_ERRORS setting to the mcp: section of AnsibleAutomationPlatform custom resource in the following format:

      spec:
    mcp:
      extra_settings:
        - setting: IGNORE_CERTIFICATE_ERRORS
          value: true

Ansible MCP server permissions are changed post deployment
Copy link

Issue: If you changed the permissions of the Ansible MCP server after it was created and deployed, you must delete the AnsibleMCPServer custom resource and recreate it.

Workaround: Perform the following steps:

  1. Navigate to the Ansible Automation Platform portal.
  2. Under Resources, search for the AnsibleMCPServer custom resource.
  3. Select the active AnsibleMCPServer instance. An active AnsibleMCPServer instance is identified by the -mcp suffix appended to the Ansible Automation Platform custom resource name.
  4. Select the Settings menu (3-dot menu icon) on the right side of the instance, then click Delete AnsibleMCPServer.
  5. After the reconciliation process is completed, the existing Ansible MCP server instance is deleted and a new Ansible MCP server instance is created.