AnsibleByExample

Ansible MCP Inventory Management Example: Query Hosts with Natural Language

Beginner
2024-01-014By Luca Berton

Lesson 1 of 15 in Foundations

Ansible Foundations to Production — full curriculum
  1. 1. Introduction to Ansible and Automation
  2. 2. Installing and Configuring Ansible
  3. 3. Running Ad-Hoc Commands
  4. 4. Writing Your First Playbook
  5. 5. Understanding and Using Modules
  6. 6. Variables and Facts
  7. 7. Conditionals and Loops
  8. 8. Handlers and Idempotency
  9. 9. Structuring Projects with Roles
  10. 10. Inventory Management
  11. 11. Using Ansible Vault for Secrets
  12. 12. Debugging and Troubleshooting
  13. 13. Real-World Automation Examples
  14. 14. Final Project: Deploy a Web Server
  15. 15. Bonus - What's Next with Ansible?
View path overview →

Red Hat's hosted MCP (Model Context Protocol) Server for Ansible Automation Platform is currently a Tech Preview. It maps AAP's REST API to 107 declarative tools across six tool sets, and one of those sets — inventory management — is built specifically so an LLM agent can answer "what hosts do I have?" without you writing a single API call. Here's a runnable example plus the natural-language flow behind it.

---
- name: Verify inventory state exposed via AAP MCP inventory tools
  hosts: localhost
  gather_facts: false
  vars:
    aap_inventory_name: "production"
    expected_group: "webservers"
  tasks:
    - name: Query inventory hosts through the AAP API (what the MCP inventory tool calls under the hood)
      ansible.builtin.uri:
        url: "https://aap.example.com/api/v2/inventories/{{ inventory_id }}/hosts/"
        method: GET
        headers:
          Authorization: "Bearer {{ aap_bearer_token }}"
        return_content: true
      register: aap_hosts
      no_log: true

    - name: Fail if expected group has no hosts
      ansible.builtin.assert:
        that:
          - aap_hosts.json.count > 0
        fail_msg: "No hosts found in inventory {{ aap_inventory_name }}"
        success_msg: "{{ aap_hosts.json.count }} hosts confirmed in {{ aap_inventory_name }}"

What the MCP inventory tools actually do

The playbook above is the plain-Ansible equivalent of a single sentence typed into an MCP-connected client such as Cursor: "list the hosts in the production inventory." Behind that sentence, the MCP Server's inventory management tool set (7 tools total) handles:

  • Querying hosts by inventory or group
  • Listing groups and their host membership
  • Reading host and group variables (including inherited vars)
  • Filtering hosts by status, facts, or custom fields

At Red Hat Tech Day Netherlands 2026 in Bunnik, Fred van Zwieten demoed this live from Cursor IDE, connected to the MCP Server over plain HTTP with Bearer-token authentication. The equivalent of the query above returned a structured, chat-native answer — no dashboard click-through, no manual curl against /api/v2/.

A representative transcript from that class of query looks like this:

User:  Show me the last 5 jobs from AAP.
Agent: [calls job-management tool: list_recent_jobs(limit=5)]
       Here are the last 5 jobs:
       1. Paint Job Template — failed — 2026-06-03 09:12
       2. Deploy Webservers — successful — 2026-06-03 08:47
       3. Patch Compliance Scan — successful — 2026-06-03 08:30
       4. Backup Rotation — successful — 2026-06-02 23:00
       5. Nightly Inventory Sync — successful — 2026-06-02 22:00

User:  Which hosts are in the webservers group for that Deploy job's inventory?
Agent: [calls inventory-management tool: list_group_hosts(inventory="production", group="webservers")]
       webservers (4 hosts): web-01, web-02, web-03, web-04
       All hosts report status "active".

The point isn't that this saves typing — it's that the MCP Server enforces AAP's own permission model and validation on every call. The same demo showed the agent attempting to launch a "Paint" job template with an invalid survey value ("Purple"); AAP's survey validation rejected it outright, proving the AI cannot bypass guardrails just because it's talking to the platform conversationally.

Notes

  • Inventory tools are read/query-oriented in this tool set (7 tools) — they don't replace ansible-inventory or dynamic inventory plugins, they sit on top of AAP's existing inventory API.
  • Job management (25 tools) and inventory management (7 tools) are separate tool sets; an agent doing root-cause analysis — as shown live, tracing a failed job to a typo (caap instead of aap in an ec2_vpc_name variable) and a race condition from two parallel job runs — pulls from both, reading job stdout/events and cross-referencing inventory variables.
  • Authentication is Bearer-token over HTTP; treat that token like any other AAP credential — scope it and rotate it.
  • This is Tech Preview: expect tool signatures and counts to shift before GA.

Takeaway: the MCP Server's inventory tool set turns "what hosts are in this group?" into a governed API call an LLM can make safely, with AAP's own validation and RBAC still doing the enforcement.

References

All Tutorials