Skip to main content

MCP Configuration

Configure MCP (Model Context Protocol) in Atmos — both the Atmos MCP server (for external AI clients to connect to Atmos) and external MCP server connections (for Atmos to connect to external servers like AWS MCP).

Experimental

Overview​

Atmos MCP has two sides:

FeatureWhat It DoesConfig Key
MCP ServerExposes Atmos AI tools to external clients (Claude Desktop, Claude Code, VS Code)mcp.enabled
MCP Server ConnectionsConnects Atmos to external MCP servers (AWS, GCP, custom)mcp.servers

Quick Start​

atmos.yaml

mcp:
  # Enable the Atmos MCP server (for external AI clients).
  enabled: true

  # Connect to external MCP servers.
  servers:
    aws-docs:
      command: uvx
      args: ["awslabs.aws-documentation-mcp-server@latest"]
      description: "AWS Documentation — search and fetch AWS docs"

ai:
  enabled: true
  tools:
    enabled: true

MCP Server Configuration​

The Atmos MCP server exposes Atmos AI tools via the Model Context Protocol. It must be explicitly enabled separately from AI features, since it opens a communication channel that external clients can connect to.

Settings​

mcp.enabled
Enable the Atmos MCP server (default: false). Must be set to true before atmos mcp start will work.
Opt-In Only

The MCP server is disabled by default. Enabling AI features (ai.enabled: true) does not enable MCP. The default stdio transport runs as a local subprocess with no network exposure.

Tool Settings​

The MCP server exposes all tools configured in ai.tools. See AI Tools Configuration for the full reference including allowed_tools, blocked_tools, and require_confirmation.

External MCP Server Connections​

Connect Atmos to external MCP servers so their tools are available in atmos ai chat, atmos ai ask, and atmos ai exec.

Server Configuration​

Each server under mcp.servers follows the standard MCP server format used by Claude Code, Codex CLI, and Gemini CLI. Atmos adds extensions for descriptions, auth, and timeouts.

atmos.yaml

mcp:
  servers:
    <server-name>:
      # Standard MCP fields
      command: "uvx"                    # Command to run the server
      args:                             # Command arguments
        - "package-name@latest"
      env:                              # Environment variables
        AWS_REGION: "us-east-1"

      # Atmos extensions
      description: "Human-readable description"
      identity: "my-identity"           # Atmos Auth identity (from the auth section)
      auto_start: false                 # Start server automatically
      timeout: "30s"                    # Connection timeout

Standard Fields​

These fields are compatible with the mcpServers JSON format used by Claude Code, Codex CLI, and Gemini CLI:

command
Required. The command to run the MCP server (e.g., uvx, npx, or an absolute path to a binary).
args
Arguments passed to the command. Typically the package name and version (e.g., awslabs.aws-pricing-mcp-server@latest).
env
Environment variables passed to the server subprocess. Supports YAML functions like !env and !exec.

Atmos Extensions​

description
Human-readable description shown in atmos mcp list and atmos mcp status.
identity
Name of an Atmos Auth identity (from the auth section) to use for credential injection. When set, Atmos authenticates through the identity chain and injects AWS_SHARED_CREDENTIALS_FILE, AWS_CONFIG_FILE, AWS_PROFILE, and AWS_REGION into the subprocess environment.
auto_start
Start the server automatically when Atmos starts (default: false).
timeout
Connection timeout as a Go duration string (default: 30s). Examples: 10s, 1m, 5m.

YAML Functions in Env Values​

Atmos YAML functions work in env values, processed during config loading:

atmos.yaml

mcp:
  servers:
    my-server:
      command: uvx
      args: ["my-mcp-server@latest"]
      env:
        # Read from OS environment variable
        AWS_REGION: !env AWS_DEFAULT_REGION
        AWS_PROFILE: !env AWS_PROFILE

        # Execute a shell command
        API_KEY: !exec "vault kv get -field=key secret/mcp"

        # Git repository root path
        PROJECT_ROOT: !repo-root

        # Current working directory
        WORK_DIR: !cwd

