> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-agent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Work with mcp-agent projects and MCP Agent Cloud from the command line.

The `mcp-agent` CLI is the primary interface for project scaffolding, deployment, and day‑to‑day management of MCP Agent Cloud. Run commands ad hoc with `uvx mcp-agent …` (no install required). If `mcp-agent` is listed in your project dependencies, `uv run mcp-agent …` executes inside that environment.

<Tip>
  Every command honours the global flags `--verbose/-v`, `--quiet/-q`, `--format <text|json|yaml>`, `--color/--no-color`, and `--version`.
</Tip>

## Quick reference

| Command                              | Purpose                                             | Example                                                                     |
| :----------------------------------- | :-------------------------------------------------- | :-------------------------------------------------------------------------- |
| `login`                              | Authenticate with MCP Agent Cloud.                  | `uvx mcp-agent login --no-open`                                             |
| `init`                               | Scaffold a project from a template.                 | `uvx mcp-agent init --template basic --dir apps/agent`                      |
| `init --quickstart`                  | Copy a curated quickstart example.                  | `uvx mcp-agent init --quickstart workflow --dir ./workflow-demo`            |
| `deploy <APP_NAME>`                  | Package the current directory and deploy it.        | `uvx mcp-agent deploy research-agent --non-interactive`                     |
| `cloud servers list`                 | List deployed or configured servers.                | `uvx mcp-agent cloud servers list --filter prod --format json`              |
| `cloud env list`                     | Inspect deployment environment secrets.             | `uvx mcp-agent cloud env list my-app`                                       |
| `install --client claude_code <URL>` | Register a deployed server with a local MCP client. | `uvx mcp-agent install https://srv_abc.deployments... --client claude_code` |

## Primary workflows

### Log in to MCP Agent Cloud

```bash theme={null}
uvx mcp-agent login
```

| Option           | Description                                              |
| :--------------- | :------------------------------------------------------- |
| `--api-key TEXT` | Provide an existing API key (also reads `MCP_API_KEY`).  |
| `--no-open`      | Prevent the CLI from opening a browser tab during login. |

After authenticating, `uvx mcp-agent cloud auth whoami` confirms the active account (use `uv run mcp-agent …` if you prefer to stay inside your project environment). Run `uvx mcp-agent cloud auth logout` to clear stored credentials.

### Initialise a project (`mcp-agent init`)

Recent CLI changes fold the old `quickstart` command into `mcp-agent init`. You can now scaffold config files or copy full examples from one entry point.

| Flag                  | Description                                                                 |
| :-------------------- | :-------------------------------------------------------------------------- |
| `--dir, -d PATH`      | Destination directory (defaults to `.`).                                    |
| `--template, -t TEXT` | Scaffolding template.                                                       |
| `--quickstart TEXT`   | Copy an example project (backwards compatible with `mcp-agent quickstart`). |
| `--force, -f`         | Overwrite existing files.                                                   |
| `--no-gitignore`      | Skip writing `.gitignore`.                                                  |
| `--list, -l`          | Display available templates with descriptions.                              |
| `interactive`         | Guided prompts for template selection and configuration.                    |

**Scaffolding templates**

| Template  | What you get                                                  |
| :-------- | :------------------------------------------------------------ |
| `basic`   | Asyncio agent with filesystem & fetch servers plus `main.py`. |
| `server`  | MCP server starter with workflow + parallel agent examples.   |
| `token`   | Token accounting example with telemetry and monitoring hooks. |
| `factory` | Router-backed agent factory pattern.                          |
| `minimal` | Bare configuration files—bring your own application code.     |

**Quickstart examples (`--quickstart <name>`)**

| Template                                       | Contents                                                                                                         |
| :--------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- |
| `workflow`                                     | Every workflow pattern (router, deep orchestrator, swarm, parallel).                                             |
| `researcher`                                   | Research assistant use case with routing and evaluation hooks.                                                   |
| `data-analysis`                                | Financial analysis agent that demonstrates multi-server orchestration.                                           |
| `state-transfer`                               | Workflow router showcasing explicit state passing.                                                               |
| `mcp-basic-agent`                              | Finder agent from the README, ready to run via `uvx python main.py` or `uv run main.py`.                         |
| `token-counter`                                | Structured logging + token metering starter.                                                                     |
| `agent-factory`                                | Agent factory with declarative routing rules.                                                                    |
| `basic-agent-server`, `reference-agent-server` | Complete MCP server implementations (asyncio + reference).                                                       |
| `elicitation`, `sampling`, `notifications`     | Packaged MCP server variations installed via `mcp_agent.data.examples`.                                          |
| `hello-world`                                  | Basic cloud-deployable example with simple tool calls.                                                           |
| `mcp`                                          | Comprehensive MCP server example showcasing tools, sampling, elicitation, notifications, prompts, and resources. |
| `temporal`                                     | Temporal integration example with durable workflows and pause/resume patterns.                                   |
| `chatgpt-app`                                  | ChatGPT App with interactive UI widgets (coin flip example with React frontend).                                 |

Examples:

