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

# CLI Reference

> Command reference for the @mcp-use/cli package and mcp-use executable.

The `mcp-use` package installs the `mcp-use` executable and includes the prebuilt `@mcp-use/cli` implementation. Use this page as the exhaustive command reference for local development, production builds, cloud deploys, saved MCP client sessions, and CLI environment variables.

For hands-on workflows, see the [CLI Client guide](/v2/typescript/tooling/client-cli), [Tunneling guide](/tunneling/index), and [Manufact Cloud deployment guide](/v2/typescript/server/deployment/mcp-use).

## Command map

<CardGroup cols={2}>
  <Card title="Run locally" icon="flame" href="#dev">
    `mcp-use dev` starts the development server, view watcher, and Inspector.
  </Card>

  <Card title="Build and start" icon="box" href="#build">
    `mcp-use build` writes production artifacts. `mcp-use start` runs the built
    server.
  </Card>

  <Card title="Deploy" icon="cloud-upload" href="#deploy">
    `mcp-use deploy`, `mcp-use deployments`, and `mcp-use servers` manage
    Manufact Cloud resources.
  </Card>

  <Card title="Client CLI" icon="terminal" href="#client">
    `mcp-use client` saves MCP servers, calls tools, reads resources, gets
    prompts, and handles OAuth.
  </Card>

  <Card title="Tunnels" icon="train-front-tunnel" href="#tunneling-reference">
    `mcp-use dev --tunnel` exposes a local server through a public URL.
  </Card>

  <Card title="Typecheck" icon="wand" href="#typecheck">
    `mcp-use typecheck` refreshes MCP view types and runs the project's own
    TypeScript compiler.
  </Card>
</CardGroup>

## Install the CLI

Most projects install the framework, CLI, and Inspector together:

```bash theme={null}
npm install mcp-use
```

The CLI package can also be installed directly:

```bash theme={null}
npm install -g @mcp-use/cli
```

```bash theme={null}
npx @mcp-use/cli dev
```

```bash theme={null}
npm install --save-dev @mcp-use/cli
```

<Tip>
  `create-mcp-use-app` installs `mcp-use`, which supplies the CLI and Inspector
  at matching versions.
</Tip>

## `dev`

**Purpose:** Start a development server with TypeScript watching, view builds, automatic reloads, and the Inspector.

**Syntax:**

```bash theme={null}
mcp-use dev [options]
```

**Options:**

| Option | Description | Default |
| - | - | - |
| `--path <path>` | Project root used for entry/view discovery, `.env`, and `tsconfig.json`. | Current directory |
| `--entry <file>` | MCP server entry file, relative to the project. | Auto-detected |
| `--mcp-dir <dir>` | MCP source directory containing the entry and `views/`. | None |
| `--views-dir <dir>` | View directory, relative to the project root. | `views/` or `<mcp-dir>/views/` |
| `--port <port>` | Server port. | `PORT` or `3000` |
| `--host <host>` | Bind address. Use `0.0.0.0` to listen on all interfaces. | `HOST` or `127.0.0.1` |
| `--no-open` | Do not open the Inspector automatically. | Opens by default |
| `--no-inspector` | Run without loading the project-local Inspector. | Inspector enabled |
| `--tunnel` | Create a public tunnel for the local server. | Disabled |

**Examples:**

```bash theme={null}
mcp-use dev
mcp-use dev --port 8080
mcp-use dev --host 127.0.0.1 --no-open
mcp-use dev --mcp-dir src/mcp
mcp-use dev --entry src/server.ts --views-dir src/views
mcp-use dev --path apps/web --entry ../mcp/src/server.ts --views-dir ../mcp/src/views
mcp-use dev --tunnel
```

**Notes and behavior:**

