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

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

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Build the project:

npm run build

Create a .env file in the root directory with the following configuration:

# AAP Gateway Authentication token (required)
BEARER_TOKEN_OAUTH2_AUTHENTICATION=your_aap_token_here

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

The service defaults to http://localhost:44926 as the AAP base URL. To change this, modify the BASE_URL constant in src/index.ts:24.

The service supports three user categories that determine which tools are available:

• Anonymous: No tools available (default for unauthenticated users)
• User: Limited set of read-only tools for EDA, Controller, and Galaxy services
• Admin: Full access to all tools including create, update, and delete operations

Categories are automatically determined based on user permissions from the AAP token, but can be overridden using category-specific endpoints.

# Development mode
npm run dev

# Production mode
npm start

The service provides several endpoints:

• Standard MCP: /mcp (POST, GET, DELETE)
• Category-specific: /{category}/mcp where category is anonymous, user, or admin

Include your AAP token in the Authorization header:

Authorization: Bearer your_aap_token_here

The service uses session-based authentication:

1. Initialize a session with a POST request containing your token
2. Use the returned Mcp-Session-Id header for subsequent requests
3. The service validates tokens and determines user permissions automatically

claude mcp add poc-aap-mcp -t http http://localhost:3000/mcp -H 'Authorization: Bearer your_aap_token_here'

1. Configure the token in .env:

BEARER_TOKEN_OAUTH2_AUTHENTICATION=your_aap_token_here

2. Start the service:

npm run dev

3. Register with Claude:

claude mcp add poc-aap-mcp -t http http://localhost:3000/mcp

To override automatic category detection:

# Force admin category
claude mcp add poc-aap-mcp -t http http://localhost:3000/admin/mcp

# Force user category
claude mcp add poc-aap-mcp -t http http://localhost:3000/user/mcp

# Force anonymous category (no auth required)
claude mcp add poc-aap-mcp -t http http://localhost:3000/anonymous/mcp

The service generates tools from AAP OpenAPI specifications for:

• EDA (Event-Driven Ansible): Activations, projects, rulebooks, decision environments
• Controller: Jobs, job templates, inventories, projects, organizations
• Gateway: User and team management, organizations, role definitions
• Galaxy: Collection management and versions

Tool availability depends on your user category. A complete list of tools with sizes is generated in tool_list.csv when the service starts.

• src/index.ts: Main service implementation
• .env: Environment configuration
• package.json: Dependencies and scripts
• tool_list.csv: Generated tool list (created at runtime)

• Automatic OpenAPI specification loading from AAP services
• Role-based access control through user categories
• Session management with token validation
• Tool filtering based on user permissions
• CORS support for web clients

To add support for additional AAP services:

1. Add the OpenAPI specification URL to the specUrls array in loadOpenApiSpecs()
2. Implement a reformatFunc to standardize tool names and paths
3. Update the category definitions to include relevant tools

Build the image with:

podman build -f Containerfile . -t aap-mcp

And run it with:

podman run -e BASE_URL=http://your-aap-installation localhost/aap-mcp

1. Authentication failed: Verify your AAP token is valid and has appropriate permissions
2. No tools available: Check that your token provides the expected user permissions
3. Connection refused: Ensure AAP is running and accessible at the configured base URL
4. Missing dependencies: Run npm install to install required packages

The service provides detailed console logging for:

• OpenAPI specification loading
• Session initialization and cleanup
• Tool filtering by category
• API request execution

GPL-3.0-or-later