Running the MCP server for Ansible Automation Platform as a standalone container

Table of Contents

• Overview
• Prerequisites
• Setup
  • 1. Pull the MCP server container image
  • 2. Start the MCP server container
    • Enable TLS on MCP server(optional)
  • 3. Verify the container is running
  • 4. Get an AAP OAuth 2.0 token
  • 5. Set the token in your environment
  • 6. Configure your MCP client
  • 7. Connect your MCP client
• Available toolsets
• Example usage
• Troubleshooting
  • Container fails to start
  • MCP servers not connecting
  • Authentication errors
  • Certificate errors
• Stopping the server
• References

Overview

Red Hat Ansible Automation Platform (AAP) includes an MCP server that acts as a bridge between external AI tools and AAP, exposing the AAP API through the Model Context Protocol (MCP). The MCP server is available for both AAP 2.6 and AAP 2.7.

The official deployment model integrates the MCP server directly into the AAP installation, either through the containerized installer on Red Hat Enterprise Linux or through the operator on Red Hat OpenShift Container Platform. For details on the official deployment, see:

• IT automation with agentic AI: Introducing the MCP server for Red Hat Ansible Automation Platform
• Deploying Ansible MCP server on Ansible Automation Platform 2.6 (containerized installation)
• Deploying Ansible MCP server on Ansible Automation Platform 2.7 (containerized installation)

This article describes an alternate approach: running the MCP server container standalone on your local machine and connecting it to a remote AAP instance. This model is useful when you want to evaluate the MCP server without modifying your AAP deployment, or when you do not have administrator access to the AAP installation.

With this standalone deployment, your MCP client (such as Claude, Cursor, ChatGPT, or VS Code) connects to the local MCP server, which forwards requests to the remote AAP instance. Your MCP client can then:

• List and manage job templates.
• View job executions and their output.
• Query inventories, hosts, and groups.
• Monitor system status and activity streams.
• Manage users, teams, and credentials.

Prerequisites

• Podman (or Docker) installed and configured.
• Access to registry.redhat.io (logged in via podman login registry.redhat.io).
• A running AAP 2.6 or AAP 2.7 instance with API access.
• An AAP OAuth 2.0 token for authentication.
• An MCP-compatible AI tool installed (such as Claude, Cursor, ChatGPT, or VS Code).

Setup

1. Pull the MCP server container image

Pulling from registry.redhat.io requires authentication. If you have not already logged in, see Red Hat Container Registry Authentication.

Pull the image that matches your AAP version:

For AAP 2.6:

podman pull registry.redhat.io/ansible-automation-platform-tech-preview/mcp-server-rhel9:latest

For AAP 2.7:

podman pull registry.redhat.io/ansible-automation-platform-27/mcp-server-rhel9:latest

2. Start the MCP server container

Use the image that matches your AAP version.

For AAP 2.6:

podman run -d --rm --name aap-mcp-server \
  -e BASE_URL=https://YOUR_AAP_HOSTNAME_HERE \
  -e IGNORE_CERTIFICATE_ERRORS=true \
  -p 3000:3000 \
  registry.redhat.io/ansible-automation-platform-tech-preview/mcp-server-rhel9:latest

For AAP 2.7:

podman run -d --rm --name aap-mcp-server \
  -e BASE_URL=https://YOUR_AAP_HOSTNAME_HERE \
  -e IGNORE_CERTIFICATE_ERRORS=true \
  -p 3000:3000 \
  registry.redhat.io/ansible-automation-platform-27/mcp-server-rhel9:latest

Environment variables:

Enable TLS on the MCP server (optional)

The MCP server container includes a built-in nginx reverse proxy that can serve HTTPS on port 8448. To enable TLS, you must provide four volume mounts: your server certificate, your private key, the system CA trust store, and a custom nginx configuration file.

Important: The default nginx configuration in the container image does not enable TLS. You must mount a custom nginx.conf for the TLS listener to function. This applies to both the AAP 2.6 and AAP 2.7 images.

Mounting /etc/pki/ca-trust is required when the AAP instance uses a certificate signed by a custom or internal CA. Without this mount, the MCP server cannot verify AAP's TLS certificate and connections to AAP will fail.

Step 1: Download nginx.conf_.txt from the attachment section of this article. Rename it to nginx.conf in your working directory.

mv nginx.conf_.txt nginx.conf

Step 2: Set permissions on the certificate and key files.

The nginx process inside the container runs as a different user. Both files must be readable by other users or the container will fail to start.

chmod 644 MyCert.crt MyPrivate.key

Step 3: Start the container with TLS.

Replace the certificate and key paths with the paths to your files. Use the image that matches your AAP version.

For AAP 2.6:

podman run -d --rm --name aap-mcp-server \
  -e BASE_URL=https://YOUR_AAP_HOSTNAME_HERE \
  -p 8448:8448 \
  -v ./MyCert.crt:/etc/ansible-automation-platform/ansiblemcp/ansiblemcp.crt:z \
  -v ./MyPrivate.key:/etc/ansible-automation-platform/ansiblemcp/ansiblemcp.key:z \
  -v /etc/pki/ca-trust:/etc/pki/ca-trust:O \
  -v ./nginx.conf:/etc/nginx/nginx.conf:z \
  registry.redhat.io/ansible-automation-platform-tech-preview/mcp-server-rhel9:latest

For AAP 2.7:

