CLI Reference

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.

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

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

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:

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

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:

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

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

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

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

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:

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

Get Started

MCP Agent SDK

Deployment

Test and Evaluate

Reference

Quick reference

Primary workflows

Log in to MCP Agent Cloud

Initialise a project (`mcp-agent init`)

Deploy an application (`mcp-agent deploy`)

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

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

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

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

Cloud management commands

Local development helpers

​Quick reference

​Primary workflows

​Log in to MCP Agent Cloud

​Initialise a project (mcp-agent init)

​Deploy an application (mcp-agent deploy)

​List deployed servers (mcp-agent cloud servers list)

​Install a deployed MCP server (mcp-agent install)

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

​Configure a deployed server (mcp-agent cloud configure)

​Cloud management commands

​Local development helpers

Quick reference

Primary workflows

Log in to MCP Agent Cloud

Initialise a project (`mcp-agent init`)

Deploy an application (`mcp-agent deploy`)

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

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

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

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

Cloud management commands

Local development helpers