aap

AAP MCP Service exposes a set of MCP endpoints that bridge Ansible Automation Platform (AAP) APIs via OpenAPI specifications. It supports multiple toolsets and services (controller, galaxy, gateway, eda) and can load OpenAPI specs from remote URLs or local files. You can interact with the MCP endpoints to read or invoke operations exposed by AAP, and you can tailor access using custom toolsets and session-based authentication. Use the provided toolsets to assemble collections of related operations (e.g., job management, inventory management, system monitoring) and restrict access based on user permissions.

To get started, configure your aap-mcp.yaml file (or use environment variables) to point to your AAP instance, enable the desired services, and define any custom toolsets. Start the service with npm start (production) or npm run dev (development), then use the MCP endpoints under /mcp or /mcp/{toolset} to interact with AAP capabilities. For secure access, pass your AAP token in the Authorization header as a Bearer token, or set BEARER_TOKEN_OAUTH2_AUTHENTICATION in the environment and initialize a session per the MCP’s session flow. You can also attach Claude to manage tokens and toolsets as described in the README.

The service will generate tools from the AAP OpenAPI specs for components such as EDA, Controller, Gateway, and Galaxy, with visibility governed by your configured toolsets and user permissions.

Prerequisites

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

Install and run locally

1. Clone the repository and install dependencies:

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

2. Build the project (if applicable):

npm run build

3. Create a copy of the sample configuration and customize it:

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

4. Start the service (production):

npm start

Development mode:

npm run dev

5. (Optional) Run in a container (Docker) if desired:

# Example Docker command:
# docker run -i your-image-name

Tips and common issues:

• Environment variables take precedence over YAML config. Set BASE_URL and BEARER_TOKEN_OAUTH2_AUTHENTICATION (or MCP_PORT) to override defaults.
• If you enable metrics, you can access Prometheus metrics at http://localhost:3000/metrics when enabled.
• Ensure the required AAP access tokens have permissions for the configured services; otherwise, authentication failures will occur.
• Use the toolsets section of your configuration to group related API calls. This is especially helpful for limiting user permissions via role-based access.
• When loading OpenAPI specs from local files, ensure the path is correct and the file is valid OpenAPI JSON/YAML.
• If you encounter issues with tool availability, verify that the tokens grant access to the intended services and that the services are enabled in the configuration.