Deploy and Configure the MCP Server for Ansible Automation Platform: Complete Guide (Containerized and OpenShift)

The MCP (Model Context Protocol) server for Ansible Automation Platform lets AI tools — Claude, Cursor, ChatGPT, VS Code — query your AAP environment and execute automation workflows using natural language. This guide covers the complete setup: deploying on containerized or OpenShift-based AAP, understanding the six toolsets, configuring the dual-layer security model, creating API tokens, and wiring up your AI client with mcp.json.

How It Works

User natural-language prompt
        │
        ▼
  AI Agent (Claude / Cursor / VS Code)
        │  Interprets intent → maps to MCP tool
        ▼
  MCP Server (port 8448)
        │  Validates request using API token
        │  Checks server-level permission (read-only / read-write)
        ▼
  AAP Controller API
        │  Applies user RBAC from token's permission scope
        ▼
  Job launched / data returned
        │
        ▼
  MCP Server → AI Agent → User

The MCP server is a gatekeeper: it validates that the server-level permission allows the requested operation, then passes the call to the AAP API using the user's token. AAP's own RBAC enforces what that user can actually do. The AI tool processes the API response and displays it in the chat interface.

See also: Ansible Automation Platform MCP Server: Now Generally Available in AAP 2.7

Prerequisites

• AAP 2.6 or later (containerized or operator-based)
• An AAP user account or service account with permissions to execute the desired automation
• For OCP: cluster admin access to install operators

Deploying on Containerized AAP

The containerized installer uses inventory variables to configure the MCP server. Add an [ansiblemcp] group with the MCP server host and set permissions in [all:vars].

Inventory Configuration

# Inventory file — MCP server section

# MCP server host (can be the same host as AAP or a separate host)
[ansiblemcp]
aap.example.com

[all:vars]
# --- existing AAP variables above ---

# MCP server permissions
# false = read-only (default, recommended for initial deployment)
# true = read-write (allows AI agent to launch jobs and modify resources)
mcp_allow_write_operations=false

# Set to true only if AAP uses a self-signed certificate
mcp_ignore_certificate_errors=false

# TLS configuration (required for custom certificates)
mcp_tls_cert=/etc/aap/tls/mcp.crt
mcp_tls_key=/etc/aap/tls/mcp.key

# Optional: override default page size for list-type API responses
mcp_extra_settings='[{"setting": "DEFAULT_PAGE_SIZE", "value": "25"}]'

Run the installer to deploy the MCP server:

./setup.sh --inventory /etc/ansible-automation-platform/inventory

Verify Deployment

# Check the MCP server container is running
podman ps | grep ansiblemcp

# Test the MCP server health endpoint
curl -sk https://aap.example.com:8448/health | python3 -m json.tool

The MCP server is exposed on port 8448 with HTTPS. The base URL for your AI client configuration is https://aap.example.com:8448.

Deploying on OpenShift (Operator-Based)

Enable MCP in the AnsibleAutomationPlatform CR

Navigate to Operators → Installed Operators → Ansible Automation Platform, select your AAP instance, and switch to YAML view. Add the mcp section under spec:

apiVersion: aap.ansible.com/v1alpha1
kind: AnsibleAutomationPlatform
metadata:
  name: aap
  namespace: ansible-automation-platform
spec:
  # ... existing spec ...
  mcp:
    disabled: false
    allow_write_operations: false  # true to enable read-write

Click Create (or Save if updating an existing instance). The operator creates an AnsibleMCPServer custom resource and deploys the MCP server pods.

Custom CA Certificate (for self-signed OCP ingress)

If your OCP cluster uses a custom CA or self-signed certificates, the MCP server cannot validate the ingress certificate. Create a secret with your CA cert and reference it:

# Create the CA secret in the AAP namespace
oc create secret generic aap-mcp-ca-bundle \
  --from-file=bundle-ca.crt=/path/to/your-ca.crt \
  -n ansible-automation-platform

Add bundle_cacert_secret to the MCP spec:

spec:
  mcp:
    disabled: false
    allow_write_operations: false
    bundle_cacert_secret: aap-mcp-ca-bundle

