Skip to main content

MCP Server Integration

The Atmos MCP Server exposes Atmos AI tools through the Model Context Protocol (MCP), an open standard that lets any compatible AI client -- Claude Desktop, Claude Code, VS Code, Cursor, and many others -- connect to your infrastructure tools without custom integrations.

Experimental

See also: MCP Command Reference for flag details and transport modes | MCP Configuration for tool and permission settings in atmos.yaml

Safe by Default

The default stdio transport runs as a local subprocess with no network exposure -- the same security model as running atmos from your terminal. No ports are opened and no remote connections are accepted.

If you use HTTP transport for remote access, see Security Considerations for recommended safeguards.

Quick Start​

This walkthrough gets you from zero to querying stacks in Claude Desktop.

Prerequisites: Atmos v1.63.0+ and Claude Desktop v0.7.0+.

1. Enable MCP and AI in atmos.yaml​

atmos.yaml

mcp:
  enabled: true                 # required — MCP is off by default
ai:
  enabled: true
  tools:
    enabled: true
    require_confirmation: false  # optional, smoother experience
info

The MCP server is disabled by default. You must explicitly set mcp.enabled: true in addition to enabling AI. This ensures that enabling AI chat features does not inadvertently expose an MCP endpoint.

2. Configure Claude Desktop​

