# MCP

Atmos supports the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) in both directions: connect Atmos _out_ to external MCP servers (AWS, GCP, custom tooling), or expose Atmos's _own_ tools to your AI assistant.

> ⚠️ Experimental

Without Atmos, MCP server config lives separately in every tool -- Claude Code, Cursor, VS Code, Codex, and Gemini each want it their own way. Atmos manages that configuration once, installs it consistently everywhere your team works, and is an MCP server in its own right -- so any of those same clients can call Atmos's own tools back.

**As a Client**

Connects Atmos to external MCP servers and installs them into your AI coding assistant.

Config key: `mcp.servers` · [Learn more](#as-a-client)

**As a Server**

Exposes Atmos's own tools (`describe`, `list`, `validate`, and more) to AI assistants.

Config key: `mcp.enabled` · [Learn more](#as-a-server)

**As a Hub**

Define MCP servers once in `atmos.yaml`, then keep Atmos and every AI coding assistant on your team working from the same servers.

Command: `atmos mcp install` · [Learn more](#as-a-client)

## As a Client

Connect Atmos to external MCP servers -- AWS documentation, pricing, security tooling, or your own custom servers -- and install them straight into the AI coding assistant you already use: Claude Code, Cursor, VS Code, Codex, or Gemini.

The same servers are also available directly inside `atmos ai chat`/`ask`/`exec`, Atmos's own [agent harness](/ai#agent-harness), with no installation step at all -- see [MCP](/ai#mcp) on the Atmos AI page for smart routing and CLI pass-through details.

### Quick Start

#### 1. Add a server

```shell
# Add a server without hand-editing YAML.
atmos mcp add "uvx awslabs.aws-documentation-mcp-server@latest" --name aws-docs
```

`atmos mcp add` writes the entry to `mcp.servers` in `atmos.yaml` for you — see [Built-in Presets](#built-in-presets) below for the fastest path, or configure `mcp.servers` by hand:

**File:** `atmos.yaml`

```yaml
mcp:
  servers:
    aws-docs:
      command: uvx
      args: ["awslabs.aws-documentation-mcp-server@latest"]
      description: "AWS Documentation — search and fetch AWS docs"
```

#### 2. List, install, and confirm

```shell
# See what's configured
atmos mcp list

# Install into detected AI clients (Claude Code, Cursor, VS Code, Codex, Gemini)
atmos mcp install

# Confirm it's connected
atmos mcp status
```

That's it — the server is now available inside your AI client alongside its built-in tools.

### Built-in Presets

Two servers are always available as named shortcuts for `atmos mcp add` — no URL or command to type out:

- **`atmos mcp add self`**
  Adds Atmos's own MCP server (writes an entry that runs 
  `atmos mcp start`
  ) as 
  `mcp.servers.atmos`
  . Prompts to enable 
  `mcp.enabled`
   if it's off — the entry won't work at runtime until Atmos can run as an MCP server itself. See 
  [As a Server](#as-a-server)
   below.
- **`atmos mcp add atmos-pro`**
  Adds the Atmos Pro MCP server (
  `https://atmos-pro.com/mcp`
  ) as 
  `mcp.servers.atmos-pro`
  . If Atmos Pro is already configured (
  `settings.pro.workspace_id`
  ) but this preset hasn't been added, 
  `atmos mcp list`
  /
  `status`
   print a reminder.

Running `atmos mcp add` with no argument at all defaults to `atmos mcp add self`.

### Setting Up

#### Configuring servers

Servers are declared under `mcp.servers` in `atmos.yaml`, as local `stdio` processes or remote `http` endpoints. Servers with an `identity` are automatically wrapped with `atmos auth exec` so credentials are injected when the client starts them. See [MCP Configuration](/cli/configuration/mcp) for the full settings reference.

#### Transport types

`type: stdio` spawns a local subprocess and talks to it over stdin/stdout -- no network exposure, one client per process. `type: http` connects to a remote endpoint using the **Streamable HTTP** transport (a single endpoint, optionally upgrading to a stream) -- use it for servers that already run remotely, like Atmos Pro or a shared internal MCP server. [`atmos mcp start --transport http`](/cli/commands/mcp/start) speaks this same transport, so one Atmos instance can connect to another over `http` too -- though the [`self` preset](#built-in-presets) still defaults to `stdio`, since it's simpler when both sides run on the same machine.

#### Installing into your client

`atmos mcp install` writes directly into each client's own config format and location:

- **Detected clients** — with no `--client` flag, Atmos detects clients already configured in the project and installs into those.
- **Explicit clients** — pass `--client` (repeatable) to target specific clients, or `--all-clients` to install into every supported client.
- **Scope** — `--scope project` (default) writes into the current project; `--scope user` (or the `--global` alias) writes into the client's user-level config so it's available across all your projects.
- **Preview first** — `--dry-run` shows what would be written without touching any files.

See the [`atmos mcp install`](/cli/commands/mcp/install) command reference for the full flag list and more examples.

Prefer a single portable `.mcp.json` instead of per-client installs? Use [`atmos mcp export`](/cli/commands/mcp/export).

### Managing Servers

- **[`atmos mcp add`](/cli/commands/mcp/add)**
  Add a server to 
  `mcp.servers`
   in 
  `atmos.yaml`
  .
- **[`atmos mcp remove`](/cli/commands/mcp/remove)**
  Remove a server from 
  `mcp.servers`
   in 
  `atmos.yaml`
  .
- **[`atmos mcp list`](/cli/commands/mcp/list)**
  List configured servers and their status.
- **[`atmos mcp install`](/cli/commands/mcp/install)**
  Install configured servers into your AI client's config.
- **[`atmos mcp uninstall`](/cli/commands/mcp/uninstall)**
  Remove installed servers from your AI client's config.
- **[`atmos mcp export`](/cli/commands/mcp/export)**
  Export a portable 
  `.mcp.json`
   file.
- **[`atmos mcp status`](/cli/commands/mcp/status)**
  Show live connection status for all configured servers.
- **[`atmos mcp test`](/cli/commands/mcp/test)**
  Test connectivity to a specific server.
- **[`atmos mcp restart`](/cli/commands/mcp/restart)**
  Validate that a server can stop and restart cleanly.
- **[`atmos mcp tools`](/cli/commands/mcp/tools)**
  List the tools exposed by a server.

## As a Server

Atmos can also run as an MCP server itself, so Claude Desktop, Claude Code, Cursor, VS Code, and other MCP-capable clients can call Atmos's own tools (`describe`, `list`, `validate`, and more) directly, without leaving your AI assistant.

### Quick Start

```shell
# Adds mcp.servers.atmos (command: atmos mcp start), prompting to enable
# mcp.enabled if it's off, then pushes it into detected AI clients.
atmos mcp add self --install
```

That's the fast path — `add self` is a shortcut for the [`self` built-in preset](#built-in-presets) covered above. It writes `mcp.enabled: true` and the client entry for you, using the same [`atmos mcp add`](/cli/commands/mcp/add)/[`atmos mcp install`](/cli/commands/mcp/install) commands used for external servers.

Prefer to do it by hand, or need per-client setup steps (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Continue, Codex, Gemini CLI, Grok CLI, transport modes, security considerations for remote/HTTP access)? See [MCP Server Integration](/ai/mcp-server) for the full manual walkthrough.

## As a Client vs. As a Server

Not sure which direction you need? Both can be enabled at once and don't conflict:

- **As a Client** — you want Atmos to _use_ other tools (AWS docs, pricing, security scanners) from inside `atmos ai chat`/`ask`/`exec`, or to hand those same external servers to your AI coding assistant.
- **As a Server** — you want your AI coding assistant to _use_ Atmos's own tools (describe stacks, list components, validate config) without shelling out to the `atmos` CLI manually.