The operator mounts the CA certificate, adds it to the combined CA bundle, and redeploys the MCP server pods. Verify with:

# Check init container logs for CA bundle confirmation
oc logs -n ansible-automation-platform \
  $(oc get pods -n ansible-automation-platform -l app=aap-mcp -o name | head -1) \
  -c init-ca-bundle | grep "Added customer CA bundle"

Find the MCP Server URL on OCP

# Get the MCP server route URL
oc get route -n ansible-automation-platform | grep mcp

Or via the OCP console: Networking → Routes → find the route for your MCP deployment (e.g., aap-mcp).

See also: MCP Server for Ansible Automation Platform: Traditional vs AI-Driven Automation

The Six Toolsets

The MCP server exposes six pre-configured toolsets. Each toolset maps to a URL path suffix and grants access to a specific category of AAP functionality.

Security Model

Dual-Layer Permission System

The MCP server enforces two permission layers in sequence:

Layer 1 — Server-level permission (set at deploy time by the administrator):

The AI tool inherits exactly the permissions of the user whose API token was provided. If the token belongs to a user with view-only access to the network inventory, the AI cannot access or modify the database inventory even if the user asks it to. Unauthorized actions are rejected by the AAP API.

> Warning: Enabling mcp_allow_write_operations=true gives the AI agent autonomy to modify your AAP environment. Large Language Models occasionally misinterpret prompts. Red Hat recommends starting with read-only access and only enabling read-write after evaluating your security posture.

Data Visibility and What the LLM Sees

When the MCP server calls the AAP API, the response is forwarded to the AI client and included in the LLM's conversation context. Understand what is and is not protected:

Always protected (masked by the AAP API before MCP receives them):

• Credential passwords
• Secret keys and API tokens stored in the AAP credential system
• SSH private keys
• Vault credentials

• IP addresses, DNS names, hostnames
• Inventory variables (host vars, group vars)
• Job template extra variables
• Job output and logs
• Credential names, types, and usernames (non-secret metadata)
• Survey answers and workflow variable prompts

See also: Ansible MCP Server: AI-Driven Automation with Model Context Protocol (Complete Guide)

Creating an API Token

Each AAP user creates their own API token to connect their AI tool to the MCP server. The AI agent inherits that user's permissions.

In the AAP UI

1. Navigate to Access Management → Users
2. Click your username → Tokens tab
3. Click Create token
4. Fill in:
5. Application: leave blank for a Personal Access Token (PAT), or select an OAuth application
6. Description: e.g., MCP server — Claude Desktop
7. Scope: Write (for read-write MCP) or Read (for read-only MCP)
8. Click Create token
9. Copy and save the token immediately — it is displayed only once

Via the AAP API

# Create a PAT via the API (useful for service accounts)
curl -sk -X POST https://aap.example.com/api/controller/v2/tokens/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -d '{
    "description": "MCP server service account token",
    "scope": "write"
  }' | python3 -m json.tool

Connecting Your AI Client

Configure your AI client by adding entries to its mcp.json file — one entry per toolset you want to enable. Use the MCP server URL from the deployment step and the API token you just created.

> Important: Keep MCP server names under 20 characters. AI agents combine the server name with the tool name to build unique identifiers, and most agents enforce a 64-character combined limit.

Full mcp.json Example (All Six Toolsets)

{
  "mcpServers": {
    "aap-jobs": {
      "type": "http",
      "url": "https://aap.example.com:8448/job_management/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AAP_MCP_TOKEN}"
      }
    },
    "aap-inventory": {
      "type": "http",
      "url": "https://aap.example.com:8448/inventory_management/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AAP_MCP_TOKEN}"
      }
    },
    "aap-monitor": {
      "type": "http",
      "url": "https://aap.example.com:8448/system_monitoring/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AAP_MCP_TOKEN}"
      }
    },
    "aap-users": {
      "type": "http",
      "url": "https://aap.example.com:8448/user_management/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AAP_MCP_TOKEN}"
      }
    },
    "aap-security": {
      "type": "http",
      "url": "https://aap.example.com:8448/security_compliance/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AAP_MCP_TOKEN}"
      }
    },
    "aap-platform": {
      "type": "http",
      "url": "https://aap.example.com:8448/platform_configuration/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AAP_MCP_TOKEN}"
      }
    }
  }
}

