AAP MCP Service

A Model Context Protocol (MCP) service that provides access to Ansible Automation Platform (AAP) APIs through OpenAPI specifications.

Prerequisites

• Node.js 22 or higher
• Access to an Ansible Automation Platform instance
• Valid AAP authentication token

Installation

1. Clone the repository:

git clone <repository-url>
cd aap-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

The service uses a YAML configuration file (aap-mcp.yaml) for flexible configuration management. Copy the sample configuration to get started:

cp aap-mcp.sample.yaml aap-mcp.yaml

Configuration File Structure

The configuration file supports the following options:

Basic Settings

# Disable HTTPS certificate validation for development (optional, defaults to false)
ignore-certificate-errors: true

# AAP base URL (optional, defaults to https://localhost)
# Lower priority than BASE_URL environment variable
base_url: "https://your-aap-instance.com"

Service Configuration

Configure which AAP services to load and how to access their OpenAPI specifications:

services:
  - name: controller
    url: "https://custom-controller.example.com/api/v2/schema/" # Optional: custom URL
    local_path: "data/controller-schema.json" # Optional: local file path
    enabled: true # Optional: enable/disable service

  - name: galaxy
    url: "https://custom-galaxy.example.com/api/v3/openapi.json"
    local_path: "data/galaxy-schema.json"
    enabled: true

  - name: gateway
    # Uses default URLs if not specified
    enabled: true

  - name: eda
    enabled: false # Disable this service

Service Configuration Rules:

• name: Must be one of: controller, galaxy, gateway, eda
• url: Custom OpenAPI specification URL (optional, uses service defaults if not specified)
• local_path: Path to local OpenAPI file (optional, if set, loads from file instead of URL)
• enabled: Enable/disable the service (optional, defaults to true)

Toolsets

Define custom toolsets that group related functionality:

toolsets:
  job_management:
    - controller.job_templates_launch_create
    - controller.workflow_job_templates_launch_create
    - controller.jobs_read
    - controller.workflow_jobs_read

  inventory_management:
    - controller.inventories_list
    - controller.hosts_list
    - controller.groups_list

  system_monitoring:
    - controller.ping_list
    - controller.config_list
    - gateway.activitystream_list

Environment Variables

Environment variables take precedence over configuration file settings:

# AAP base URL (highest priority)
BASE_URL=https://your-aap-instance.com

# MCP server port (optional, defaults to 3000)
MCP_PORT=3000

# Change this to true to get access to the write operations
#ALLOW_WRITE_OPERATIONS=true

Configuration Priority

Configuration values are resolved in the following order (highest to lowest priority):

1. Environment Variables (e.g., BASE_URL, BEARER_TOKEN_OAUTH2_AUTHENTICATION)
2. Configuration File (aap-mcp.yaml)
3. Default Values (built-in defaults)

User Toolsets

The service supports role-based access control through user toolsets.

Usage

Starting the Service

1. Configure the service by copying and editing the sample configuration:

cp aap-mcp.sample.yaml aap-mcp.yaml
# Edit aap-mcp.yaml with your AAP instance details

2. Start the service:

# Development mode
npm run dev

# Production mode
npm start

MCP Endpoints

The service provides several MCP endpoints:

• Standard MCP: /mcp (POST, GET, DELETE)
• Toolset-specific: /mcp/{toolset} where toolset matches your configured toolsets

Authentication

Include your AAP token in the Authorization header:

Authorization: Bearer your_aap_token_here

Session Management

The service

... View full README on GitHub