Create or edit the config file at ~/.config/claude/claude_desktop_config.json (macOS/Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

claude_desktop_config.json

{
  "mcpServers": {
    "atmos": {
      "command": "atmos",
      "args": ["mcp", "start"],
      "cwd": "/path/to/your/atmos/project"
    }
  }
}
Working Directory

Set cwd to the directory containing your atmos.yaml. On Windows, use atmos.exe as the command and double backslashes for paths (e.g., C:\\Users\\You\\project).

3. Restart and Verify​

Completely quit Claude Desktop and reopen it. After a few seconds, look for the MCP indicator icon in the bottom-right corner. Click it to confirm "atmos" is listed with a green dot. Then try asking:

List all my Atmos stacks

Claude will call atmos_list_stacks and return your actual stack names.

If something goes wrong, check the Troubleshooting section.

Available Tools​

When connected, the MCP server exposes all enabled Atmos AI tools. For full details on each tool, its parameters, and the permission system, see AI Tools Configuration.

atmos_describe_component
Get detailed component configuration for a stack.
atmos_list_stacks
List and filter stacks.
atmos_validate_stacks
Validate stack configurations.
describe_affected
Show components affected by git changes.
read_component_file
Read a component source file.
read_stack_file
Read a stack configuration file.
write_component_file
Modify a component file (requires permission).
write_stack_file
Modify a stack file (requires permission).

All tools respect your configured permission settings.

Client Setup​

Beyond the Quick Start with Claude Desktop, here is how to configure other popular MCP clients. Every client uses the same underlying command (atmos mcp start); only the config format differs.

Desktop Apps and IDEs​

Create .vscode/mcp.json in your project:

.vscode/mcp.json

{
  "servers": {
    "atmos": {
      "type": "stdio",
      "command": "atmos",
      "args": ["mcp", "start"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Alternatively, press Cmd+Shift+P / Ctrl+Shift+P and search "MCP: Add Server".

tip

Enable chat.mcp.discovery.enabled in VS Code settings to auto-discover MCP servers from your Claude Desktop config.

CLI Tools​

claude mcp add

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

# HTTP transport
claude mcp add --transport http atmos http://localhost:8080

# With project scope and env vars
claude mcp add --scope project --transport stdio atmos \
  --env ATMOS_BASE_PATH=/path/to/project \
  -- atmos mcp start

Or add a .mcp.json file to your project root:

.mcp.json

{
  "mcpServers": {
    "atmos": {
      "type": "stdio",
      "command": "atmos",
      "args": ["mcp", "start"]
    }
  }
}

Manage servers with claude mcp list, claude mcp get atmos, and claude mcp remove atmos.

Client Comparison​

Claude Desktop — ~/.config/claude/claude_desktop_config.json
General infrastructure queries.
VS Code Copilot — .vscode/mcp.json
Coding with infrastructure context.
Cursor — ~/.cursor/mcp.json
AI-first development.
Cline — GUI + cline_mcp_settings.json
Autonomous coding.
Continue.dev — .continue/mcpServers/atmos.yaml
Multi-model workflows.
Windsurf — ~/.windsurf/mcp.json
AI-powered development.
Claude Code — .mcp.json or CLI
Terminal-based workflows.
Gemini CLI — ~/.gemini/settings.json
Google Cloud users.
Codex CLI — ~/.codex/config.json
OpenAI ecosystem.
Grok CLI — .grok/settings.json
xAI users.

Example Queries​

Once connected, ask questions in natural language. Claude automatically picks the right tool.

List all my Atmos stacks
Show me the vpc component configuration in prod-us-east-1
What stacks use the RDS component?
Validate all stack configurations
Generate a Terraform plan for vpc in staging
Read the stack file for prod-us-east-1
What are the differences between dev and prod for vpc?

Security Considerations​

stdio Transport (Default)​

Runs as a local subprocess under your user account with no network exposure. This is the recommended transport for desktop apps and local development -- no additional security configuration is needed.

HTTP Transport​

HTTP Transport Security

HTTP transport has no built-in authentication or encryption. Only use it when you need remote or multi-client access, and always add network-level security.

For any deployment beyond localhost:

Network isolation
Use firewall rules, private networks, or VPN. Bind to localhost for single-user scenarios.
Reverse proxy
Put nginx or Caddy in front with TLS and authentication. See the nginx example below.
SSH tunneling
Forward the port over SSH for secure remote access: ssh -L 8080:localhost:8080 user@server.
Tool permissions
Restrict tools in atmos.yaml using allowed_tools and blocked_tools. Disable write operations if not needed.
Monitoring
Poll /health and log all tool executions.

Advanced Deployments​

Docker​

Dockerfile

FROM cloudposse/atmos:latest

COPY atmos.yaml /atmos/atmos.yaml
COPY stacks/ /atmos/stacks/
COPY components/ /atmos/components/

WORKDIR /atmos
EXPOSE 8080

# Binding to 0.0.0.0 inside a container is safe; Docker port mapping controls external access.
CMD ["atmos", "mcp", "start", "--transport", "http", "--host", "0.0.0.0", "--port", "8080"]

docker

docker build -t atmos-mcp .
docker run -p 8080:8080 -e ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY}" atmos-mcp

Troubleshooting​

stdio Connection Issues​

Server not appearing in Claude Desktop:

  1. Verify the config file location and JSON syntax. Use the paths listed in Quick Start.
  2. Fully quit Claude Desktop (Cmd+Q / Alt+F4), wait a few seconds, and reopen.
  3. Confirm atmos is in your PATH:

verify

which atmos
atmos mcp start   # should start without errors; Ctrl+C to exit
  1. Check Claude Desktop logs for errors mentioning "atmos":
    • macOS: ~/Library/Logs/Claude/mcp*.log
    • Windows: %APPDATA%\Claude\logs\mcp*.log
    • Linux: ~/.config/Claude/logs/mcp*.log

Tools not appearing in conversations:

Make sure ai.tools.enabled is true in atmos.yaml and that you have not added the tools to blocked_tools. If tools still do not appear, try asking Claude explicitly: "Use the atmos_list_stacks tool to show my stacks."

"Command not found" errors:

Use the full path to atmos in your config. Run which atmos to find it, then set "command": "/usr/local/bin/atmos" (or wherever it is installed).

HTTP Connection Issues​

debug http

# Check if the server is running
curl http://localhost:8080/health

# Check if the port is in use
lsof -i :8080

# Try a different port
atmos mcp start --transport http --port 3000

If a firewall is blocking connections, allow the port (sudo ufw allow 8080/tcp on Linux, or add atmos to the macOS application firewall).

Common Configuration Errors​

"AI tools are not enabled" -- Set ai.enabled: true and ai.tools.enabled: true in atmos.yaml.

Tools not executing -- Check allowed_tools and blocked_tools in your AI tool config. Remove overly restrictive entries.

Slow responses -- Increase ai.timeout_seconds (default varies by provider). For HTTP transport, check network latency. Monitor resource usage via /health.

Client Setup Guides​

Feedback and Support​