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

| Feature                    | What It Does                                                                      | Config Key    |
|----------------------------|-----------------------------------------------------------------------------------|---------------|
| **MCP Server**             | Exposes Atmos AI tools to external clients (Claude Desktop, Claude Code, VS Code) | `mcp.enabled` |
| **MCP Server Connections** | Connects Atmos to external MCP servers (AWS, GCP, custom)                         | `mcp.servers` |

## Quick Start

**File:** `atmos.yaml`

```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.

:::info 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](/cli/configuration/ai/tools) 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.

**File:** `atmos.yaml`

```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](#yaml-functions-in-env-values)
   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`](/cli/configuration/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:

**File:** `atmos.yaml`

```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](/cli/configuration/auth) to automatically inject AWS credentials:

**File:** `atmos.yaml`

```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](/cli/configuration/toolchain):

**File:** `atmos.yaml`

```yaml
toolchain:
  aliases:
    uv: astral-sh/uv
```

```bash
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 Provider | Config Delivery | Notes |
|---|---|---|
| Claude Code | `--mcp-config` temp file | Full 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:

```bash
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.

**File:** `atmos.yaml`

```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:

```bash
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

**File:** `atmos.yaml`

```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)
```

---

## Related Commands