# atmos mcp add

Use this command to add an MCP server to `mcp.servers` in `atmos.yaml` without hand-editing YAML.

> ⚠️ Experimental

## Description

The `atmos mcp add` command writes a new entry under `mcp.servers` in `atmos.yaml`. The target can be:

- A **built-in preset** — `self` (Atmos's own MCP server) or `atmos-pro` (the Atmos Pro MCP server).
- An **`http(s)://` URL** — added as a remote HTTP server.
- A **stdio command** — added as a local subprocess server, optionally with arguments (e.g. `"npx -y @org/mcp-server --flag value"`).

Running `atmos mcp add` with no target defaults to `atmos mcp add self`.

### Which file is edited

`add` (and `remove`) edit the config file whose value is actually in effect for the server, so an edit is never silently shadowed by a higher-precedence file. Without an explicit `--config`, the target is resolved by the server's effective provenance:

- **Overwrite** an existing server: the highest-precedence file that already declares `mcp.servers.<name>` (Atmos reapplies the root `atmos.yaml` over its imports, so a root entry wins over a fragment).
- **New** server: the highest-precedence file that already declares `mcp.servers` - typically an auto-discovered [`.atmos.d/`](/cli/configuration#automatic-configuration-imports-atmosd) (or `atmos.d/`) fragment - so a modular-config project is not silently split across the root `atmos.yaml` and a fragment. If nothing declares `mcp.servers`, the root `atmos.yaml` is used.
- **`mcp.enabled`** (flipped when adding the `self` preset): written to the highest-precedence file that already declares it, else the root `atmos.yaml`, so enabling actually takes effect.

Precedence follows the config loader: an [active profile](/cli/configuration/profiles) (via `--profile`, `ATMOS_PROFILE`, or `profiles.default`) is merged over the root `atmos.yaml`, so a profile that declares the key is edited ahead of the root; the root is in turn ahead of `.atmos.d/`/`atmos.d/` fragments, and within a fragment directory a later file overrides an earlier one. Only effective config roots are searched (the git repository root always; the current working directory only when it has its own root `atmos.yaml`). Pass `--config <file>` to target a specific file explicitly.

Only the config file is written - `add` never touches an AI client's config file. Use `--install` to also push the new server into detected AI clients in the same step, or run [`atmos mcp install`](/cli/commands/mcp/install) separately.

If the target resolves to the `self` preset and `mcp.enabled` is `false` in `atmos.yaml`, `add` prompts (when running interactively) to enable it — the `self` entry won't work at runtime until Atmos can run as an MCP server itself. Non-interactively, it errors with the exact `atmos config set` command to run instead.

## Usage

```shell
atmos mcp add [preset-name|url|command] [flags]
```

- **`preset-name|url|command`** — Optional. A built-in preset name (`self`, `atmos-pro`), an `http(s)://` URL, or a stdio command. Defaults to `self` when omitted.
- **`--name`, `-n`** — Server name. Auto-inferred from the URL or command if not provided (presets use their own default name, e.g. `self` → `atmos`).
- **`--transport`, `-t`** — Transport for a URL target. Only `http` is supported today; other values (e.g. `sse`) are rejected.
- **`--env`** — Environment variable for a stdio server, `KEY=VALUE` (repeatable).
- **`--header`, `-H`** — HTTP header for a remote server, `"Key: Value"` (repeatable).
- **`--description`** — Human-readable description shown in `atmos mcp list`/`status`.
- **`--identity`** — Atmos Auth identity (from the `auth` section) for credential injection.
- **`--timeout`** — Connection timeout, as a Go duration string (e.g. `30s`).
- **`--auto-start`** — Start the server automatically when Atmos starts.
- **`--install`** — Also install into detected AI clients immediately after adding.
- **`--yes`, `-y`** — Skip confirmation prompts.
- **`--force`** — Overwrite an existing entry without prompting.

### Examples

```shell
# Add Atmos's own MCP server (also the default target with no argument).
atmos mcp add self

# Add the Atmos Pro MCP server.
atmos mcp add atmos-pro

# Add a remote HTTP server with an auth header.
atmos mcp add https://mcp.example.com/mcp --header "Authorization: Bearer ${TOKEN}"

# Add a local stdio server and immediately install it into detected AI clients.
atmos mcp add "uvx awslabs.aws-documentation-mcp-server@latest" --install

# Add a server with an explicit name, description, and Atmos Auth identity.
atmos mcp add uvx --name aws-docs --description "AWS Documentation" --identity readonly
```