```bash theme={null}
uvx mcp-agent init --template basic --dir apps/research-agent
uvx mcp-agent init --quickstart workflow --dir ./workflow-demo --force
uvx mcp-agent init --list
```

### Deploy an application (`mcp-agent deploy`)

```bash theme={null}
uvx mcp-agent deploy research-app \
  --config-dir ./deploy \
  --ignore-file .deployignore \
  --non-interactive
```

| Option                        | Description                                                                                                    |
| :---------------------------- | :------------------------------------------------------------------------------------------------------------- |
| `APP_NAME`                    | Optional friendly name for the deployment.                                                                     |
| `--config-dir, -c DIRECTORY`  | Directory containing configuration and source (defaults to the working directory).                             |
| `--working-dir, -w DIRECTORY` | Base directory for resolving relative paths.                                                                   |
| `--app-description, -d TEXT`  | Update the app description shown in Cloud.                                                                     |
| `--non-interactive`           | Fail instead of prompting (crucial for CI/CD).                                                                 |
| `--no-auth/--auth`            | Toggle unauthenticated server access (preserves existing setting by default).                                  |
| `--ignore-file FILE`          | Gitignore-style patterns (precedence: CLI > `.mcpacignore` in `--config-dir` > `.mcpacignore` in working dir). |
| `--git-tag / --no-git-tag`    | Create a local git tag for the deployment.                                                                     |
| `--retry-count INTEGER`       | Deployment retry attempts (1–10, default 3).                                                                   |
| `--api-url`, `--api-key`      | Override Cloud endpoint or use specific credentials (respect env vars).                                        |

Use `--dry-run` for validation without uploading, and let the CLI guide you through classifying developer versus user secrets.

When deployment completes you will see two new artefacts next to your source:

* `mcp_agent.deployed.secrets.yaml` – transformed secrets file containing opaque handles plus an `env` section.
* `mcp_agent.deployed.config.yaml` – the configuration snapshot that the control plane consumes (safe to commit).

Add an `env` list to `mcp_agent.config.yaml` whenever you want to capture environment variables as deployment secrets:

```yaml theme={null}
env:
  - OPENAI_API_KEY              # value read from os.environ
  - {SUPABASE_URL: https://db.example.com}  # fallback literal when the env var is absent
```

Keys are processed in order, pulling from `os.environ` first, then the optional fallback literal. Each value is stored as a secret handle under `env:` in `mcp_agent.deployed.secrets.yaml`.

### List deployed servers (`mcp-agent cloud servers list`)

```bash theme={null}
uvx mcp-agent cloud servers list --filter prod --sort-by -created --format json
uvx mcp-agent cloud servers describe srv_123
```

| Option      | Description                                                                 |
| :---------- | :-------------------------------------------------------------------------- |
| `--limit`   | Maximum number of entries (default 100).                                    |
| `--filter`  | Case-insensitive filter applied to server name, description, or status.     |
| `--sort-by` | Sort by `name`, `created`, or `status` (prefix with `-` for reverse order). |
| `--format`  | Output format (`text`, `json`, `yaml`).                                     |

`cloud servers describe <SERVER_ID>` and `cloud servers workflows <SERVER_ID>` share the same formatting flag and surface deep metadata such as server URLs, current status, and published workflows.

### Install a deployed MCP server (`mcp-agent install`)

```bash theme={null}
uvx mcp-agent install https://srv_abc.deployments.mcp-agent.com \
  --client claude_desktop \
  --name research-buddy \
  --dry-run
```

| Option                   | Description                                                                          |
| :----------------------- | :----------------------------------------------------------------------------------- |
| `SERVER_IDENTIFIER`      | HTTPS or SSE URL from the deployment dashboard.                                      |
| `--client, -c TEXT`      | Destination client (`vscode`, `claude_code`, `cursor`, `claude_desktop`, `chatgpt`). |
| `--name, -n TEXT`        | Override the generated client entry name.                                            |
| `--dry-run`              | Print the configuration block without writing to disk.                               |
| `--force, -f`            | Overwrite existing entries.                                                          |
| `--api-url`, `--api-key` | Override Cloud endpoints or credentials (fallback to env vars).                      |

For authenticated clients, the CLI injects `MCP_API_KEY` automatically. Use `--dry-run` when sharing configuration snippets or validating changes before committing them.

### Tail logs for a running application (`mcp-agent cloud logger tail`)

```bash theme={null}
uvx mcp-agent cloud logger tail srv_abc123 --follow
```

