Connect Atmos to MCP Servers — Use Cloud Tools Without Reimplementing Them
Atmos can now connect to external MCP servers and use their tools directly in AI conversations.
Configure any MCP server in atmos.yaml, and its tools appear alongside native Atmos tools
in atmos ai chat, atmos ai ask, and atmos ai exec — no custom integration code needed.
Why This Matters
The MCP ecosystem has hundreds of servers — 20+ from AWS for pricing, security, documentation, and API access; GCP and Azure servers for their respective clouds; plus community servers for databases, monitoring, CI/CD, and custom internal APIs.
Instead of waiting for each cloud integration to be built into Atmos, you can now install any
stdio-based MCP server and use it from the Atmos CLI. One atmos.yaml section, zero glue code.
Any MCP server that accepts command, args, and env works — AWS, GCP, Azure, or your own
custom server.
Quick Start
Add servers to your atmos.yaml:
Then use them:
# Check what you've configured
atmos mcp list
# Verify a server works
atmos mcp test aws-docs
# See what tools a server exposes
atmos mcp tools aws-pricing
# Cost analysis (uses aws-pricing)
atmos ai ask "What's the on-demand price for m7i.xlarge in us-east-1?"
# Spend breakdown (uses aws-billing)
atmos ai ask "What did we spend on EC2 last month?"
# Billing history (uses aws-billing)
atmos ai ask "Show our billing summary for the past 3 months"
# Security posture (uses aws-security)
atmos ai ask "Is GuardDuty enabled in all regions?"
# IAM analysis (uses aws-iam)
atmos ai ask "List all IAM roles with admin access"
# Audit trail (uses aws-cloudtrail)
atmos ai ask "Show recent API calls from the root account"
# Documentation (uses aws-docs, no credentials needed)
atmos ai ask "How do I configure S3 bucket lifecycle rules?"
Smart Server Routing
When multiple MCP servers are configured, Atmos automatically selects only the servers relevant to your question using a lightweight routing call to your configured AI provider. This keeps tool payloads small and responses fast, even with dozens of servers configured:
$ atmos ai ask "List all IAM roles with admin access"
ℹ MCP routing selected 1 of 8 servers: aws-iam
ℹ MCP server "aws-iam" started (29 tools)
ℹ Registered 29 tools from 1 MCP server(s)
ℹ AI tools initialized: 39
Use --mcp to override and specify servers directly:
# Specify one server
atmos ai ask --mcp aws-iam "List all admin roles"
# Comma-separated or repeated flags
atmos ai ask --mcp aws-iam,aws-cloudtrail "Who accessed the admin role?"
# Works with all AI commands
atmos ai chat --mcp aws-billing
atmos ai exec --mcp aws-security,aws-iam "audit our security posture"
Visibility
Atmos shows which MCP servers are active and which tools the AI uses:
ℹ MCP routing selected 2 of 8 servers: aws-docs, aws-pricing
ℹ MCP server "aws-docs" started (4 tools)
ℹ MCP server "aws-pricing" started (7 tools)
ℹ Registered 11 tools from 2 MCP server(s)
ℹ AI tools initialized: 26 total
After the AI responds, tool executions are listed:
---
## Tool Executions (2)
1. ✅ aws-docs → aws.search_documentation (234ms)
2. ✅ aws-pricing → get_pricing (456ms)
Tool usage is not inferred — the AI provider explicitly declares which tools it wants to call
via the API protocol (tool_use stop reason with a tool_calls array). Atmos executes the
requested tools, sends results back to the AI for the final answer, and records every call.
If no tool executions appear, the AI genuinely chose not to use any tools for that question.
CLI Commands
atmos mcp list # List configured external servers
atmos mcp tools <name> # List tools from a server
atmos mcp test <name> # Test server connectivity
atmos mcp status # Show all server statuses
atmos mcp restart <name> # Restart a server
atmos mcp export # Generate .mcp.json for Claude Code / IDE
Standard Config Format
The command, args, env fields follow the same format used by Claude Code, Codex CLI, and
Gemini CLI. Atmos adds description, identity, and timeout as extensions:
mcp:
servers:
my-server:
command: "uvx" # Standard
args: ["package@latest"] # Standard
env: # Standard
AWS_REGION: "us-east-1"
description: "What this server does" # Atmos extension
identity: "my-identity" # Atmos Auth identity (from the auth section)
timeout: "30s" # Connection timeout
Atmos Auth Integration
Use Atmos Auth to inject credentials automatically — no manual
AWS_PROFILE setup:
mcp:
servers:
aws-security:
command: uvx
args: ["awslabs.well-architected-security-mcp-server@latest"]
identity: "security-audit" # Atmos Auth identity (from the auth section)
Atmos authenticates through the identity chain, writes isolated credential files, and sets
AWS_SHARED_CREDENTIALS_FILE + AWS_PROFILE on the subprocess.
Toolchain Integration
Map uv to the aqua registry and install via the Atmos Toolchain:
toolchain:
aliases:
uv: astral-sh/uv
atmos toolchain install astral-sh/uv@0.7.12
IDE Integration
Use the same servers from Claude Code, Cursor, or any MCP-compatible IDE:
# Generate .mcp.json from your atmos.yaml config
atmos mcp export
Servers with identity are automatically wrapped with atmos auth exec for
credential injection. The generated .mcp.json works with Claude Code out of the box.
