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

Updated 5 Aug 2026

Alternate Deployment Method: This guide provides step-by-step instructions for deploying the MCP server for Ansible Automation Platform as a standalone containerized service. Unlike the official integrated deployment (where MCP is bundled into AAP), this approach allows you to run the MCP server independently in a container environment and connect it to an existing remote AAP instance. This method is useful when you need MCP functionality without modifying your AAP installation, or when managing AAP instances in restricted environments.

Version-specific MCP server: The MCP server is version-specific. Because some APIs changed between AAP 2.6 and AAP 2.7, not all tools will work correctly if you use an MCP server image that does not match your AAP version. Use the AAP 2.6 MCP server image with AAP 2.6 instances, and the AAP 2.7 MCP server image with AAP 2.7 instances.

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

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:

Variable	Required	Default	Description
`BASE_URL`	Yes	`https://localhost`	The AAP instance URL.
`IGNORE_CERTIFICATE_ERRORS`	No	`false`	Set to `true` for self-signed certificates (development only).
`MCP_PORT`	No	`3000`	Port the MCP server listens on.
`ALLOW_WRITE_OPERATIONS`	No	`false`	Enable POST, PUT, PATCH, and DELETE operations.
`SESSION_TIMEOUT`	No	`1200`	Session timeout in seconds.
`ENABLE_METRICS`	No	`false`	Enable Prometheus metrics at `/metrics`.

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

Port	Description
`3000`	Direct HTTP access to the MCP server. No TLS. Use `-p 3000:3000`.
`8448`	HTTPS via nginx. Use `-p 8448:8448`.
`8086`	HTTP redirect to HTTPS on port 8448 (TLS mode only).

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

Log in to the AAP web UI.
Navigate to User Settings → Tokens.
Click Create Token.
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

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

## Available toolsets

The MCP server organizes AAP functionality into toolsets:

Toolset	Description
`job_management`	Job templates, jobs, workflow jobs, projects.
`inventory_management`	Inventories, hosts, groups, host variables.
`system_monitoring`	Instance groups, activity stream, mesh visualizer, status.
`user_management`	Users, teams, organizations, roles, authenticators.
`security_compliance`	Credentials, credential types, audit logs.
`platform_configuration`	Settings, execution environments, notification templates.

## 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

Verify the container is running: podman ps.
Check the health endpoint: curl http://localhost:3000/api/v1/health.
Verify AAP_TOKEN is set: echo $AAP_TOKEN.
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

AAP Version	Container Image
AAP 2.6	`registry.redhat.io/ansible-automation-platform-tech-preview/mcp-server-rhel9:latest`
AAP 2.7	`registry.redhat.io/ansible-automation-platform-27/mcp-server-rhel9:latest`

## References

SBR

Ansible

Product(s)

Red Hat Ansible Automation Platform

Category

Install

Article Type

General

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

Table of Contents