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