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

Updated 16 Mar 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.

## Overview

Red Hat Ansible Automation Platform (AAP) 2.6 introduces the MCP server for Ansible Automation Platform as a technology preview feature. The MCP server acts as a bridge between external AI tools and AAP, exposing the AAP API through the Model Context Protocol (MCP).

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

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

### 2. Start the MCP server container

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

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 it, mount your certificate and key when starting the container:

podman run -d --rm --name aap-mcp-server \
  -e BASE_URL=https://YOUR_AAP_HOSTNAME_HERE \
  -p 8448:8448 \
  -v /path/to/cert.pem:/etc/ansible-automation-platform/ansiblemcp/ansiblemcp.crt:z \
  -v /path/to/key.pem:/etc/ansible-automation-platform/ansiblemcp/ansiblemcp.key:z \
  registry.redhat.io/ansible-automation-platform-tech-preview/mcp-server-rhel9:latest

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

If connecting to an AAP instance with self-signed certificates, set IGNORE_CERTIFICATE_ERRORS=true. Do not use this setting in production.

## Stopping the server