Set AAP_MCP_TOKEN in your shell environment (or your AI client's secrets manager):

export AAP_MCP_TOKEN="your-api-token-here"

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "aap-jobs": {
      "type": "http",
      "url": "https://aap.example.com:8448/job_management/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

VS Code (GitHub Copilot / Continue / Cline)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "aap-jobs": {
      "type": "http",
      "url": "https://aap.example.com:8448/job_management/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AAP_MCP_TOKEN}"
      }
    }
  }
}

Verifying the Connection

In your AI agent's chat window, send:

What MCP tools are available for my Ansible Automation Platform?

The agent should return a list of tools from the enabled toolsets. Then try:

Give me a list of my Ansible Automation Platform job templates.

Example Natural Language Workflows

Once connected, your AI agent can handle queries like:

Operators (read-only):

• "Show me all job templates tagged with 'production'"
• "What's the status of the last database backup job?"
• "Which hosts are in the web-servers inventory group?"
• "Why did the patching workflow fail last night?"

• "Launch the deploy-web-app job template in the Production organization"
• "Create a new user jsmith in the Development team with read-only access"
• "Show me all users who have access to the production inventory"

Troubleshooting

SSL certificate validation fails (OCP)

Symptom: SELF_SIGNED_CERT_IN_CHAIN errors, MCP server cannot connect to AAP.

Fix: Create a CA secret and reference it in the AnsibleMCPServer CR (see Custom CA Certificate above).

400 Bad Request from MCP server (containerized)

Symptom: AI agent requests fail with HTTP 400.

Cause: AAP is using a self-signed certificate and the MCP server cannot validate it.

Fix: Set mcp_ignore_certificate_errors=true in the inventory and rerun the installer. For OCP:

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

406 Status Code on Job Output

Symptom: Retrieving job stdout fails with HTTP 406.

Cause: AAP rejects requests for non-JSON output format.

Fix: Instruct your AI tool to request JSON format explicitly: "Show me the job output for job 42 in JSON format." The AI can then transform it to your preferred display format.

Permissions not taking effect after changing allow_write_operations

Symptom: Changed allow_write_operations but behavior hasn't changed.

Fix: On OCP, changing the permission after deployment requires deleting and recreating the AnsibleMCPServer CR. Navigate to Ansible Automation Platform portal → Resources → AnsibleMCPServer, select the active instance (identified by the -mcp suffix), and delete it. The operator recreates it with the updated permission.

On containerized: rerun the installer with the updated inventory.

Automation Intelligent Assistant (Chatbot UI)

In addition to the external MCP server, AAP 2.7 includes an automation intelligent assistant — an LLM-backed chatbot embedded directly in the AAP UI. Unlike the external MCP server (which connects your preferred AI tool to AAP), the intelligent assistant is AAP's own chat interface.

Deploy it on OCP by creating a chatbot configuration secret and enabling Lightspeed in the operator:

# chatbot-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: chatbot-configuration-secret
  namespace: ansible-automation-platform
stringData:
  chatbot_llm_provider_type: openai
  chatbot_url: https://api.openai.com/v1
  chatbot_model: gpt-4o-mini
  chatbot_token: <your-openai-api-key>

oc apply -f chatbot-secret.yaml -n ansible-automation-platform

Then enable Lightspeed in the AAP operator CR:

spec:
  lightspeed:
    disabled: false
    chatbot_config_secret_name: chatbot-configuration-secret

After a few minutes, the chat icon appears in the top-right corner of the AAP UI. The intelligent assistant answers questions about your AAP environment using the configured LLM.

Related Articles

• Ansible Automation Platform MCP Server: Now Generally Available in AAP 2.7
• Bring Your Own Knowledge to Ansible Lightspeed
• Red Hat Ansible Automation Platform 2.7: What's New
• AAP 2.7: Removing Direct API Access — Migration Guide