Skip to main content

Claude Code Integration

Use Claude Code with the Atmos MCP server to access your infrastructure directly from your development environment. Create specialized atmos-expert subagents that provide deep infrastructure expertise while you code.

Experimental

Overview​

Claude Code subagents are specialized AI assistants that enhance your development workflow with domain-specific expertise. When you create an atmos-expert subagent, it can use the Atmos MCP server to access your infrastructure directly from your IDE.

Architecture​

┌─────────────────────────────────────────────────┐
│ Claude Code                                     │
│                                                 │
│  You: @atmos-expert "List my stacks"            │
│         ↓                                       │
│  ┌──────────────────┐                           │
│  │ atmos-expert     │ Specialized Context       │
│  │ Subagent         │ Isolated Conversation     │
│  └────────┬─────────┘                           │
│           │                                     │
└───────────┼─────────────────────────────────────┘
            │ MCP Protocol
            ↓
   ┌────────────────────┐
   │ Atmos MCP Server   │  Universal Interface
   │ • describe_stacks  │
   │ • list_components  │
   │ • validate_stack   │
   └────────┬───────────┘
            │
            ↓
   ┌────────────────────┐
   │ Atmos CLI          │  Your Infrastructure
   └────────────────────┘

When to Use Subagents vs Built-in AI​

Write Terraform code
Claude Code Subagent (in IDE)
Edit component files
Claude Code Subagent (in IDE)
Get help while coding
Claude Code Subagent (in IDE)
Analyze infrastructure
Built-in Atmos AI (atmos ai chat)
Use Ollama/GPT/Gemini
Built-in Atmos AI (7 providers)
Multi-day project discussion
Built-in Atmos AI (persistent sessions)
Quick one-off question
Built-in Atmos AI (atmos ai ask)
Team collaboration
Built-in Atmos AI (shareable sessions)

Setup Guide​

Step 1: Configure Atmos MCP Server​

Create or edit ~/.config/Claude/claude_desktop_config.json:

~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "atmos": {
      "command": "/usr/local/bin/atmos",
      "args": ["mcp", "start"],
      "env": {
        "ATMOS_BASE_PATH": "/path/to/your/infrastructure"
      }
    }
  }
}
macOS with Homebrew

If you installed Atmos via Homebrew, use /opt/homebrew/bin/atmos as the command path.

Restart Claude Desktop after editing the config.

Step 2: Create the Subagent​

Create ~/.claude/agents/atmos-expert.md:

~/.claude/agents/atmos-expert.md
---
name: atmos-expert
description: Expert in Atmos infrastructure orchestration, stack management, and Terraform/Helmfile best practices.
tools:
  - mcp__atmos__describe_stacks
  - mcp__atmos__describe_component
  - mcp__atmos__list_stacks
  - mcp__atmos__list_components
  - mcp__atmos__validate_component
  - mcp__atmos__validate_stack
  - Read
  - Glob
  - Grep
model: inherit
---

You are an expert in Cloud Posse's Atmos infrastructure orchestration framework.

## Your Expertise

- **Stack Architecture**: Atmos stack hierarchies, inheritance, and composition
- **Component Management**: Terraform/Helmfile component design and best practices
- **Configuration Patterns**: YAML configuration, templating, and variable management
- **Troubleshooting**: Diagnosing and resolving Atmos configuration issues

## Available Atmos Tools

1. **describe_stacks**: Get detailed stack configurations with inheritance resolved
2. **describe_component**: Get component configuration for specific stacks
3. **list_stacks**: List all available stacks
4. **list_components**: List all available components
5. **validate_component**: Validate component configuration
6. **validate_stack**: Validate entire stack configuration

## How to Help Users

1. **Analyze before answering**: Use MCP tools to understand the actual configuration
2. **Provide context**: Explain why a configuration works a certain way
3. **Suggest improvements**: Recommend Cloud Posse best practices
4. **Show examples**: Provide concrete YAML examples when helpful
5. **Troubleshoot systematically**: Use validation tools to identify issues
Project-Specific Subagents

You can also create .claude/agents/atmos-expert.md in your project root for project-specific behavior. Project-level subagents override user-level subagents when names conflict.

Step 3: Use the Subagent​

In Claude Code, invoke the subagent with @:

@atmos-expert List all available stacks in my infrastructure

The subagent will use the MCP server to query your infrastructure and provide expert guidance.

Example: Stack Troubleshooting​

You: @atmos-expert Why is prod-use1-eks failing validation?

atmos-expert:
[Uses validate_stack and describe_component]

I found 2 issues in prod-use1-eks:

1. Missing required variable `cluster_version`
   Location: stacks/catalog/eks/defaults.yaml:15

2. Invalid CIDR block format
   Location: stacks/catalog/eks/prod-use1.yaml:23
   Current: "10.0.0/16"
   Should be: "10.0.0.0/16"

[Provides fixes with line numbers]

Troubleshooting​

Subagent Not Using MCP Tools​

Check MCP server is running:

terminal
# Test MCP server directly
atmos mcp start

# Should show: Starting Atmos MCP server...

Verify tool names -- MCP tools require the prefix mcp__<server-name>__<tool-name>:

  • Correct: mcp__atmos__describe_stacks
  • Wrong: describe_stacks (missing prefix)

Restart Claude Desktop after config changes.

Subagent Not Being Invoked​

  1. Check that the description clearly indicates when to use the agent
  2. Use explicit invocation: @atmos-expert your question
  3. Verify file location: ~/.claude/agents/atmos-expert.md (user-level) or .claude/agents/atmos-expert.md (project-level)

MCP Server Not Found​

terminal
# Check atmos is in PATH
which atmos

# Should output: /usr/local/bin/atmos or /opt/homebrew/bin/atmos

Update Claude Desktop config to use the correct path.

Comparison with Built-in Atmos AI​

Access Method
Claude Code Subagent: @atmos-expert in IDE. Built-in Atmos AI: atmos ai chat in terminal.
Tool Protocol
Claude Code Subagent: MCP (slight overhead). Built-in Atmos AI: Direct (faster).
Context
Claude Code Subagent: Independent per subagent. Built-in Atmos AI: Persistent SQLite sessions.
AI Provider
Claude Code Subagent: Claude (Sonnet/Opus/Haiku). Built-in Atmos AI: 7 providers (Claude, GPT, Gemini, Grok, Ollama, Bedrock, Azure).
IDE Integration
Claude Code Subagent: Full code access. Built-in Atmos AI: CLI only.
Code Editing
Claude Code Subagent: Can modify files. Built-in Atmos AI: Read-only.
Session Persistence
Claude Code Subagent: Per-conversation. Built-in Atmos AI: Across CLI invocations.
Best For
Claude Code Subagent: Development workflow. Built-in Atmos AI: Operations workflow.

External Resources​