podman run -d --rm --name aap-mcp-server \
  -e BASE_URL=https://YOUR_AAP_HOSTNAME_HERE \
  -p 8448:8448 \
  -v ./MyCert.crt:/etc/ansible-automation-platform/ansiblemcp/ansiblemcp.crt:z \
  -v ./MyPrivate.key:/etc/ansible-automation-platform/ansiblemcp/ansiblemcp.key:z \
  -v /etc/pki/ca-trust:/etc/pki/ca-trust:O \
  -v ./nginx.conf:/etc/nginx/nginx.conf:z \
  registry.redhat.io/ansible-automation-platform-27/mcp-server-rhel9:latest

Port reference:

Note: Do not set IGNORE_CERTIFICATE_ERRORS=true when using TLS mode with a CA-signed certificate. The CA trust mount handles certificate verification.

3. Verify the container is running

Run the following commands to confirm the MCP server container started correctly:

podman ps
podman logs aap-mcp-server
curl http://localhost:3000/api/v1/health

A successful health check returns {"status":"ok"}.

Note: When using TLS, update URLs to use https://localhost:8448 instead of http://localhost:3000.

4. Get an AAP OAuth 2.0 token

1. Log in to the AAP web UI.
2. Navigate to User Settings → Tokens.
3. Click Create Token.
4. Copy the generated token.

5. Set the token in your environment

export AAP_TOKEN="<token>"

For persistence, add this line to your shell profile (.bashrc, .zshrc, or equivalent).

6. Configure your MCP client

Each MCP client has its own configuration method. The key information you need for any client is the MCP server URL pattern (http://localhost:3000/mcp/<toolset>) and the authorization header (Bearer <token>).

The following example shows a .mcp.json file for Claude Code. Consult your MCP client documentation for the equivalent configuration in other tools.

{
  "mcpServers": {
    "aap-mcp-job-management": {
      "type": "http",
      "url": "http://localhost:3000/mcp/job_management",
      "headers": {
        "Authorization": "Bearer ${AAP_TOKEN}"
      }
    },
    "aap-mcp-inventory-management": {
      "type": "http",
      "url": "http://localhost:3000/mcp/inventory_management",
      "headers": {
        "Authorization": "Bearer ${AAP_TOKEN}"
      }
    },
    "aap-mcp-system-monitoring": {
      "type": "http",
      "url": "http://localhost:3000/mcp/system_monitoring",
      "headers": {
        "Authorization": "Bearer ${AAP_TOKEN}"
      }
    },
    "aap-mcp-user-management": {
      "type": "http",
      "url": "http://localhost:3000/mcp/user_management",
      "headers": {
        "Authorization": "Bearer ${AAP_TOKEN}"
      }
    },
    "aap-mcp-security-compliance": {
      "type": "http",
      "url": "http://localhost:3000/mcp/security_compliance",
      "headers": {
        "Authorization": "Bearer ${AAP_TOKEN}"
      }
    },
    "aap-mcp-platform-configuration": {
      "type": "http",
      "url": "http://localhost:3000/mcp/platform_configuration",
      "headers": {
        "Authorization": "Bearer ${AAP_TOKEN}"
      }
    }
  }
}

Note: If you enabled TLS, use https://localhost:8448 instead of http://localhost:3000 in your MCP client configuration.

7. Connect your MCP client

1. Verify that AAP_TOKEN is set in your environment.
2. Open your MCP client and load the MCP server configuration.
3. Approve or enable the MCP servers when prompted.
4. Verify the servers are connected using your client's MCP status command.

Available toolsets

The MCP server organizes AAP functionality into toolsets:

Example usage

After connecting, you can ask your AI tool to interact with AAP:

> List all job templates
> Show me the recent job executions
> What hosts are in the Demo Inventory?
> Show me the system status
> List all users in the Default organization

Troubleshooting

Container fails to start

ss -tlnp | grep 3000
podman logs aap-mcp-server

If port 3000 is already in use, stop the conflicting process or set MCP_PORT to a different port.

MCP servers not connecting

1. Verify the container is running: podman ps.
2. Check the health endpoint: curl http://localhost:3000/api/v1/health.
3. Verify AAP_TOKEN is set: echo $AAP_TOKEN.
4. Use your MCP client's status command to check server connectivity.

Authentication errors

• Verify the AAP token is valid and not expired.
• Verify the token has appropriate permissions in AAP.
• Verify that AAP_TOKEN is exported in the same shell session as your MCP client.

Certificate errors

Self-signed certificates on the AAP instance: Set IGNORE_CERTIFICATE_ERRORS=true when starting the container. Do not use this setting in production.

Certificates signed by a custom or internal CA: Do not set IGNORE_CERTIFICATE_ERRORS=true. Instead, enable TLS mode and mount the system CA trust store as described in Enable TLS on the MCP server. The -v /etc/pki/ca-trust:/etc/pki/ca-trust:O mount allows the MCP server to verify the AAP certificate against your CA chain. The :O flag creates a read-only overlay mount that does not modify the host trust store.

Wrong MCP server version

If you see unexpected API errors or missing fields, verify that your MCP server image matches your AAP version. The AAP 2.6 MCP server uses AAP 2.6 APIs, and the AAP 2.7 MCP server uses AAP 2.7 APIs. Using a mismatched server will result in errors.

Stopping the server

podman stop aap-mcp-server

Container image reference

References

• Deploying Ansible MCP server on AAP 2.6 (containerized installation)
• Deploying Ansible MCP server on AAP 2.7 (containerized installation)
• IT automation with agentic AI: Introducing the MCP server for Red Hat Ansible Automation Platform
• AAP MCP server source code
• Model Context Protocol documentation
• Connecting an AI agent to the Ansible MCP server (AAP 2.6)
• Connecting an AI agent to the Ansible MCP server (AAP 2.7)