* The MCP endpoint is served at `/mcp`.
* Address precedence is `--port` / `--host`, then `PORT` / `HOST`, then the defaults. `dev` does not import the server until after its listener is chosen, so it cannot use a server-configured address.
* The Inspector supplied by `mcp-use` is mounted at `/mcp/inspector` and opens automatically unless `--no-open` is set.
* Inspector UI, proxy, and OAuth routes remain local-only. A public tunnel exposes the MCP endpoint but returns `404` for `/mcp/inspector`.
* The command sets `NODE_ENV=development` when it is not already set and sets `PORT` to the chosen listener port before importing the entry.
* When `MCP_URL` is unset and the listener binds a loopback host, the command sets `MCP_URL` to `http://localhost:<port>` only while it imports the entry, so module-scope OAuth configuration sees the local origin. Request handlers and tool code do not see this value. With `--tunnel`, the command still sets this local value and does not replace it with the public tunnel URL.
* Source changes reload the exported server without dropping the long-lived HTTP listener. View modules use Vite HMR when views exist at startup.
* Adding the first view to a project that started with none requires restarting `mcp-use dev`.
* `mcp-use dev` keeps its Vite cache in `.mcp-use/cache/` and the tunnel subdomain in `.mcp-use/state/tunnel.json`.
* See [Tunneling reference](#tunneling-reference) for the lifecycle and limits of `--tunnel`.

## `typecheck`

**Purpose:** Refresh the managed `mcp-env.d.ts` declaration for the discovered server entry, then run the project's installed TypeScript compiler with `--noEmit`.

**Syntax:**

```bash theme={null}
mcp-use typecheck [options] [-- <tsc-options>]
```

The command accepts `--path`, `--entry`, and `--mcp-dir` with the same meanings as `dev` and `build`. Arguments after `--` are forwarded to TypeScript:

```bash theme={null}
mcp-use typecheck
mcp-use typecheck --entry src/server.ts
mcp-use typecheck -- --project tsconfig.check.json --pretty false
```

`mcp-env.d.ts` is scaffolded into new projects, so editors and plain `tsc --noEmit` work before the first CLI run. The command refreshes declarations carrying an mcp-use generated header when the entry changes and never overwrites a user-owned declaration. TypeScript must be installed in the selected project.

## `build`

**Purpose:** Build the exported MCP server and its views into `.mcp-use/build/`.

**Syntax:**

```bash theme={null}
mcp-use build [options]
```

**Options:**

| Option | Description | Default |
| - | - | - |
| `--path <path>` | Project root used for entry/view discovery, `.env`, and `tsconfig.json`. | Current directory |
| `--entry <file>` | MCP server entry file, relative to the project. | Auto-detected |
| `--mcp-dir <dir>` | MCP source directory containing the entry and `views/`. | None |
| `--views-dir <dir>` | View directory, relative to the project root. | `views/` or `<mcp-dir>/views/` |
| `--source-maps` | Emit source maps for server and external view bundles. | Disabled |
| `--inline` | Embed each view's bundled JavaScript and CSS in its MCP resource. | Disabled |

**Examples:**

```bash theme={null}
mcp-use build
mcp-use build --inline
mcp-use build --mcp-dir src/mcp
mcp-use build --entry src/server.ts --views-dir src/views
mcp-use build --path ./my-server
```

**Notes and behavior:**

* The command bundles the default-exported server as `.mcp-use/build/index.js` and writes `.mcp-use/build/manifest.json`.
* Each `views/<name>/view.tsx` builds to hashed external assets under `.mcp-use/build/views/<name>/` by default.
* Pass `--inline` to embed each view's bundled JavaScript and CSS directly in the HTML returned by `resources/read`. There is no `--no-inline`; omit `--inline` to use external assets.
* The build is transpile-only. Run `mcp-use typecheck` as a separate project script when type checking is required.
* TypeScript path aliases come from the selected project's `tsconfig.json`.
* If `MCP_ASSETS_URL` is set for an external build, view paths are rewritten to that asset origin using the server's `basePath`. Inline view bundles are not rewritten.
* The selected project's `public/` directory is copied to `.mcp-use/build/views/public/`.

## `start`

**Purpose:** Run the production server previously written to `.mcp-use/build/`.

**Syntax:**

```bash theme={null}
mcp-use start [options]
```

**Options:**

| Option | Description | Default |
| - | - | - |
| `--path <path>` | Project root containing `.mcp-use/build/`. | Current directory |
| `--port <port>` | Server port. | `PORT`, server config, or `3000` |
| `--host <host>` | Bind address. Use `0.0.0.0` to listen on all interfaces. | `HOST`, server config, or `127.0.0.1` |
| `--with-inspector` | Mount the bundled Inspector at `${basePath}/inspector`. | Disabled |
| `--tunnel` | Create a public tunnel for the production server. | Disabled |

**Examples:**

```bash theme={null}
mcp-use start
mcp-use start --port 8080
mcp-use start --host 0.0.0.0
mcp-use start --with-inspector
mcp-use start --path ./my-server
mcp-use start --tunnel
```

**Notes and behavior:**

* Address precedence is CLI flag, environment variable, server configuration, then default: `--port` → `PORT` → `config.port` → `3000`, and `--host` → `HOST` → `config.host` → `127.0.0.1`.
* `--tunnel` starts the tunnel only after the production server binds. The command prints the public MCP URL and closes the tunnel when the process shuts down.
* The command requires `.mcp-use/build/manifest.json`; run `mcp-use build` first.
* It imports the manifest's built `entryPoint` and requires that module to default-export an `MCPServer`.
* `start` does not rediscover source entries or views. `--entry`, `--mcp-dir`, and `--views-dir` belong to `dev` and `build`.
* The command sets `NODE_ENV=production` when it is not already defined and loads the selected project's production `.env` values before importing the built entry.
* The build manifest never records Inspector state. `--with-inspector` is a runtime-only opt-in that mounts the Inspector on the same listener; it does not rebuild or alter `.mcp-use/build`.
* The Inspector can call tools and proxy OAuth flows. Keep `--with-inspector` behind access controls when serving beyond localhost.

## Tunneling reference

`mcp-use dev --tunnel` and `mcp-use start --tunnel` create a public URL that forwards to the local MCP server.

```bash theme={null}
mcp-use dev --tunnel
mcp-use start --tunnel
```

Tunnel limits and lifecycle:

| Limit or behavior | Value |
| - | - |
| Tunnel lifetime | Expires 24 hours after creation |
| Inactive tunnel cleanup | 1 hour of no activity |
| Creation rate limit | 10 tunnel creations per IP per hour |
| Active tunnel limit | 5 active tunnels per IP |
| Close behavior | The tunnel closes when the CLI process exits |

The standalone package is also available:

```bash theme={null}
npx @mcp-use/tunnel 3000
```

See the [Tunneling guide](/tunneling/index) for client setup and testing workflows.

## `deploy`

**Purpose:** Create or update a Manufact Cloud deployment for an MCP server.

**Syntax:**

```bash theme={null}
mcp-use deploy [path] [options]
```

`[path]` is the project directory. It defaults to the current directory.

**Options:**

| Option | Description | Default |
| - | - | - |
| `--open` | Open the deployment in a browser after a successful deploy. | Disabled |
| `--name <name>` | Server name. Also names the GitHub repository when the CLI creates one. | GitHub repository name; with `--no-github`, the `package.json` name or directory name |
| `--new` | Create a new server instead of reusing the linked project. | Disabled |
| `--env <key=value>` | Environment variable assignment. Repeatable. | None |
| `--env-file <path>` | Load environment variables from a `.env` file. | None |
| `--branch <name>` | Branch to deploy. Also scopes env sync to that branch preview environment. | Current git branch; `main` with `--no-github` |
| `--root-dir <path>` | Root directory inside the repository for monorepos. | Repository root |
| `--org <slug-or-id>` | Target organization. | Active org |
| `-y, --yes` | Accept confirmation prompts and authorize Git and repository changes: creating a private GitHub repository, committing and pushing uncommitted changes, and selecting the default GitHub App installation. | Disabled |
| `--region <region>` | Deployment region: `US`, `EU`, or `APAC`. | `US` |
| `--build-command <cmd>` | Build command override. | Auto-detected |
| `--start-command <cmd>` | Start command override. | Auto-detected |
| `--dockerfile <path>` | Non-default Dockerfile path, relative to `--root-dir` or repository root. | None |
| `--watch-paths <glob>` | Only auto-deploy when matching files change. Repeatable. GitHub only. | All changes |
| `--wait-for-ci` | Hold GitHub auto-deploys until other check runs pass. GitHub only. | Disabled |
| `--no-github` | Upload local source without connecting GitHub. | Disabled |
| `--json` | Emit exactly one JSON result or error. Never prompts or opens a browser; cannot be combined with `--open`. | Human-readable text |

**Examples:**

```bash theme={null}
mcp-use deploy
mcp-use deploy --no-github
mcp-use deploy --name my-server --open
mcp-use deploy --env DATABASE_URL=postgres://... --env API_KEY=secret
mcp-use deploy --env-file .env.production
mcp-use deploy --root-dir apps/mcp-server
mcp-use deploy --root-dir apps/mcp-server --watch-paths "apps/mcp-server/**" --watch-paths "packages/shared/**"
mcp-use deploy --new --name my-server-v2
mcp-use deploy --org manufact-inc --region EU --yes
```

**Notes and behavior:**

* The default path deploys from GitHub. When it creates a new GitHub-backed server and the organization has no GitHub App installation, the command exits with `github_installation_required` and a link to the dashboard settings. If the project has no `origin` remote, an interactive run offers to create a private repository, initialize Git, commit, and push to `main`. If the working tree has uncommitted changes, it offers to commit and push them with `git add .`. `--yes` authorizes these Git changes without prompting.
* `--no-github` packs and uploads local source to a platform-managed repository.
* Redeploys of a project already linked to a platform-managed server auto-detect the upload path. `--no-github` is only required on the first deploy for that path.
* The command writes `.mcp-use/cloud/link.json` to link the local project to the cloud server.
* When it writes the project link, the CLI adds `.mcp-use/` to the repository's local `.git/info/exclude` if that file exists. It writes `.mcp-use/` to `.gitignore` only when it creates a new repository.
* On a redeploy of a linked server, the supplied `--name`, `--branch`, `--region`, `--root-dir`, `--build-command`, `--start-command`, `--dockerfile`, `--watch-paths`, and `--wait-for-ci` values update that server's configuration before the deployment starts.
* Environment variables passed through `--env` and `--env-file` are synced to the target branch preview environment when `--branch` is set.

## Authentication commands

Authentication commands manage the user-level Manufact Cloud credentials in `~/.mcp-use/config.json`.

### `login`

**Purpose:** Authenticate the CLI with Manufact Cloud.

**Syntax:**

```bash theme={null}
mcp-use login [options]
```

**Options:**

| Option | Description | Default |
| - | - | - |
| `--api-key <key>` | Authenticate with an API key. | Browser/device flow |
| `--device-code <code>` | Redeem a short-lived, pre-approved RFC 8628 device code. | None |
| `--org <id-or-slug>` | Select the active organization by ID or slug. | Account default |
| `--no-open` | Do not open the verification URL during interactive login. | Opens on a TTY |
| `--json` | Emit one machine-readable JSON result. | Human-readable text |

**Examples:**

```bash theme={null}
mcp-use login
mcp-use login --device-code ABC123
mcp-use login --api-key mcp_... --org my-org
```

**Notes and behavior:**

* Interactive login starts a device-code flow and opens a browser.
* `--device-code` skips the browser and redeems the code through the same token endpoint. The CLI then creates, validates, and stores a persistent API key.
* `--api-key` and `--device-code` cannot be combined. An explicit `--device-code` takes precedence over `MCP_USE_API_KEY`.
* The CLI never writes the device code, bearer token, or API key to human-readable or JSON output.
* If `--org` is omitted, the CLI stores the account-default organization when one is available.
* `MCP_USE_API_KEY` can provide the API key for non-interactive login.

### `whoami`

**Purpose:** Print the current authentication status and user information.

**Syntax:**

```bash theme={null}
mcp-use whoami
```

**Options:**

| Option | Description | Default |
| - | - | - |
| `--json` | Emit a machine-readable identity object. | Human-readable text |

**Examples:**

```bash theme={null}
mcp-use whoami
```

**Notes and behavior:** The command reads `~/.mcp-use/config.json`. When that file selects no organization, it reports the account default, matching `org current` and the `servers`/`deployments` commands. This is the usual case when authenticating with `MCP_USE_API_KEY` instead of `mcp-use login`.

### `logout`

**Purpose:** Remove saved Manufact Cloud credentials.

**Syntax:**

```bash theme={null}
mcp-use logout [options]
```

**Options:**

| Option | Description | Default |
| - | - | - |
| `--yes` | Skip confirmation. Required for non-interactive and JSON runs. | Prompts on a TTY |
| `--json` | Emit one machine-readable JSON result. | Human-readable text |

**Examples:**

```bash theme={null}
mcp-use logout --yes
```

**Notes and behavior:** The command removes credentials from `~/.mcp-use/config.json`.

## Organization commands

Organization commands control the active Manufact Cloud organization for cloud commands.

| Command | Purpose | Syntax |
| - | - | - |
| `org list` | List organizations available to the authenticated user. | `mcp-use org list` |
| `org current` | Show the active organization. | `mcp-use org current` |
| `org use <id-or-slug>` | Select and persist a different active organization. | `mcp-use org use <id-or-slug>` |

**Notes and behavior:**

* `deploy`, `deployments`, and `servers` use the active organization unless `--org` overrides it.
* For CI or agent runs, pass `--org <org>` to `login`, `deploy`, `servers`, or `deployments` commands instead of switching global state. The value can be an organization slug, ID, or name.

## Deployment management commands

**Purpose:** Inspect and manage existing Manufact Cloud deployments.

**Syntax:**

```bash theme={null}
mcp-use deployments <subcommand> [options]
```

**Subcommands:**

| Subcommand | Purpose | Options |
| - | - | - |
| `list` | List deployments. | `--org <id-or-slug>`, `--server <id>`, `--limit <n>`, `--skip <n>`, `--json` |
| `get <deployment-id>` | Show deployment details. | `--json` |
| `logs <deployment-id>` | View runtime logs. | `--build`, `--follow`, `--json` |
| `restart <deployment-id>` | Trigger a new deployment on the same server. | `--follow`, `--branch <name>`, `--json` |
| `stop <deployment-id>` | Stop a running deployment. | `--yes`, `--json` |
| `delete <deployment-id>` | Delete a deployment. | `--yes`, `--json` |

**Examples:**

```bash theme={null}
mcp-use deployments list
mcp-use deployments get dep_abc123
mcp-use deployments logs dep_abc123 --build --follow
mcp-use deployments restart dep_abc123 --branch main --follow
mcp-use deployments stop dep_abc123 --yes
mcp-use deployments delete dep_abc123 --yes
```

**Notes and behavior:**

* `logs` shows runtime logs by default. Use `--build` for build logs.
* `restart` redeploys the same server and uses the deployment branch unless `--branch` is set.
* `stop` and `delete` prompt for confirmation on a TTY. Pass `--yes` in non-interactive or JSON runs.

## Server management commands

**Purpose:** Manage cloud servers, which are long-lived Git-backed deploy targets that own deployments.

**Syntax:**

```bash theme={null}
mcp-use servers <subcommand> [options]
```

**Subcommands:**

| Subcommand | Purpose | Options |
| - | - | - |
| `list` | List servers for an organization. | `--org <slug-or-id>`, `--limit <n>`, `--skip <n>` |
| `get <id-or-slug>` | Show server details and recent deployments. | `--org <slug-or-id>` |
| `update <id-or-slug>` | Update server configuration. | `--branch <name>`, `--name <name>`, `--description <text>`, `--build-command <cmd>`, `--start-command <cmd>`, `--root-dir <path>`, `--watch-paths <glob>`, `--deploy-branches <glob>`, `--wait-for-ci`, `--no-wait-for-ci`, `--org <slug-or-id>` |
| `delete <server-id>` | Delete a server and its deployments. | `--yes`, `--org <slug-or-id>` |
| `env <subcommand>` | Manage server environment variables. | See [Server environment commands](#server-environment-commands). |

**Examples:**

```bash theme={null}
mcp-use servers list
mcp-use servers get srv_abc123
mcp-use servers update srv_abc123 --branch main
mcp-use servers update srv_abc123 --build-command "npm run build"
mcp-use servers update srv_abc123 --watch-paths "apps/api/**" --watch-paths "packages/shared/**" --deploy-branches "release/*"
mcp-use servers delete srv_abc123 --yes
```

**Notes and behavior:**

* `servers update --branch` changes the production branch for future production deploys.
* `--watch-paths` and `--deploy-branches` are repeatable. Pass the flag once per pattern; a second bare value is read as a positional, not as another pattern.
* Pass an empty string to `--build-command`, `--start-command`, `--root-dir`, `--watch-paths`, or `--deploy-branches` to clear that setting.
* `--wait-for-ci` and `--no-wait-for-ci` control whether auto-deploys wait for other check runs before deploying.
* `servers delete` prompts for confirmation unless `--yes` is set.

## Server environment commands

**Purpose:** List, set, and unset environment variables on a cloud server.

**Syntax:**

```bash theme={null}
mcp-use servers env <subcommand> [options]
```

**Subcommands:**

| Subcommand | Purpose | Required arguments | Other options |
| - | - | - | - |
| `list <server>` | List environment variable metadata. | Server ID or slug | `--org <id-or-slug>`, `--branch <name>` |
| `set <server> <KEY=VALUE>` | Create or update an environment variable. | Server ID or slug, value | `--org <id-or-slug>`, `--branch <name>`, `--secret` |
| `unset <server> <key>` | Delete an environment variable by key. | Server ID or slug, key | `--org <id-or-slug>`, `--branch <name>`, `--yes` |

**Examples:**

```bash theme={null}
mcp-use servers env list srv_abc123
mcp-use servers env list srv_abc123 --branch feature/example
mcp-use servers env set srv_abc123 API_KEY=secret --secret
mcp-use servers env set srv_abc123 FEATURE_FLAG=true --branch feature/example
mcp-use servers env unset srv_abc123 API_KEY --yes
```

**Notes and behavior:**

* `env list` returns metadata only. Values are never returned.
* `env set` creates a production variable when `--branch` is omitted, or a preview variable when it is supplied.
* `--secret` stores a value as write-only. It must be passed on **every** write to the variable, including updates and rotations: omitting it stores the value as non-sensitive, even if the variable was previously write-only.
* `--branch <name>` scopes preview environment variables to a branch. Omit `--branch` for production resolution.
* `env unset` prompts for confirmation unless `--yes` is set. If the key doesn't exist in the selected production or branch scope, it fails with `env_variable_not_found`.

## `client`

**Purpose:** Save HTTP MCP server connections, call tools, read resources, get prompts, and manage OAuth credentials from the terminal.

**Syntax:**

```bash theme={null}
mcp-use client <subcommand>
mcp-use client <name> <scope> <action>
```

**Top-level subcommands:**

| Command | Purpose | Key options |
| - | - | - |
| `connect <name> <url>` | Verify and save an HTTP(S) MCP server. | `-H, --header`, `--no-oauth`, `--auth-timeout <ms>`, `--protocol <auto\|legacy\|modern>`, `--no-open`, `--json` |
| `list` | List saved servers. | `--json` |
| `remove <name>` | Remove a saved server and credentials. | `--json` |

**Per-server scopes:**

| Scope | Actions |
| - | - |
| `tools` | `list`, `describe <tool>`, `call <tool> [args...] [--timeout <ms>]` |
| `resources` | `list`, `read <uri>` |
| `prompts` | `list`, `get <prompt> [args...]` |
| `auth` | `login`, `status`, `logout [--yes]` |

Every action in this table accepts `--json` except where the top-level table does not advertise it.

**Examples:**

```bash theme={null}
mcp-use client connect local http://localhost:3000/mcp
mcp-use client list
mcp-use client local tools list
mcp-use client local tools call read_file path=/tmp/test.txt
mcp-use client local resources read "file:///tmp/data.json"
mcp-use client local prompts get greeting name=Alice
mcp-use client local auth login
mcp-use client local auth status
```

**Notes and behavior:**

* Saved server metadata is stored in `~/.mcp-use/client/servers.json`. Credentials are stored separately under `~/.mcp-use/client/credentials/`.
* In an interactive TTY, OAuth displays `This server requires OAuth. Press Enter to open your browser.` and opens the browser only after Enter.
* When protected-resource metadata identifies mixed auth, `connect` succeeds anonymously, reports that public tools are available, and suggests `mcp-use client <name> auth login`. The JSON connection result includes `authorization` metadata.
* `auth login` starts OAuth for an already-saved server; otherwise the first wire-level OAuth challenge can start the flow later and the CLI retries that operation once.
* `--no-open` and non-TTY human output never prompt or open a browser; they print a state-free local launcher URL while the loopback callback continues waiting. The local route redirects to the provider without exposing OAuth state in terminal output.
* `--json` never opens a browser or prints an OAuth URL or state. If fresh consent is required, it exits `1` with `oauth_interaction_required` and an interactive retry command in `error.details.nextSteps`.
* `connect --no-oauth` prevents automatic OAuth when the server returns `401`.
* `--protocol auto` prefers the modern wire and falls back to legacy. `legacy`
  selects only the legacy wire. `modern` selects the stateless, sessionless
  modern wire with no fallback.
* Repeated `-H, --header <"Key: Value">` options store static headers as credentials.
* Tool and prompt arguments accept `key=value`, `key:=<json>`, or a single JSON object argument.
* `--json` may appear anywhere after `client`. Success emits exactly one JSON value to stdout. Errors emit exactly one JSON error envelope to stderr and no stdout value.
* Calls, resource reads, and prompt gets emit raw MCP result envelopes. Lists emit arrays, and `tools describe` emits one tool object.
* Tool `isError` results exit `1` and retain the original protocol result in `error.details` under `--json`; they and auth-like error text are not interpreted as OAuth challenges.

<Card title="CLI Client guide" icon="terminal" href="/v2/typescript/tooling/client-cli">
  Use the guide for connection workflows, OAuth behavior, argument parsing
  examples, and scripting patterns.
</Card>

## `screenshot`

**Purpose:** Call a view-backed MCP tool and capture its rendered MCP App as a PNG.

**Syntax:**

```bash theme={null}
mcp-use screenshot (--server <name> | --mcp <url>) --tool <name> [args...] [options]
```

Pass tool arguments after the options, either as one JSON object or as
`key=value` / `key:=<json>` pairs.

**Source options:**

| Option | Description |
| - | - |
| `--server <name>` | Use a server saved by `mcp-use client`. |
| `--mcp <url>` | Connect directly to an HTTP(S) MCP endpoint. |
| `-H, --header <"Key: Value">` | Header for `--mcp`. Repeatable, and incompatible with `--server`. |

**Capture options:**

| Option | Description | Default |
| - | - | - |
| `--tool <name>` | View-backed tool to call. Required. | None |
| `--output <path>` | Output PNG path. | Timestamped view name |
| `--width <px>` | Host and widget width, an integer from `1` to `10000000`. | `768` |
| `--height <px>` | Host viewport height, an integer from `1` to `10000000`. The PNG is cropped to the widget bounds. | `720` |
| `--device-scale-factor <n>` | Pixel density, greater than 0 and at most 4. | `1` |
| `--theme <light\|dark>` | Host theme. | `light` |
| `--wait-for <selector>` | Wait for a selector before capture. | None |
| `--delay <ms>` | Additional delay after readiness. | `0` |
| `--timeout <ms>` | Tool, browser, and readiness timeout. | `30000` |
| `--inspector <url>` | Use an existing Inspector origin. | Starts one |
| `--cdp-url <url>` | Use an existing Chrome DevTools endpoint. | Launches Chrome |
| `--json` | Emit one result or error and never prompt. | Off |

**Examples:**

```bash theme={null}
mcp-use screenshot --server demo --tool show-app appName=Demo
mcp-use screenshot --mcp https://example.com/mcp --tool show-app \
  '{"appName":"CI"}' --theme dark --output app.png --json
```

**Exit codes:**

| Code | Meaning |
| - | - |
| `0` | Capture succeeded, or help was requested. |
| `2` | Invalid arguments. |
| `1` | MCP, tool, Inspector, browser, readiness, or write failure. |

## Environment variables

| Variable | Used by | Description | Default |
| - | - | - | - |
| `PORT` | `dev`, `start`, server runtime | Server port when `--port` is not provided. `dev` sets it to the resolved listener port before importing the entry; `start` reads it before importing the built entry. | `3000` |
| `HOST` | `dev`, `start`, server runtime | Bind host when `--host` is not provided. `start` and direct `listen()` fall back to `config.host` before `127.0.0.1`. | `127.0.0.1` |
| `NODE_ENV` | `dev`, `build`, `start` | Runtime environment. When it is not already set, `dev` uses `development`, and `build` and `start` set `production` before loading the project `.env`. | Command-specific |
| `MCP_URL` | server runtime, `dev`, `build` | **Server public origin**, such as `https://mcp.example.com`. OAuth resource URL, CSP `connectDomains`, dev HMR websocket. When OAuth derives its resource from `MCP_URL` (the provider sets no `resource`), a value with a path, query, or credentials makes the server constructor throw; views and CSP use only its origin. Lower priority than `CSP_URLS`. `dev` sets it only while importing the entry on loopback binds, `build` sets `http://localhost:3000` only while inspecting the entry, and `start` never sets it. | None (request origin) |
| `MCP_ASSETS_URL` | `build`, server runtime | **Assets URL prefix** (origin + optional path) for view JS/CSS and `public/`. Falls back to `MCP_URL` origin. When set at build, manifest paths become full CDN URLs (path segment from server `basePath`). | None (falls back to server origin) |
| `CSP_URLS` | server runtime | Comma-separated CSP domain shortcut — applied to all four MCP Apps categories when per-category vars are unset. Higher priority than `MCP_URL` auto-append. | None |
| `CSP_CONNECT_DOMAINS` | server runtime | Overrides `CSP_URLS` for `connectDomains` | None |
| `CSP_RESOURCE_DOMAINS` | server runtime | Overrides `CSP_URLS` for `resourceDomains` | None |
| `CSP_FRAME_DOMAINS` | server runtime | Overrides `CSP_URLS` for `frameDomains` | None |
| `CSP_BASE_URI_DOMAINS` | server runtime | Overrides `CSP_URLS` for `baseUriDomains` | None |
| `MCP_USE_CLOUD_WEB_URL` | `deploy` | Manufact web URL for dashboard and GitHub settings links. | `https://manufact.com` |
| `MCP_USE_CLOUD_API_URL` | `login` and all cloud commands | Manufact API URL. Takes precedence over `MCP_API_URL`. The CLI normalizes it to include `/api/v1`. | `https://cloud.manufact.com/api/v1` |
| `MCP_API_URL` | `login` and all cloud commands | Fallback Manufact API URL when `MCP_USE_CLOUD_API_URL` is unset. | `https://cloud.manufact.com/api/v1` |
| `MCP_USE_API_KEY` | `login` and all cloud commands | API key for non-interactive login. Cloud commands (`deploy`, `servers`, `deployments`, `org`, `whoami`) use it directly and prefer it over the saved credential. | None |
| `MCP_USE_WS_RELAY` | `dev --tunnel`, `start --tunnel` | WebSocket relay API origin used when creating authenticated local tunnels. | `https://api.tunnel.mcp-use.run` |
| `MCP_USE_CHROME_PATH` | `screenshot` | Chrome executable path for screenshots. | Auto-detected |
| `PUPPETEER_EXECUTABLE_PATH` | `screenshot` | Fallback Chrome executable path. | Auto-detected |
| `CHROME_PATH` | `screenshot` | Fallback Chrome executable path. | Auto-detected |

**Examples:**

```bash theme={null}
PORT=8080 mcp-use start
MCP_URL=https://my-server.example.com MCP_ASSETS_URL=https://cdn.example.com/bucket mcp-use build
MCP_USE_API_KEY=mcp_... mcp-use login --org my-org
MCP_USE_CHROME_PATH=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  mcp-use screenshot --server local --tool show-board
```

## Related references

* [CLI Client guide](/v2/typescript/tooling/client-cli)
* [Tunneling guide](/tunneling/index)
* [Manufact Cloud deployment guide](/v2/typescript/server/deployment/mcp-use)
* [ServerConfig API reference](https://mcp-use-typescript-api-reference.vercel.app/modules/mcp-use.index.html#serverconfig)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.