Auth Integration​

For production use, configure Atmos Auth to automatically inject AWS credentials:

atmos.yaml

auth:
  providers:
    aws-sso:
      kind: aws/iam-identity-center
      start_url: "https://your-org.awsapps.com/start"
      region: "us-east-1"
  identities:
    security-audit:
      kind: aws/permission-set
      provider: aws-sso
      default: true
      principal:
        permission_set: "ReadOnlyAccess"
        account:
          id: "123456789012"

mcp:
  servers:
    aws-security:
      command: uvx
      args: ["awslabs.well-architected-security-mcp-server@latest"]
      identity: "security-audit"   # Atmos Auth identity (from the auth section)

When identity is set, Atmos:

  1. Authenticates through the identity chain (SSO → role assumption)
  2. Writes isolated credential files to ~/.aws/atmos/<realm>/
  3. Injects AWS_SHARED_CREDENTIALS_FILE, AWS_CONFIG_FILE, AWS_PROFILE into the subprocess
  4. The MCP server's AWS SDK picks up credentials automatically

Toolchain Integration​

Map uv to the aqua registry and install via the Atmos Toolchain:

atmos.yaml

toolchain:
  aliases:
    uv: astral-sh/uv
atmos toolchain install astral-sh/uv@0.7.12

CLI Provider MCP Pass-Through​

When using a CLI provider (claude-code, codex-cli, gemini-cli), MCP servers are passed directly to the CLI tool instead of being managed by Atmos. Smart routing is skipped — all configured servers are passed and the AI model decides which to use.

CLI ProviderConfig DeliveryNotes
Claude Code--mcp-config temp fileFull support
Codex CLI~/.codex/config.toml (backup/restore)ATMOS_* env vars injected
Gemini CLI.gemini/settings.json in cwd (backup/restore)MCP blocked for personal Google accounts
tip

For CLI providers, ATMOS_PROFILE must be exported in your shell for auth-requiring MCP servers to work:

export ATMOS_PROFILE=managers
atmos ai ask "What did we spend on EC2?"

Smart Routing​

When multiple MCP servers are configured, Atmos automatically selects only the servers relevant to your question before starting them. This keeps tool payloads small and responses fast.

atmos.yaml

mcp:
  routing:
    enabled: true   # Default: true. Uses the same AI provider and model from ai.default_provider.
routing.enabled
Enable automatic server routing (default: true). When enabled, Atmos sends the question and server descriptions to the AI provider, which returns which servers are relevant. Only those servers are started.

Use --mcp on any AI command to bypass routing and specify servers directly:

atmos ai ask --mcp aws-iam "List all admin roles"
atmos ai ask --mcp aws-iam,aws-cloudtrail "Who accessed the admin role?"
atmos ai chat --mcp aws-billing

Example: AWS MCP Servers​

atmos.yaml

mcp:
  servers:
    # No credentials needed
    aws-docs:
      command: uvx
      args: ["awslabs.aws-documentation-mcp-server@latest"]
      env:
        FASTMCP_LOG_LEVEL: "ERROR"
      description: "AWS Documentation — search and fetch AWS docs"

    # Requires AWS credentials (uses Atmos Auth)
    aws-pricing:
      command: uvx
      args: ["awslabs.aws-pricing-mcp-server@latest"]
      env:
        AWS_REGION: "us-east-1"
        FASTMCP_LOG_LEVEL: "ERROR"
      description: "AWS Pricing — real-time pricing and cost analysis"
      identity: "readonly"   # Atmos Auth identity (from the auth section)

    # Security assessment (read-only, uses Atmos Auth)
    aws-security:
      command: uvx
      args: ["awslabs.well-architected-security-mcp-server@latest"]
      env:
        AWS_REGION: "us-east-1"
        FASTMCP_LOG_LEVEL: "ERROR"
      description: "AWS Security — Well-Architected security posture assessment"
      identity: "readonly"   # Atmos Auth identity (from the auth section)