Create and integrate custom MCP Servers in execution environments

Before including an MCP server in your execution environment:

• Review the source code: MCP servers can execute arbitrary operations on your infrastructure. Audit the server code before installing, especially for servers from community or third-party sources.
• Pin to specific versions: Use explicit version numbers in your registry metadata rather than latest.

  cfn_mcp_version: "1.0.19"

  This ensures reproducible builds and prevents unexpected behavior from upstream changes.

• Use read-only mode where available: Many MCP servers support a read-only flag that prevents mutating operations:

    cfn_mcp_registry:
      - name: "awslabs.cfn-mcp-server"
        type: "stdio"
        lang: "pypi"
        args: ["--readonly"]
        description: "AWS CloudFormation MCP Server (read-only)"

• Review required permissions: Understand what permissions each MCP server needs. For example, the CloudFormation MCP server requires cloudcontrol:* and cloudformation:* IAM permissions. Grant only the minimum permissions needed.

Understand the MCP builder framework

Copy link

ansible.mcp_builder collection provides a reusable framework for installing MCP servers inside execution environments. Rather than manually scripting installation steps in your container build, you define a role with metadata about your MCP server, and the framework handles the rest.

To automate the installation and lifecycle management of your servers, you must understand how the ansible.mcp_builder framework operates.

The framework consists of three main components:

• The common role (ansible.mcp_builder.common) provides shared installation logic for MCP servers. Based on the language specified in your role's registry metadata, the common role automatically:
  • Installs the appropriate language runtime (Go, Node.js, or Python/uv) if not already present.
  • Downloads and installs the MCP server package from the correct source (PyPI, npm, or Git).
  • Generates a unified manifest file (/opt/mcp/mcpservers.json) listing all available MCP servers.
  • Creates the mcp_manage utility for listing, querying, and running installed MCP servers
• Your custom role defines metadata about the MCP server you want to install. At minimum, it includes:
  • A registry variable that specifies the server name, transport type, language, and description.
  • A tasks file that invokes the common role's install_manager and generate_manifesttasks.
• A playbook ties your custom role into the build process. This playbook is called by ansible-builder during the execution environment container build.

Select an installation method

All installed MCP servers are registered in /opt/mcp/mcpservers.json. This file follows the mcp.json format established by VS Code, with each server entry containing:

 {
    "server-name": {
        "type": "stdio",
        "command": "/opt/mcp/bin/server-name",
        "args": [],
        "description": "Description of the MCP server"
    }
}

For remote (HTTP-based) MCP servers, the entry uses url instead of command:

{
    "server-name": {
        "type": "http",
        "url": "https://remote-server:12345",
        "args": [],
        "description": "Remote MCP server"
    }
}

When multiple playbooks install MCP servers into the same execution environment, the manifest merges automatically. Each subsequent installation appends its entries to the existing manifest without overwriting previous entries.

To include both dev preview MCP servers from ansible.mcp_builder (such as aws_ccapi_mcp) and your custom role in the same execution environment, chain multiple playbook calls in additional_build_steps:

additional_build_steps:
  append_final: |
    RUN ansible-playbook ansible.mcp_builder.install_mcp -e mcp_servers=aws_ccapi_mcp
    RUN ansible-playbook myorg.mcp_cfn.install_cfn_mcp
 

The manifest file merges automatically. The second playbook appends its entries to the existing mcpservers.json created by the first.

Test and verify your MCP server

Copy link

Verify your MCP server configuration by listing registered servers, inspecting the generated JSON manifest, and testing container connectivity with Podman.

Testing your MCP server in the execution environment

After building the execution environment, verify that your MCP server is correctly installed and functional.

List the MCP servers registered in the manifest:

podman run --rm my-cfn-mcp-ee:latest mcp_manage list

Expected output:

Available MCP servers:
  - awslabs.cfn-mcp-server (type: stdio, path: /opt/mcp/bin/awslabs.cfn-mcp-server)

Verify the manifest file

Inspect the generated manifest directly:

Expected output:

{
    "awslabs.cfn-mcp-server": {
        "args": [],
        "command": "/opt/mcp/bin/awslabs.cfn-mcp-server",
        "description": "AWS CloudFormation MCP Server - manage AWS resources via Cloud Control API",
        "type": "stdio"
    }
}
 

Test server connectivity

Run the MCP server with --help to confirm it is callable:

For servers that require credentials (such as AWS), pass environment variables:

podman run --rm \
  -e AWS_PROFILE=my-profile \
  -e AWS_REGION=us-east-1 \
  -v ~/.aws:/home/runner/.aws:ro \
  my-cfn-mcp-ee:latest \
  mcp_manage run awslabs.cfn-mcp-server

Add a remote server to your role

To define a remote MCP server, set the type to http in your registry metadata:

 # roles/cfn_mcp/defaults/main.yml (remote mode example)
---
cfn_mcp_registry:
  - name: "awslabs.cfn-mcp-server"
    type: "http"
    lang: "pypi"
    path: "https://my-mcp-host.example.com:8443/cfn"
    args: []
    description: "Remote AWS CloudFormation MCP Server"

cfn_mcp_version: "latest"

When type is http, the framework only registers the server in the manifest with its URL.

Support both modes

The GitHub MCP role in ansible.mcp_builder demonstrates a pattern for supporting both embedded and remote modes. You can adopt this pattern by:

1. Creating a vars/remote.yml file with the remote registry definition.
2. Loading it conditionally in your tasks:

# roles/cfn_mcp/tasks/main.yml
---
- name: Override registry for remote mode
  ansible.builtin.include_vars:
    file: remote.yml
  when: cfn_mcp_mode | default('local') == 'remote'

- name: Include install manager tasks
  ansible.builtin.include_role:
    name: ansible.mcp_builder.common
    tasks_from: install_manager

- name: Update MCP servers manifest
  ansible.builtin.include_role:
    name: ansible.mcp_builder.common
    tasks_from: generate_manifest
 

You can then select the mode when building the execution environment:

additional_build_steps:
  append_final: |
    RUN ansible-playbook myorg.mcp_cfn.install_cfn_mcp -e cfn_mcp_mode=remote
 

Managing credentials and secrets

MCP servers frequently require credentials to interact with cloud providers or external services. Follow these practices:

• Never embed credentials into the execution environment image: Credentials embedded during build time persist in the container image layers and can be extracted. Instead, pass credentials at runtime using environment variables or mounted files.
• Use runtime environment variables: Pass credentials when launching the execution environment:

   podman run --rm \
      -e AWS_PROFILE=my-profile \
      -e GITHUB_PERSONAL_ACCESS_TOKEN="$GITHUB_TOKEN" \
      my-mcp-ee:latest …
   

• Mount credential files as read-only: For providers that use credential files (such as AWS), mount them read-only:

  -v ~/.aws:/home/runner/.aws:ro

• In Ansible Automation Platform, use credential types: When running MCP-enabled execution environments through Ansible Automation Platform, configure credentials through the automation controller credential management system rather than embedding them in playbooks or job templates.