Atmos AI

Atmos AI and MCP

Purpose

Use this skill when the work is about AI and Atmos together. There are two integration patterns:

• AI uses Atmos: external AI assistants use Atmos Agent Skills for knowledge and Atmos MCP servers for tools. This includes atmos mcp start, atmos mcp export, the Atmos MCP server, Atmos Pro MCP, AWS MCP servers, and MCP+skills setup for Claude Code, Codex, Gemini, Cursor, Windsurf, GitHub Copilot, and similar clients.
• Atmos uses AI: Atmos calls AI providers directly or through local CLI providers. This includes atmos ai ask, atmos ai chat, atmos ai exec, --ai command analysis, API providers, CLI providers, external MCP server routing, and CLI provider MCP pass-through.

This skill is the coordination layer for AI providers, agent skills, MCP configuration, MCP export, and the "AI inside AI" setup where an external assistant calls Atmos, and Atmos can also call AI.

Routing

Atmos Uses AI: Commands and Providers

atmos ai chat
atmos ai ask "What stacks do we have?"
atmos ai exec "validate stacks" --format json
atmos ai sessions list
atmos ai skill list

# Analyze any Atmos command output with AI
atmos terraform plan vpc -s prod --ai
atmos terraform plan vpc -s prod --ai --skill atmos-terraform
atmos terraform plan vpc -s prod --ai --skill atmos-terraform,atmos-stacks

Use API providers for CI/CD and non-interactive automation. Use CLI providers when the user wants to reuse an existing local subscription such as Claude Code, Codex CLI, or Gemini CLI.

ai:
  enabled: true
  default_provider: claude-code
  providers:
    claude-code:
      max_turns: 10
  tools:
    enabled: true

AI Uses Atmos: MCP and Skills

Atmos MCP has two separate capabilities:

• Atmos MCP server: atmos mcp start exposes Atmos AI tools to external clients.
• External MCP connections: mcp.servers lets Atmos or an AI CLI use AWS, cloud, database, or custom MCP servers.

The Atmos MCP server is disabled by default. Enabling AI does not enable MCP.

mcp:
  enabled: true

ai:
  enabled: true
  tools:
    enabled: true

Use Atmos Agent Skills with MCP. MCP provides live tools; skills provide Atmos-native knowledge and conventions.

Without skills, an AI assistant falls back to general training data that may generate invalid YAML, miss features like !store / !terraform.output, or use wrong CLI flags. With skills, the assistant loads the right Atmos context just before answering.

The same prompt -- "set up cross-stack dependencies with remote state" -- pulls live data through MCP and applies Atmos-native patterns (!terraform.state, abstract components, inheritance, remote-state-bridge) from the relevant skill.

Installing Skills: atmos ai skill (canonical, cross-client)

atmos ai skill install/list/update/uninstall is the canonical, cross-client way to manage skills -- it works for every supported client (Claude Code, VS Code/Copilot, Gemini), not just Claude Code.

atmos ai skill list                          # Browse the bundled catalog + what's installed
atmos ai skill install atmos-terraform       # Bundled skill, offline, no network/Git needed
atmos ai skill install github.com/user/repo  # Community skill from GitHub
atmos ai skill install                       # Install every bundled skill at once
atmos ai skill update                        # Refresh installed bundled skills to the latest catalog version
atmos ai skill uninstall atmos-terraform

Installing a bundled skill copies its content at that point in time -- upgrading the atmos binary alone doesn't refresh a skill you already installed. Run atmos ai skill update after upgrading Atmos to pick up any bundled skill content that shipped since you installed it. Skills installed from GitHub aren't covered by update yet; re-run install <source> --force for those.

By default the skill is copied into every detected client's project-local skill directory (.claude/skills/, .github/skills/ for VS Code/Copilot, .gemini/skills/) with zero extra flags. Use --client/--all-clients to target specific clients, --scope user/--global to install into each client's user-level directory instead of the project one, or --path to take full manual control of the install location (this skips auto-distribution to clients). See atmos ai skill for the full flag reference.

Installing Skills: Claude Code Plugin (Claude Code only)

For Claude Code specifically, the skills plugin is a lighter-weight alternative that also wires up marketplace updates:

/plugin marketplace add cloudposse/atmos
/plugin install atmos@cloudposse

For Codex, Gemini, Cursor, Windsurf, GitHub Copilot, JetBrains Junie, and Amazon Q, see the AI Agent Skills announcement for tool-specific install paths, or use atmos ai skill install above, which works for all of them.

The Three Layers

A complete AI assistant setup typically uses three layers of MCP servers, each answering a different question:

Use this framing when helping users decide which servers to enable. Pure stack questions need only the atmos server. Live-cloud questions need AWS servers. History/drift/deployment questions need Atmos Pro.

External MCP Server Configuration

Configure servers once in atmos.yaml. atmos mcp export writes them to per-CLI config files.

@latest below is for brevity -- pin every uvx package to a reviewed version before treating this as a production setup (unpinned @latest on an MCP server is a supply-chain risk; see Guardrails below).

toolchain:
  aliases:
    uv: astral-sh/uv                                      # Pin uvx via the Atmos toolchain

mcp:
  enabled: true
  servers:
    # Atmos's own MCP server — exposes describe/list/validate as tools
    atmos:
      command: atmos
      args: ["mcp", "start"]
      description: "Atmos AI tools — stacks, components, validation"

    # AWS MCP server suite — credentials injected via Atmos Auth
    aws-docs:
      command: uvx
      args: ["awslabs.aws-documentation-mcp-server@latest"]
      description: "AWS docs (public, no auth)"

    aws-billing:
      command: uvx
      args: ["awslabs.billing-cost-management-mcp-server@latest"]
      identity: readonly
      env: { AWS_REGION: us-east-1 }
      description: "AWS billing summaries"

    aws-iam:
      command: uvx
      args: ["awslabs.iam-mcp-server@latest"]
      identity: readonly
      description: "IAM role/policy analysis"

The canonical AWS server set (use identity: readonly via Atmos Auth for servers that need AWS credentials; aws-docs is commonly no-auth):

Atmos Pro MCP Server (HTTP transport)

The Atmos Pro MCP server is HTTP transport (not stdio), runs at https://atmos-pro.com/mcp, and is registered separately from atmos mcp export. Auth is a one-time browser OAuth (GitHub); short-lived tokens land in the OS keychain.

Capabilities: drift detection, deployment history, workflow runs, failed-step logs, audit log, repair recommendations, flapping detection.

Register it directly with each AI CLI:

# Claude Code
claude mcp add --transport http atmos-pro https://atmos-pro.com/mcp

# Gemini CLI
gemini mcp add --transport http atmos-pro https://atmos-pro.com/mcp

For Codex CLI, append to ~/.codex/config.toml:

[mcp_servers.atmos-pro]
type = "http"
url = "https://atmos-pro.com/mcp"