| name | atmos-ai |
| description | Atmos AI and MCP integrations: connect external AI assistants to Atmos through agent skills, atmos mcp start, multi-CLI MCP export, Atmos Pro MCP, and AWS MCP servers; run AI from Atmos through atmos ai ask/chat/exec, --ai command analysis, API providers, CLI providers, external MCP routing/pass-through, toolchain-aware export, auth-wrapped tools, and MCP+skills pairing |
| metadata | {"copyright":"Copyright Cloud Posse, LLC 2026","version":"1.0.0","category":"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
| Work | Use |
|---|
AI provider setup, atmos ai, --ai, MCP server/client config, MCP export, agent-skill pairing | Stay in atmos-ai |
| Project discovery, resolved stacks/components, provenance, query filters, affected analysis | Load atmos-introspection |
Terraform plan/apply/deploy/destroy, --affected, --all, --query, CI execution matrices | Load atmos-terraform or atmos-ci |
| Cloud credentials, identities, SSO/OIDC, auth-wrapped MCP servers | Load atmos-auth |
Tool binaries for MCP servers, uvx/npx resolution, Aqua aliases, PATH injection | Load atmos-toolchain |
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
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.
| Layer | What it provides | Example |
|---|
| MCP | Tools -- live data and execution capability | "What stacks exist?" -> atmos MCP tool call |
| Skills | Knowledge -- domain patterns and conventions | "How should I structure cross-stack deps?" -> skill |
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
atmos ai skill install atmos-terraform
atmos ai skill install github.com/user/repo
atmos ai skill install
atmos ai skill update
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:
| Layer | Server(s) | Answers |
|---|
| Defined | atmos (Atmos MCP server) | What's in the stacks, components, repo |
| Deployed | AWS MCP server suite (awslabs/*) | What's live in the cloud right now |
| Over time | atmos-pro (Atmos Pro MCP) | What changed, when, why, who, drift |
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.
toolchain:
aliases:
uv: astral-sh/uv
mcp:
enabled: true
servers:
atmos:
command: atmos
args: ["mcp", "start"]
description: "Atmos AI tools — stacks, components, validation"
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):
| Server | Purpose |
|---|
| aws-docs | Search AWS documentation (no auth) |
| aws-knowledge | Managed AWS knowledge base (remote) |
| aws-pricing | Real-time pricing and cost analysis |
| aws-billing | Billing summaries and payment history |
| aws-iam | IAM role/policy analysis |
| aws-cloudtrail | Event history and API call auditing |
| aws-security | Well-Architected security assessment |
| aws-api | Direct AWS CLI (read-only by default) |
See examples/mcp-for-ai-coding-assistants/atmos.yaml for a working full configuration.
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 mcp add --transport http atmos-pro https://atmos-pro.com/mcp
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"
Auth and Profiles
For MCP servers that need cloud credentials, prefer Atmos Auth identities over ambient
AWS_PROFILE switching. When identity is set on an MCP server, Atmos injects isolated
credential files and profile env vars into that subprocess.
A common pattern is a single readonly identity (with default: true) used by every
AWS-querying MCP server, plus per-domain identities (e.g., billing-auditor,
security-audit) for servers that need different account access:
auth:
providers:
sso:
kind: aws/iam-identity-center
start_url: "https://your-org.awsapps.com/start"
region: us-east-1
identities:
readonly:
kind: aws/permission-set
default: true
via: { provider: sso }
principal:
name: ReadOnlyAccess
account: { id: "123456789012" }
For local use, authenticate once with the relevant identity:
atmos auth login readonly
atmos mcp test aws-security
For CLI providers, export ATMOS_PROFILE when the active profile defines the auth identities
or MCP servers:
export ATMOS_PROFILE=managers
atmos ai ask "What did we spend on EC2 last month?"
Do not add an atmos auth login step to non-interactive GitHub OIDC CI unless a specific
integration requires it. In CI, set ATMOS_PROFILE and let Atmos exchange the OIDC token when
the command runs.
Multi-CLI MCP Export
atmos mcp export generates MCP client config from mcp.servers. The format adapts to the
client based on the output path or --format flag.
| Client | Native config path | Format | Export command |
|---|
| Claude Code | .mcp.json (project root) | JSON | atmos mcp export |
| Gemini CLI | .gemini/settings.json | JSON | atmos mcp export --output .gemini/settings.json |
| Cursor | .cursor/mcp.json | JSON | atmos mcp export --output .cursor/mcp.json |
| Codex CLI | ~/.codex/config.toml | TOML | atmos mcp export --output ~/.codex/config.toml |
Claude Code and Gemini share the same JSON schema (mcpServers object). Codex uses TOML with
[mcp_servers.<name>] tables.
Exported configs preserve two critical behaviors:
- Servers with
identity are wrapped as atmos auth exec -i <identity> -- <command> ....
- The exported server
env.PATH includes the Atmos toolchain PATH so tools like uvx and
npx resolve even when the AI client does not inherit the user's shell environment.
Inspect and test exported configurations:
atmos mcp list
atmos mcp status
atmos mcp tools aws-docs
atmos mcp test aws-security
atmos mcp export
atmos mcp restart <name> validates that the server can stop and start during the command; do
not describe it as creating a long-running background service for stdio servers.
Gemini Trusted Folders Gotcha
Gemini's Trusted Folders feature blocks MCP servers in untrusted directories. After
atmos mcp export --output .gemini/settings.json, the user must trust the folder once via
the Gemini UI/settings before the MCP servers will start. Symptom: servers configured
correctly but no tools available in Gemini.
Related Examples
examples/mcp-for-ai-coding-assistants/ -- canonical full setup: Atmos MCP server + AWS
server suite + Atmos Pro, exported to Claude Code / Codex / Gemini, AWS credentials via
Atmos Auth.examples/mcp/ -- external MCP server config when Atmos itself drives the AI loop
(atmos ai ask) instead of an external CLI.examples/ai-claude-code/ -- use a Claude Pro/Max subscription as Atmos's AI provider (no
Anthropic API key). Atmos hosts the conversation; Claude Code provides the model.examples/ai/ -- multi-provider Atmos AI setup (Anthropic API, OpenAI API, Ollama). No
external CLI; chat with infrastructure from atmos ai ask.
Guardrails
- Keep MCP server configuration in
atmos.yaml so agents, IDEs, and CI share one source of truth.
- Pin MCP package versions when repeatability matters; avoid unreviewed
@latest in production workflows.
- Use
atmos toolchain for binaries that MCP servers need, then rely on export/toolchain PATH injection.
- Use
--identity=false, off, 0, or no only when deliberately disabling Atmos Auth for a command.
- The exported
.mcp.json is safe to commit -- it contains no secrets (worst case: IAM role
names). Credentials resolve at runtime via atmos auth exec.
- For
awslabs/* MCP servers, prefer a single readonly identity by default and switch only
for servers that genuinely need elevated access.
Related Reading
