The mcp-demo repository provides integration guides for connecting AI assistants to Ansible Automation Platform (AAP) through the Model Context Protocol (MCP). Written primarily in Shell, this repository serves as a practical demonstration of how to bridge AI tools with AAP's automation capabilities.
The core offering is setup documentation for three distinct AI assistant platforms: Cursor IDE, Claude Desktop, and Microsoft Copilot Studio. Each platform receives tailored configuration guidance reflecting its specific requirements and strengths. Cursor IDE and Claude Desktop use JSON-based configurations with environment variable support and can bypass SSL validation for development purposes. Microsoft Copilot Studio takes a different approach, requiring valid SSL certificates and using OpenAPI YAML with Power Apps Custom Connectors for authentication via API keys rather than bearer tokens.
The repository documents a single AAP MCP server that exposes six separate toolset endpoints covering distinct operational domains. Job Management handles execution and monitoring of automation jobs. Inventory Management provides control over hosts, groups, and inventories. System Monitoring tracks platform health and metrics. User Management handles users, teams, and organizations. Security and Compliance endpoints access security policies and audit logs. Platform Configuration manages platform settings. All six endpoints operate on the same ports (8448 or 8449 depending on deployment configuration).
Once configured, users can interact with AAP through natural language queries. The documentation provides concrete examples such as listing recent jobs, displaying inventory hosts, checking platform status, launching specific job templates, querying host counts by operating system, and retrieving failed jobs within time windows. This natural language interface removes the need for direct API calls or command-line interaction.
The repository includes a .cursorrules file that provides AI context about Ansible Automation Platform best practices, helping assistants understand inventory organization patterns, host variables, OS detection, API pagination, resource relationships, and common AAP workflows. This contextual guidance improves the quality of AI-assisted interactions with the platform.
Security considerations are explicitly addressed throughout the documentation. The repository includes a .gitignore entry for mcp_key.txt to prevent accidental token commits. Documentation emphasizes storing API tokens securely through environment variables or key vaults, rotating tokens regularly, using proper SSL certificates in production, and applying least-privilege principles to token permissions. The SSL certificate handling differs by platform, with Cursor and Claude allowing development-mode bypasses while Copilot Studio mandates valid certificates, with Let's Encrypt recommended as an option.
Prerequisites for using the repository include Ansible Automation Platform 2.6 or later with the MCP server already deployed, a valid API token from the AAP instance, and one of the three supported AI assistant platforms. The quick start section directs users to deployment guides for RHEL and OpenShift environments, documentation for obtaining API tokens, and platform-specific setup directories.
The repository structure organizes setup guides into separate directories for each platform, with platform-specific troubleshooting documentation. A video tutorial demonstrating five real-world use cases with the AAP MCP server is referenced, providing visual guidance for implementation. The repository welcomes contributions through standard fork-and-pull-request workflows, with issue reporting directed to appropriate repositories depending on whether problems relate to the AAP MCP server itself or specific platform integrations.
