Ansible Development Tools MCP Server - API Endpoint Documentation¶

{
  "name": "ansible-mcp-server",
  "version": "0.1.0",
  "protocolVersion": "1.0"
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<tool_name>",
    "arguments": {
      // Tool-specific parameters
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "<response_content>"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error: <error_message>"
      }
    ],
    "isError": true
  }
}

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "$defs": {
    "v3": {
      "type": "object",
      "properties": { /* v3 schema properties */ },
      "required": ["version"]
    },
    "v1": {
      "type": "object",
      "properties": { /* v1 schema properties */ },
      "required": ["version"]
    },
    "TYPE_StringOrListOfStrings": {
      "oneOf": [
        { "type": "string" },
        { "type": "array", "items": { "type": "string" } }
      ]
    }
  },
  "oneOf": [
    { "$ref": "#/$defs/v3" },
    { "$ref": "#/$defs/v1" }
  ]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/read",
  "params": {
    "uri": "schema://execution-environment"
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "sample://execution-environment"
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/read",
  "params": {
    "uri": "rules://execution-environment"
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/read",
  "params": {
    "uri": "guidelines://ansible-content-best-practices"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "zen_of_ansible",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "1. Ansible is not Python.\n2. YAML sucks for coding.\n3. Playbooks are not for programming.\n..."
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "ansible_content_best_practices",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[Complete best practices guidelines document in Markdown format]"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_available_tools",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Available Ansible Development Tools MCP Server tools\n\n- zen_of_ansible\n- ansible_content_best_practices\n- list_available_tools\n- ansible_lint\n..."
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "ade_environment_info",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Environment Information\n==================================================\n\nWorkspace: /workspace\nPython: Python 3.11.5\nVirtual Environment: /workspace/venv (not active)\n\nAnsible Tools:\n  • Ansible: ansible [core 2.15.0]\n  • Ansible Lint: ansible-lint 6.14.3\n\nDevelopment Tools:\n  • ADE: Installed\n  • ADT: Installed\n\nInstalled Collections:\n  • amazon.aws 6.0.0\n  • ansible.utils 2.10.0\n  • community.general 7.0.0"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "ade_setup_environment",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "ade_setup_environment",
    "arguments": {
      "envName": "ansible-dev",
      "pythonVersion": "3.11",
      "collections": ["amazon.aws", "ansible.utils"],
      "installRequirements": true
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Checking for conflicting packages...\nNo conflicting packages detected\n\nChecking ansible-lint status...\nansible-lint is working properly\nVersion: ansible-lint 6.14.3\n\nVirtual environment created successfully\nInstalling Ansible tools in virtual environment...\nansible-lint and ansible-core installed in virtual environment\nCollections installed successfully\n\nTo activate the virtual environment, run:\n   source /workspace/ansible-dev/bin/activate\n\nTo deactivate the virtual environment, run:\n   deactivate\n\nPerforming final verification...\nFinal verification passed - ansible-lint is working in virtual environment"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "adt_check_env",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "ADT (ansible-dev-tools) is already installed"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "ADT (ansible-dev-tools) installed successfully"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Failed to install ADT. pip error: [error], pipx error: [error]"
      }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "ansible_create_playbook",
    "arguments": {
      "name": "my-playbook",
      "path": "/workspace/playbooks"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "ansible-creator init playbook completed successfully\n\nOutput:\n[ansible-creator output]"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error creating playbook: [error message]\n"
      }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "ansible_create_collection",
    "arguments": {
      "name": "acme.my_collection",
      "path": "/workspace/collections"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "ansible-creator init collection completed successfully\n\nOutput:\n[ansible-creator output]"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error creating collection: [error message]\n"
      }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "ansible_lint",
    "arguments": {
      "filePath": "/workspace/playbooks/deploy.yml"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "ansible_lint",
    "arguments": {
      "filePath": "/workspace/playbooks/deploy.yml",
      "fix": true
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Linting completed for file: /workspace/playbooks/deploy.yml\nNo issues found."
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Linting results for file: /workspace/playbooks/deploy.yml\n\n❌ Found 2 issue(s):\n\n1. [yaml] on line 5 of /workspace/playbooks/deploy.yml\n   Message: line too long (120 > 80 characters)\n\n2. [name[missing]] on line 10 of /workspace/playbooks/deploy.yml\n   Message: All tasks should be named\n\n"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error: File not found: /workspace/playbooks/deploy.yml\n"
      }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "define_and_build_execution_env",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 12,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error: 'baseImage' and 'tag' are required fields.\n\n**Please provide the following critical information:**\n- **baseImage**: The base container image (e.g., 'quay.io/fedora/fedora-minimal:41', 'quay.io/centos/centos:stream10')\n- **tag**: The tag/name for the resulting image (e.g., 'my-ee:latest')\n\n**Optional fields:**\n- **collections**: Array of Ansible collection names (e.g., ['amazon.aws', 'ansible.utils'])\n- **systemPackages**: Array of system packages (e.g., ['git', 'vim'])\n- **pythonPackages**: Array of Python packages (e.g., ['boto3', 'requests'])\n- **destinationPath**: Directory path for the file (defaults to workspace root)"
      }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "define_and_build_execution_env",
    "arguments": {
      "baseImage": "quay.io/fedora/fedora-minimal:41",
      "tag": "my-ee:latest",
      "collections": ["amazon.aws"],
      "systemPackages": ["git"]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 13,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "**Please generate the execution-environment.yml file using the following prompt:**\n\n```\nYou are generating an Ansible Execution Environment (EE) definition file.\n\nRULES AND GUIDELINES:\nee-rules.md content\n\nSAMPLE EE FILE STRUCTURE:\nexecution-environment-sample.yml content\n\nUSER REQUIREMENTS:\n- Base Image: quay.io/fedora/fedora-minimal:41\n- Tag: my-ee:latest\n- Collections: amazon.aws\n- System Packages: git\n\nGenerate a valid execution-environment.yml file following ALL rules...\n```\n\n**After generating the YAML, call this tool again with the 'generatedYaml' parameter containing the generated YAML content.**"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "define_and_build_execution_env",
    "arguments": {
      "baseImage": "quay.io/fedora/fedora-minimal:41",
      "tag": "my-ee:latest",
      "collections": ["amazon.aws"],
      "systemPackages": ["git"],
      "generatedYaml": "version: 3\nimages:\n  base_image:\n    name: quay.io/fedora/fedora-minimal:41\ndependencies:\n  galaxy: requirements.yml\n  python: requirements.txt\n  system: bindep.txt\nadditional_build_steps:\n  prepend_base:\n    - RUN dnf install -y git\n"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 14,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Execution environment file created successfully at /workspace/execution-environment.yml\n\nThe generated file has been validated against the execution environment schema.\n\nGenerated execution-environment.yml:\n```yaml\nversion: 3\nimages:\n  base_image:\n    name: quay.io/fedora/fedora-minimal:41\ndependencies:\n  galaxy: requirements.yml\n  python: requirements.txt\n  system: bindep.txt\nadditional_build_steps:\n  prepend_base:\n    - RUN dnf install -y git\n```\n\n**To build the execution environment image, run:**\n```bash\nansible-builder build --file /workspace/execution-environment.yml --context /workspace/context --tag my-ee:latest -vvv\n```\n\n**Note:** Before building, ensure you have:\n- ansible-builder installed (install via: pip install ansible-builder or via ADT)\n- A container runtime (podman or docker) installed and running\n- Sufficient permissions to build container images\n\n**Additional commands you might want to use:**\n- Create build context only: `ansible-builder create --file /workspace/execution-environment.yml --context /workspace/context`\n- Build with custom tag: `ansible-builder build --file /workspace/execution-environment.yml --context /workspace/context --tag your-custom-tag`\n\n**AGENT INSTRUCTIONS:**\n--Ask the user if the agent should run the command for them\n--If yes, run the build command and provide feedback\n--When the build completes summarize the image and build results\n--If the build fails, fix the issue and re-run the build"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 14,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Execution environment file created successfully at /workspace/execution-environment.yml\n\n**Schema Validation Warnings:**\n- /dependencies/galaxy should be object or string\n- /images missing required property 'base_image.name'\n\nThe file was generated but may not fully comply with the schema. Please review.\n\n[rest of response]"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "tools/call",
  "params": {
    "name": "ansible_navigator",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 15,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Ansible Navigator - Features & Usage Guide\n\n## Output Modes\n- **stdout** (used by this tool) - Direct terminal output\n- **interactive** - Text-based UI for exploring execution\n\n## Execution Environments\n- **VM/Podman** (default) - Runs in isolated container\n- **Local Ansible** (with --ee false) - Uses local installation\n..."
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 16,
  "method": "tools/call",
  "params": {
    "name": "ansible_navigator",
    "arguments": {
      "userMessage": "run play1.yml"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 17,
  "method": "tools/call",
  "params": {
    "name": "ansible_navigator",
    "arguments": {
      "userMessage": "run playbooks/deploy.yml",
      "mode": "stdout",
      "environment": "auto",
      "disableExecutionEnvironment": false
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 16,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "ansible-navigator run completed for file: /workspace/playbooks/play1.yml:\n\n**Playbook executed successfully!**\n\n**Configuration Used:**\n- **Output Mode:** stdout (default - shows full output)\n- **Environment:** auto (auto-detected) → /workspace/venv\n- **Execution Environment:** disabled (using local Ansible)\n\n**What This Means:**\n- Detected virtual environment, so execution environment was automatically disabled\n- Using your local Ansible installation from the venv\n\n**Want to customize? Just ask me to:**\n- \"Run with minimal output\" → Uses stdout-minimal mode\n- \"Run in interactive mode\" → Uses interactive TUI\n- \"Use venv\" → Forces virtual environment\n- \"Use system ansible\" → Forces system PATH\n- \"Disable execution environment\" → Uses local Ansible (no Podman)\n\nOutput:\n[ansible-navigator output]"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 16,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error: File not found or not accessible: /workspace/play1.yml. ..."
      }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 16,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "ansible-navigator is not available in PATH or virtual environments.\n\nPATH: /usr/local/bin:/usr/bin:/bin\n\nChecked virtual environments in: /workspace\nCommon venv names checked: ansible-dev, venv, .venv, virtualenv, .virtualenv, env, .env\n\nPlease install ansible-navigator:\n  pip install ansible-navigator\n\nOr ensure it's installed and accessible in your PATH or a virtual environment."
      }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 16,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "ansible-navigator exited with code 1: Container engine issue detected.\n\nError output:\nCannot connect to Podman. Is Podman VM running?\n\n**Issue:** Podman VM not running.\n\n**Note:** Tool will auto-retry with local Ansible (execution environment disabled).\n\n**To use Podman:** Run `podman machine start`"
      }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": <number>,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error: <error_message>\n[additional context]"
      }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Tool 'invalid_tool' not found. Available tools: zen_of_ansible, ansible_content_best_practices, list_available_tools, ansible_lint, ..."
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "❌ Cannot use tool 'ansible_lint' because required dependencies are missing:\n\n  - ansible-lint (Ansible playbook linter)\n    Install: pip install ansible-lint\n\nPlease install or update the dependencies and try again."
      }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "❌ Cannot use tool 'ansible_lint' because version requirements are not met:\n\n  - ansible-lint (Ansible playbook linter)\n    Current version: 5.4.0\n    Required version: 6.0.0 or higher\n    Update: pip install ansible-lint\n\nPlease install or update the dependencies and try again."
      }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error: File not found: /path/to/file.yml"
      }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error: 'baseImage' and 'tag' are required fields.\n\n**Please provide the following critical information:**\n- **baseImage**: The base container image\n- **tag**: The tag/name for the resulting image"
      }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error: Failed to start ansible-lint process. Is it installed and in your PATH? Details: [error details]"
      }
    ],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error: Failed to parse JSON output from ansible-lint. Raw output: [output]"
      }
    ],
    "isError": true
  }
}