| Option                          | Description                                                                                                  |           |
| :------------------------------ | :----------------------------------------------------------------------------------------------------------- | --------- |
| `--follow/-f`                   | Stream logs continuously (mutually exclusive with `--since`, `--limit`, `--order-by`, `--asc`, or `--desc`). |           |
| `--grep`                        | Filter log messages using a regex (e.g., \`--grep "ERROR                                                     | WARN"\`). |
| `--format`                      | Render output as `text`, `json`, or `yaml`.                                                                  |           |
| `--limit/-n`                    | Maximum entries to fetch in batch mode (default 100).                                                        |           |
| `--since`                       | Show logs from a relative duration (e.g., `1h`, `30m`).                                                      |           |
| `--order-by`, `--asc`, `--desc` | Sort batched results (default is newest first).                                                              |           |

Use streaming (`--follow`) when you need real-time visibility; combine `--since` with `--grep` to audit historical runs.

### Configure a deployed server (`mcp-agent cloud configure`)

```bash theme={null}
uvx mcp-agent cloud configure \
  --id https://srv_base.deployments.mcp-agent.com/mcp \
  --secrets-file team-secrets.yaml
```

| Option                     | Description                                                                         |
| :------------------------- | :---------------------------------------------------------------------------------- |
| `--id/-i`                  | Server URL to clone and configure with your own secrets.                            |
| `--secrets-file/-s`        | YAML file containing values for required user secrets.                              |
| `--secrets-output-file/-o` | Destination for prompted secrets (defaults to `mcp_agent.configured.secrets.yaml`). |
| `--params`                 | List required secrets and exit without configuring.                                 |
| `--dry-run`                | Validate required parameters using mock clients without persisting secrets.         |
| `--api-url`, `--api-key`   | Override Cloud endpoint or credentials.                                             |

This workflow lets you adopt a published server template, supply your credentials (LLM keys, database passwords, etc.), and produce a new server deployment associated with your account.

## Cloud management commands

* **Apps (`mcp-agent cloud apps …`)** – manage logical applications.
  * `apps status <APP_ID>` displays health, version, and associated servers.
  * `apps workflows <APP_ID>` enumerates workflows exposed by that app.
  * `apps delete <APP_ID>` removes the application; `apps update` refreshes metadata.

* **Logs (`mcp-agent cloud logger tail …`)** – fetch or stream logs.
  * `--since 1h`, `--grep`, `--limit/-n`, and `--order-by timestamp|severity` tune batch retrieval.
  * `--follow/-f` enables streaming (mutually exclusive with the filtering flags).
  * `--format text|json|yaml` controls output.

* **Configure (`mcp-agent cloud configure --id <SERVER_URL> …`)** – collect user secrets after deployment.
  * `--secrets-file/-s` reuses an authored secrets.yaml.
  * `--secrets-output-file/-o` chooses where prompted secrets are written (defaults to `mcp_agent.configured.secrets.yaml`).
  * `--params` lists required secrets and exits.
  * `--dry-run` validates using mock clients without persisting anything.

* **Env (`mcp-agent cloud env …`)** – manage environment secrets captured during deploy.
  * `env list [APP]` displays stored environment keys with masked handles.
  * `env add <KEY> <VALUE> [APP]` (or `--from-env-file .env.local`) creates or updates secret values (`apps/<app_id>/env/<KEY>`).
  * `env remove <KEY> [APP]` deletes the stored handle.
  * `env pull [APP] --format env|yaml --output <FILE>` downloads resolved values as either a dotenv file (default `.env.mcp-cloud`) or a YAML file. `.env` is loaded first (developer overrides), followed by `.env.mcp-cloud`, before config-driven fallbacks are applied.
  * `--app/-a`, `--api-url`, `--api-key` allow per-command overrides (use `--app` when omitting positional arguments or when using `--from-env-file`).

* **Auth (`mcp-agent cloud auth …`)** – the same login, whoami, and logout commands exposed at the top level, handy for scripts.

* **Workflows (`mcp-agent cloud workflows …`)** – inspect and control durable workflow runs.
  * `workflows list <SERVER|URL> [--format text|json|yaml]` lists workflow definitions.
  * `workflows runs <SERVER|URL>` surfaces recent executions.
  * `workflows describe|status <SERVER> <RUN_ID>` shows execution details.
  * `workflows resume|suspend|cancel <SERVER> <RUN_ID>` manipulates in-flight runs.

Example session:

```bash theme={null}
# Inspect available servers
uvx mcp-agent cloud servers list

# Tail logs for a specific deployment
uvx mcp-agent cloud logger tail srv_abc123 --follow

# Resume a paused workflow run
uvx mcp-agent cloud workflows resume srv_abc123 run_xyz789

# Review required secrets before configuring an app
uvx mcp-agent cloud configure --id https://srv_abc123.deployments.mcp-agent.com/mcp --params
```

## Local development helpers

* `mcp-agent dev start` – run your app locally with optional file watching (auto-detects `main.py`, then `agent.py` when `--script` is omitted). Companion subcommands include `dev chat`, `dev go`, `dev invoke`, `dev serve`, `dev logs`, `dev keys`, and `dev models`.
* `mcp-agent config show|check|edit|builder` – inspect YAML, validate schemas, or generate config files with an interactive questionnaire (`builder` supports templates and expert mode).
* `mcp-agent doctor` – end-to-end diagnostics across configuration, secrets, provider keys, required MCP servers, and network connectivity.
* `mcp-agent install --dry-run` – even for local experiments, emit ready-to-paste client snippets without touching disk.

These commands respect the same settings discovery as the runtime: preload strings (`MCP_APP_SETTINGS_PRELOAD`), explicit paths, discovered `mcp_agent.config.yaml`/`mcp_agent.secrets.yaml`, and environment variables. Append `--help` whenever you need the latest options or examples.