Configure MCPs once in Atmos, use it from Claude Code, Codex, and Gemini

Claude Code, OpenAI Codex CLI, and Google Gemini CLI all speak MCP, but each wants its own config format, its own credentials flow, and its own idea of where binaries live. This post shows how to centralize all of it — server configuration, AWS credentials, and toolchain version — in one atmos.yaml that every AI coding assistant uses unchanged.

Atmos Auth is the only place AWS credentials live; each MCP server is automatically wrapped with the right identity for the question it'll answer (billing → payer account, CloudTrail → audit, IAM → root, workload queries → dev/rpg/staging). One atmos auth login covers them all — no API keys in CLI configs, no AWS_PROFILE swapping between prompts. The server set spans the Atmos MCP server for project stacks, the AWS MCP server suite for live cloud queries, and the Atmos Pro MCP server for drift, deployment, and audit history. The Atmos toolchain pins binaries so every assistant runs the same binary. See the example: examples/mcp-for-ai-coding-assistants/.

---

Your AI knows your stacks and components. And your cloud. And your history.

In one prompt, your AI coding assistant answers:

• What's configured in your infrastructure
• What's deployed in your cloud accounts
• What changed — when, why, how, and by whom

Centralized auth. Centralized security and permissions. One atmos.yaml. Try the example →

---

The Problem

If you've tried to use the awslabs MCP servers with more than one AI coding assistant, with each MCP server requiring different credentials, you've probably hit this:

• Three different config files. Claude Code reads .mcp.json, OpenAI Codex CLI reads ~/.codex/config.toml (TOML, not JSON), and Google Gemini CLI reads .gemini/settings.json. The schemas are almost the same but not quite, and each CLI looks in a different place.
• Three different ways to register servers. Each CLI has its own mcp add command with subtly different flags. Or you can hand-edit the config file. Or both.
• AWS credentials need to flow through. Every AWS MCP server needs AWS credentials. Without help, that means aws configure, juggling AWS_PROFILE, copy-pasting role ARNs into shell wrappers, or worse — baking credentials into config files that get committed by accident.
• Toolchain drift. uvx, npx, and friends need to exist on PATH when the AI CLI spawns the MCP server subprocess. If your Codex install uses a different shell session than Claude Code, one of them might not find uvx.

Each of these is solvable individually. Solving all of them for three CLIs is annoying.

The Idea

atmos.yaml already had everything you need:

toolchain:
  aliases:
    uv: astral-sh/uv          # pin uvx to a known version

mcp:
  enabled: true                # expose Atmos's own tools as an MCP server
  servers:                     # external MCP servers Atmos manages
    atmos:
      command: atmos
      args: ["mcp", "start"]
    aws-billing:
      command: uvx
      args: ["awslabs.billing-cost-management-mcp-server@latest"]
      env: { AWS_REGION: "us-east-1" }
      identity: "readonly"     # ← Atmos Auth identity
    # … and more

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"

atmos mcp export reads the mcp.servers block, wraps every server with identity in atmos auth exec -i <identity> --, prepends the toolchain's PATH so uvx resolves, and writes a .mcp.json ready for any MCP-compatible client.

For Claude Code that's the native format. Gemini's .gemini/settings.json is structurally identical, so the same export works with --output .gemini/settings.json. For Codex, it's TOML format — and the example walks you through that.

The result: many MCP servers, three AI CLIs, one Atmos config.

What Each AI CLI Gets

All three CLIs end up with the same set of MCP servers:

Server	Purpose	Transport	Auth
atmos	describe component, list stacks, etc.	stdio	Atmos Auth
atmos-pro	Drift, deployments, workflow runs, audit log	HTTP	Browser OAuth (GitHub)
aws-docs	Search AWS documentation	stdio	None (public)
aws-knowledge	Managed AWS knowledge base (remote)	stdio	None (public)
aws-pricing	Real-time pricing	stdio	AWS (via Atmos Auth)
aws-billing	Billing summaries	stdio	AWS (via Atmos Auth)
aws-iam	IAM role/policy analysis	stdio	AWS (via Atmos Auth)
aws-cloudtrail	Event history	stdio	AWS (via Atmos Auth)
aws-security	Well-Architected security	stdio	AWS (via Atmos Auth)
aws-api	Direct AWS CLI (read-only by default)	stdio	AWS (via Atmos Auth)

The AWS servers plus the embedded atmos server are stdio-transport and managed through atmos mcp export. The atmos-pro entry is HTTP- transport (it runs on https://atmos-pro.com/mcp), so it's registered directly with each AI CLI alongside the exported config — see the Atmos Pro section below.

What the atmos MCP server does

The first entry — atmos — is the Atmos MCP server itself, running inside the atmos binary via atmos mcp start. Including it in the exported config gives your AI coding assistant programmatic access to your Atmos project — the stacks, components, manifests, and the atmos CLI as a whole — alongside the AWS introspection tools.

It exposes more than 20 tools:

• Stack & component introspection (read-only).
• Execution (permission-gated).
• Security & compliance — atmos_list_findings, atmos_describe_finding, atmos_analyze_finding, atmos_compliance_report.

Write-side tools (write_*, execute_bash_command) respect Atmos's tool permission model. The MCP server runs in YOLO mode by default, so the AI coding assistant's own permission UI — Claude Code's per-tool approval, Codex's confirm prompt, Gemini's consent dialog — handles execution approval.

The Atmos Pro MCP server (SaaS)

Atmos Pro is the fastest way to deploy your apps on AWS with Terraform and GitHub Actions. The Atmos Pro MCP server lets your AI assistant query everything Atmos Pro knows about your workspace — drift, deployments, workflow runs, audit log — without leaving the editor.

Unlike the local servers, this one runs on https://atmos-pro.com/mcp over HTTP transport. Auth is a one-time browser OAuth (GitHub login); short-lived tokens land in your OS keychain, revocable from the Atmos Pro UI. No API keys to leak.

It exposes capabilities across these areas:

• Workflows & deployments — workflow runs with approval states and job summaries; deployment history linked to commits and PRs; failed-step logs and failure-pattern analysis over time.
• Triage & diagnostics — list/inspect drifted or errored instances, stacks, and components; access repair history and recommendations; structured failure explanations.
• Historical context — when failures began, flapping detection, stability comparisons against previous periods, full audit log.
• Security & access — audit every agent tool call (actor type, client name, arguments); permission reviews; compliance audit trail.

How the three layers complement each other

The AWS servers tell the assistant what is deployed. The atmos server tells it what is defined. The atmos-pro server tells it what is happening over time — drift against truth, who/what changed it, why a run failed, when problems began.

So the AI can answer cross-layer questions in one prompt:

"Why did our vpc deploy fail yesterday — what changed in the stack config, what does Atmos Pro show for that run, and which AWS resource is now out of sync?"

…pulling deployment history from atmos-pro, declared config from atmos (or directly from your repo Atmos config), and live state from aws-api in a single coherent answer.

Pair with Atmos Agent Skills

MCP gives the AI tools — to inspect stacks, query AWS, check Atmos Pro. Atmos Agent Skills give it knowledge — domain-specific skills (stacks, components, validation, YAML functions, vendoring, toolchain, GitOps, auth, …) that activate based on what you ask.

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 skills are built on the open AGENTS.md and Agent Skills standards, so they work across all three CLIs (Claude Code, Codex CLI, Gemini CLI) plus Cursor, Windsurf, GitHub Copilot, and others.

For Claude Code:

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

For other tools, see the AI Agent Skills announcement for tool-specific install paths.

Why pair them: MCP answers "what does this code do?" by reading files and live state; skills answer "what should this code do?" by teaching the assistant Atmos's conventions. 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) from the relevant skill. Stronger together than either alone.

Wiring Up Each CLI

Once you've run atmos auth login, each CLI takes a couple of commands.

Claude Code

# Generate .mcp.json in your project root.
atmos mcp export

# Start Claude Code from that directory.
claude

Or use claude mcp add to register each server globally:

claude mcp add --transport stdio aws-billing -- \
  atmos auth exec -i readonly -- uvx awslabs.billing-cost-management-mcp-server@latest

claude mcp add --transport stdio atmos -- atmos mcp start

The atmos auth exec -i readonly -- wrapper is what Atmos Auth's credential injection rides on. The IAM role specified in atmos.yaml's identities.readonly gets assumed and the resulting AWS_KEY environment variables land in the MCP server's process.

OpenAI Codex CLI

Codex reads ~/.codex/config.toml:

[mcp_servers.atmos]
command = "atmos"
args = ["mcp", "start"]

[mcp_servers.aws-billing]
command = "atmos"
args = ["auth", "exec", "-i", "readonly", "--",
        "uvx", "awslabs.billing-cost-management-mcp-server@latest"]

[mcp_servers.aws-billing.env]
AWS_REGION = "us-east-1"
FASTMCP_LOG_LEVEL = "ERROR"

Google Gemini CLI

Gemini's .gemini/settings.json is the same schema as .mcp.json, so you can export directly:

# Per-project (check it in alongside atmos.yaml):
atmos mcp export --output .gemini/settings.json

# Or per-user:
atmos mcp export --output ~/.gemini/settings.json

# Then start Gemini in this directory:
gemini

Or use gemini mcp add:

gemini mcp add aws-billing -- \
  atmos auth exec -i readonly -- uvx awslabs.billing-cost-management-mcp-server@latest

gemini mcp add atmos -- atmos mcp start

Trusted Folders

Gemini's Trusted Folders feature blocks MCP servers in untrusted directories. Trust the folder once via the Gemini UI/settings before the servers will start.

Atmos Pro (all three CLIs)

The atmos-pro server is HTTP-transport and registered separately from the atmos mcp export flow. The OAuth handshake runs the first time the server is spawned — log in with GitHub, the token lands in your OS keychain (no API keys to leak, revocable from the Atmos Pro UI).

# 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"

Or merge the JSON entry into .mcp.json / .gemini/settings.json / ~/.claude.json:

{
  "mcpServers": {
    "atmos-pro": {
      "type": "http",
      "url": "https://atmos-pro.com/mcp"
    }
  }
}

What You Can Ask

Same questions, three AIs:

List all IAM roles with AdministratorAccess.
What did we spend on EC2 across all accounts last month?
Is GuardDuty enabled in every region?
What stacks are defined in this project?
Validate every stack and report any errors.

# Atmos Pro questions:
Which workspaces have drift right now?
Why did the last deploy of vpc in prod fail?
Has this stack been flapping over the past week?

# Cross-layer (mixes atmos-pro + atmos + aws-api):
Why did our vpc deploy fail yesterday — what changed in the stack
config, what does Atmos Pro show for that run, and which AWS resource
is now out of sync?

The AI assistant picks which MCP tools to call. You don't specify them.

Why This Matters

Four benefits:

1. Central management. One atmos.yaml, versioned with your infrastructure repo. Onboarding a new engineer is git clone + atmos auth login. Adding a new MCP server is one block in atmos.yaml and one re-export. No per-engineer drift.

2. Security — every credential, in one place. Atmos Auth is the only place AWS credentials live. Each external MCP server is spawned via atmos auth exec, which resolves credentials at runtime and writes them only into that subprocess's env. The exported .mcp.json is safe to check into the repo if needed — the worst it leaks is the IAM role name. No static secrets in ~/.aws/credentials, no AWS_PROFILE scattered across shells, no per-server authentication, no token files in each CLI's config dir.

3. Convenience — one login, every account auto-routed. Configure all the accounts you care about in auth.identities, run atmos auth login once, and Atmos picks the right account for every MCP server automatically (billing → payer, CloudTrail → audit, IAM analysis → root, workload introspection → dev). The AI calls a tool, and the right credentials are already there — no identity juggling between prompts, no AWS_PROFILE swapping, no re-login to ask a billing question after asking a VPC one.

4. Toolchain hygiene. uvx and friends are pinned to a known version via the Atmos toolchain. Every engineer's AI assistant uses the same binaries. No "but it works on my machine" with a different uvx minor.

The example walks through the full setup end to end, including the per-CLI config layouts: examples/mcp-for-ai-coding-assistants/.

Related Examples

• Atmos MCP integrations — Same external MCP server config, but Atmos drives the AI loop (atmos ai ask) instead of an external CLI. Useful if you'd rather stay inside the atmos CLI than spawn Claude Code / Codex / Gemini.
• Atmos AI with Claude Code — Use a Claude Pro/Max subscription as Atmos's AI provider (no Anthropic API key). Atmos hosts the AI conversation; Claude Code provides the model; MCP servers pass through.
• Atmos AI (multi-provider) — Multi-provider Atmos AI setup (Anthropic API, OpenAI API, Ollama, …). No external CLI; chat with your infra from atmos ai ask.

Related Reading

• MCP Configuration in Atmos — full reference for the mcp: section, including server-config fields and smart-routing.
• Atmos Auth — provider/identity model and atmos auth login flow.
• Atmos Toolchain — how toolchain aliases and atmos toolchain install work.
• Atmos MCP Server — the Atmos-AI-tools-as-MCP-server mode, exposed to your AI coding assistant via the atmos entry in mcp.servers.
• Atmos Agent Skills — 21 domain-specific skills that complement MCP tools by giving AI assistants deep Atmos knowledge (stacks, components, validation, YAML functions, vendoring, GitOps, design patterns, …).
• AI Agent Skills announcement — install paths for Claude Code, Codex, Gemini, Cursor, Windsurf, GitHub Copilot, JetBrains Junie, and Amazon Q.
• Atmos Pro MCP server install — HTTP-transport SaaS server for drift, deployments, and audit context.
• Atmos Pro MCP server announcement — full capability list and the design choices behind the OAuth flow.
• AWS MCP servers (awslabs/mcp) — the upstream source of the AWS MCP servers used in the example.