CLI Reference - mcp-use

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, Tunneling guide, and Manufact Cloud deployment guide.

Command map

Run locally

mcp-use dev starts the development server, view watcher, and Inspector.

Build and start

mcp-use build writes production artifacts. mcp-use start runs the built server.

Deploy

mcp-use deploy, mcp-use deployments, and mcp-use servers manage Manufact Cloud resources.

Client CLI

mcp-use client saves MCP servers, calls tools, reads resources, gets prompts, and handles OAuth.

Tunnels

mcp-use dev --tunnel exposes a local server through a public URL.

Typecheck

mcp-use typecheck refreshes MCP view types and runs the project’s own TypeScript compiler.

Install the CLI

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

npm install mcp-use

The CLI package can also be installed directly:

npm install -g @mcp-use/cli

npx @mcp-use/cli dev

npm install --save-dev @mcp-use/cli

create-mcp-use-app installs mcp-use, which supplies the CLI and Inspector at matching versions.

`dev`

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

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:

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 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:

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:

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:

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:

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:

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:

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.

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:

npx @mcp-use/tunnel 3000

See the Tunneling guide for client setup and testing workflows.

Cloud command conventions

Manufact Cloud commands work with any MCP framework. With --json, stdout contains one JSON result or an error envelope:

{
  "error": {
    "code": "not_authenticated",
    "message": "Sign in to Manufact Cloud.",
    "nextSteps": [{ "description": "Log in", "command": "mcp-use login" }]
  }
}

Exit codes are 0 for success, 1 for an operational failure, and 2 for invalid or missing arguments. JSON and non-interactive commands never prompt for missing input. Use each command’s --help for its complete flag list. Cloud credentials live in ~/.manufact/auth.json (mode 0600). Project links live in .manufact/project.json. Server selection is --server, MANUFACT_SERVER, then the project link. Organization selection is --org, MANUFACT_ORG, the project link, the active organization, then the account default.

Authentication commands

mcp-use login [--api-key <key> | --device-code <code>] [--org <id-or-slug>] [--no-open] [--json]

--api-key uses an existing key; --device-code completes an approved device flow. They are mutually exclusive. --no-open leaves browser navigation to you. In a terminal, login opens the verification URL and waits. Without a terminal or with --json, it prints the device code and exits. Approve it in a browser, then run the returned completion command. Device login creates a named key. Credentials are stored in ~/.manufact/auth.json with mode 0600.

`logout`

Remove the local credential and revoke the key created by device login.

mcp-use logout [options]

Pass --yes to confirm non-interactively. --json emits the result. An existing key supplied by the user is removed locally without revoking that shared key remotely.

`whoami`

Show the signed-in account, active organization, credential source, and key name.

mcp-use whoami [--json]

MANUFACT_TOKEN overrides stored credentials; MCP_USE_API_KEY is the fallback.

Projects commands

`link`

Link a project directory to a Cloud server.

mcp-use link [--server <id-or-slug>] [--org <id-or-slug>] [--path <dir>] [--json]

Writes .manufact/project.json and adds .manufact/ to the project ignore rules. This works for projects using any MCP framework. Without a terminal, supply a server or an existing link.

`unlink`

Remove the local project link.

mcp-use unlink [--path <dir>] [--json]

The Cloud server and deployments remain available.

`deploy`

Deploy from GitHub, upload local source, or register an already-hosted MCP URL.

mcp-use deploy [path] [options]

--no-github uploads local source. --external-url <url> registers a hosted endpoint. --new creates another server. Use --name, --branch, --root-dir, --build-command, --start-command, --dockerfile, and --region as needed. Repeat --env KEY=VALUE or use --env-file <path>. --no-wait returns early; --open opens the dashboard from a terminal. Deployment waits by default. A project link is stored in .manufact/project.json. Cloud deployment works with any MCP framework. Deploy-time variables use production scope on the saved production branch, otherwise a preview override for the deployed branch.

Organization commands

`org list`

List your organizations.

mcp-use org list [--json]

`org current`

Show the active organization.

mcp-use org current [--json]

`org use`

Save the active organization.

mcp-use org use <id-or-slug> [--json]

`org create`

Create an organization.

mcp-use org create <name> [--slug <slug>] [--json]

`org update`

Update the selected organization.

mcp-use org update [--name <name>] [--slug <slug>] [--logo <file>] [options]

`org members`

List organization members.

mcp-use org members [options]

`org invites list`

List organization invitations.

mcp-use org invites list [options]

`org invites send`

Invite a member to the organization.

mcp-use org invites send <email> [--role member|admin] [options]

`org invites cancel`

Cancel a pending invitation.

mcp-use org invites cancel <invite-id> [options]

Servers commands

`servers list`

List accessible Cloud servers.

mcp-use servers list [--limit <n>] [--skip <n>] [options]

`servers get`

Inspect a server.

mcp-use servers get [server] [options]

`servers update`

Change server and repository settings.

mcp-use servers update [server] [options]

--name, --description, --branch, --root-dir, --build-command, --start-command, --watch-paths, --deploy-branches, --wait-for-ci / --no-wait-for-ci, --repo <owner/name>, --disconnect-repo, and --allow-ip <cidr> configure supported settings.

`servers rm`

Remove a Cloud server.

mcp-use servers rm [server] [options]

Environment commands

`env list`

List environment keys and metadata.

mcp-use env list [options]

--environment production|preview|development selects scope; --branch selects a preview override. Set/push support --phase runtime|build|both. Use env set --help for passing a secret through stdin with --sensitive. Values are write-only. Listing returns keys and metadata. A branch-specific override can shadow the shared preview value.

`env set`

Create or update environment variables.

mcp-use env set <KEY=VALUE...> [options]

`env rm`

Remove an environment variable.

mcp-use env rm <KEY> [options]

`env push`

Apply variables from an environment file.

mcp-use env push <file> [options]

Deployments commands

`deployments list`

List deployments.

mcp-use deployments list [--limit <n>] [--skip <n>] [options]

`deployments get`

Inspect one deployment.

mcp-use deployments get <id> [options]

`deployments restart`

Start a replacement deployment.

mcp-use deployments restart <id> [--branch <branch>] [options]

`deployments promote`

Promote a deployment to production.

mcp-use deployments promote <id> [options]

`deployments stop`

Stop a deployment.

mcp-use deployments stop <id> [options]

`deployments rm`

Remove a deployment.

mcp-use deployments rm <id> [options]

`logs`

Read runtime or build logs.

mcp-use logs [deployment-id] [--build] [--since <duration>] [--limit <n>] [--follow] [options]

--build selects build output; --follow follows updates. Runtime logs support a time window and line limit. Runtime following continues until interrupted; build following ends at a terminal status. With --json, output is emitted when following ends. Use the deployment ID returned by deploy to inspect a failed build. When omitting it, select the server through its project link or --server.

Domains commands

`domains get`

Inspect server domain and DNS details.

mcp-use domains get [--domain-id <id>] [options]

`domains set-subdomain`

Choose a hosted subdomain.

mcp-use domains set-subdomain <name> [options]

`domains add`

Attach a custom domain.

mcp-use domains add <hostname> [--branch <branch>] [options]

Configure the exact CNAME target returned by domains add at your DNS provider, then verify the domain.

`domains verify`

Verify a domain DNS record.

mcp-use domains verify [--domain-id <id>] [options]

Configure the exact CNAME target returned by domains add at your DNS provider, then verify the domain.

`domains rm`

Remove a custom domain.

mcp-use domains rm [--domain-id <id>] [options]

GitHub commands

`github connect`

Get the GitHub App installation URL.

mcp-use github connect [options]

`github installations`

List available GitHub App installations.

mcp-use github installations [options]

`github repos`

List repositories accessible to the GitHub App.

mcp-use github repos [--installation <id>] [--page <n>] [--limit <n>] [options]

Checklist commands

`checklist run`

Run the publishing checklist for a server.

mcp-use checklist run [--branch <branch>] [--no-wait] [options]

Retain the run ID when using --no-wait, then inspect it with checklist get. A completed check does not publish the server.

`checklist list`

List publishing checklist runs.

mcp-use checklist list [--branch <branch>] [--limit <n>] [--skip <n>] [options]

`checklist get`

Inspect a publishing checklist run.

mcp-use checklist get <run-id> [options]

`checklist cancel`

Cancel a checklist run.

mcp-use checklist cancel <run-id> [options]

Alerts commands

`alerts list`

List server alert rules.

mcp-use alerts list [options]

`alerts get`

Inspect an alert rule.

mcp-use alerts get <id> [options]

`alerts create`

Create an alert from dashboard-format YAML.

mcp-use alerts create --file <rule.yaml> [options]

Use the dashboard YAML format. Choose a minimum traffic count alongside rate thresholds and separate trigger/recovery thresholds. alerts options lists current metrics.

`alerts update`

Update an alert from dashboard-format YAML.

mcp-use alerts update <id> --file <rule.yaml> [options]

Use the dashboard YAML format. Choose a minimum traffic count alongside rate thresholds and separate trigger/recovery thresholds. alerts options lists current metrics.

`alerts rm`

Remove an alert rule.

mcp-use alerts rm <id> [options]

`alerts options`

List available alert metrics and limits.

mcp-use alerts options [options]

Use the dashboard YAML format. Choose a minimum traffic count alongside rate thresholds and separate trigger/recovery thresholds. alerts options lists current metrics.

Analytics commands

Query a deployed MCP server’s analytics through Manufact Cloud using the existing CLI login. Both commands accept --server <id-or-slug>, --org, --path, and --json. Server selection uses --server, then MANUFACT_SERVER, then the project link. No PostHog credentials are needed.

`analytics catalog`

Read the live ClickHouse schema before constructing a query:

mcp-use analytics catalog [--server <id-or-slug>] [--branch <name>] [--json]

Returns relations and columns, metric SQL expressions and units, worked examples, branch mappings, retention, freshness, and current query limits. Human output is the complete formatted catalog; --json emits one compact JSON document.

`analytics query`

Run one read-only ClickHouse SELECT or UNION over catalog relations:

mcp-use analytics query "SELECT client_name, sum(events) AS requests FROM clients_daily WHERE bucket >= {from:DateTime64(3)} AND bucket < {to:DateTime64(3)} AND traffic_class != 'non_mcp' GROUP BY client_name ORDER BY requests DESC LIMIT 20" --time-range 7d --json

Option	Description	Default
`--time-range <preset>`	`1h`, `24h`, `7d`, `30d`, or `90d`	`7d`
`--from <timestamp>`	Inclusive ISO start with `Z` or a UTC offset; requires `--to`	—
`--to <timestamp>`	Exclusive ISO end with `Z` or a UTC offset; cannot be in the future	—
`--branch <name>`	Scope to a preview branch; omission includes all environments	All environments
`--max-rows <n>`	Maximum returned rows, 1–500	`100`
`--include-internal`	Include Manufact internal traffic	Excluded

Pass exactly one quoted SQL argument, up to 16384 UTF-8 bytes. For SQL starting with a dash, place flags before a literal delimiter:

mcp-use analytics query --server my-server --json -- '-- comment
SELECT 1'

Custom dates replace --time-range; both dates are required and the start must precede the end. They bind {from:DateTime64(3)} and {to:DateTime64(3)}. Include predicates in SQL using the catalog relation’s time column (time for raw events, bucket for rollups). For example, query one complete UTC day:

mcp-use analytics query "SELECT sum(events) AS requests FROM clients_daily WHERE bucket >= {from:DateTime64(3)} AND bucket < {to:DateTime64(3)}" --from 2026-01-01T00:00:00Z --to 2026-01-02T00:00:00Z --json

Cloud enforces server authorization, retention, and execution budgets, and rejects SETTINGS, FORMAT, INTO, table functions, and non-catalog relations. Query requests have a 30-second client timeout and no automatic retries. JSON output preserves queryId, columns, positional rows, truncated, statistics, and meta, including retention and freshness. Pair row values with columns in order and preserve 64-bit integer strings. Human output shows a table plus query metadata and a truncation notice when applicable. Empty results describe matching retained data, not all historical activity. Exit codes are 0 for success/help, 1 for operational failures, and 2 for invalid arguments. JSON errors use the standard error.code, error.message, and error.nextSteps shape. Analytics-specific API codes are retained, including ANALYTICS_SQL_REJECTED, ANALYTICS_QUERY_BUDGET, and ANALYTICS_UNAVAILABLE; authentication and network errors use the existing Cloud CLI codes. Query SQL and scope values are excluded from passive command telemetry. Install the version-matched manufact-analytics skill with mcp-use skills install for catalog discovery, SQL aggregation, and result interpretation.

Feedback commands

`feedback send`

Send feedback about the CLI to Manufact through the SDK’s PostHog project. No Cloud login or linked server is required.

mcp-use feedback send "The deployment error needs a recovery command."

Pass a single quoted message with 1–10,000 characters after trimming. The only options are --json for one JSON result and -h/--help for offline help. For dash-leading text, use mcp-use feedback send -- '--json output is missing'. Place output options before --, e.g. feedback send --json -- '--help is unclear'. Only the supplied message, report ID, random installation ID, CLI version, OS, architecture, Node version, and CI/terminal indicators are sent. Files, logs, credentials, account details, and conversations are not collected. Review the message and omit secrets or personal data. This explicit action works even with MCP_USE_ANONYMIZED_TELEMETRY=false, DO_NOT_TRACK=1, or NODE_ENV=test. It reuses the anonymous usage installation ID; if storage is unavailable, it uses a temporary random ID. Feedback events (mcp_use_cli_feedback) are separate from passive usage events (mcp_use_cli_command), which never include report text. Exit 0 and { "accepted": true, "reportId": "<uuid>" } mean the capture endpoint accepted the request. They do not confirm downstream ingestion or human review. The request times out after 10 seconds and is not automatically retried. Exit 1 returns feedback_rejected for HTTP errors, feedback_network_error for network failures, or feedback_timeout. Network failures and timeouts leave acceptance unknown; check connectivity before retrying. Invalid input exits 2 with usage_error. Without --json, success prints a receipt and failures go to stderr.

Agent skills commands

`skills install`

Install version-matched coding-agent guidance, including the Cloud CLI and manufact-analytics skills.

mcp-use skills install [--path <directory>] [--json]

Installs into .cursor/skills, .claude/skills, and .agents/skills. The skills are bundled with the CLI and work offline. skills add remains an alias. Other project skills are preserved. Destructive removals and deployment promotion/stopping require --yes without a terminal.

`client`

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

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:

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.

CLI Client guide

Use the guide for connection workflows, OAuth behavior, argument parsing examples, and scripting patterns.

`screenshot`

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

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:

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 `connectDomains` and `resourceDomains` when their 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	Sets `frameDomains` (not covered by `CSP_URLS`)	None
`CSP_BASE_URI_DOMAINS`	server runtime	Sets `baseUriDomains` (not covered by `CSP_URLS`)	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`
`MANUFACT_TOKEN`	Cloud commands	API key that overrides the stored credential.	None
`MANUFACT_SERVER`	Project-scoped Cloud commands	Server ID or slug, after `--server` and before the project link.	None
`MANUFACT_ORG`	Project-scoped Cloud commands	Organization ID or slug, after `--org` and before the project link.	None
`MCP_USE_API_KEY`	Cloud commands	Legacy credential fallback when `MANUFACT_TOKEN` is unset.	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:

PORT=8080 mcp-use start
MCP_URL=https://my-server.example.com MCP_ASSETS_URL=https://cdn.example.com/bucket mcp-use build
MANUFACT_TOKEN="$CI_MANUFACT_TOKEN" mcp-use whoami --json
MCP_USE_CHROME_PATH=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  mcp-use screenshot --server local --tool show-board

​Command map

Run locally

Build and start

Deploy

Client CLI

Tunnels

Typecheck

​Install the CLI

​dev

​typecheck

​build

​start

​Tunneling reference

​Cloud command conventions

​Authentication commands

​login

​logout

​whoami

​Projects commands

​link

​unlink

​deploy

​deploy

​Organization commands

​org list

​org current

​org use

​org create

​org update

​org members

​org invites list

​org invites send

​org invites cancel

​Servers commands

​servers list

​servers get

​servers update

​servers rm

​Environment commands

​env list

​env set

​env rm

​env push

​Deployments commands

​deployments list

​deployments get

​deployments restart

​deployments promote

​deployments stop

​deployments rm

​logs

​Domains commands

​domains get

​domains set-subdomain

​domains add

​domains verify

​domains rm

​GitHub commands

​github connect

​github installations

​github repos

​Checklist commands

​checklist run

​checklist list

​checklist get

​checklist cancel

​Alerts commands

​alerts list

​alerts get

​alerts create

​alerts update

​alerts rm

​alerts options

​Analytics commands

​analytics catalog

​analytics query

​Feedback commands

​feedback send

​Agent skills commands

​skills install

Command map

Install the CLI

`dev`

`typecheck`

`build`

`start`

Tunneling reference

Cloud command conventions

Authentication commands

`login`

`logout`

`whoami`

Projects commands

`link`

`unlink`

`deploy`

`deploy`

Organization commands

`org list`

`org current`

`org use`

`org create`

`org update`

`org members`

`org invites list`

`org invites send`

`org invites cancel`

Servers commands

`servers list`

`servers get`

`servers update`

`servers rm`

Environment commands

`env list`

`env set`

`env rm`

`env push`

Deployments commands

`deployments list`

`deployments get`

`deployments restart`

`deployments promote`

`deployments stop`

`deployments rm`

`logs`

Domains commands

`domains get`

`domains set-subdomain`

`domains add`

`domains verify`

`domains rm`

GitHub commands

`github connect`

`github installations`

`github repos`

Checklist commands

`checklist run`

`checklist list`

`checklist get`

`checklist cancel`

Alerts commands

`alerts list`

`alerts get`

`alerts create`

`alerts update`

`alerts rm`

`alerts options`

Analytics commands

`analytics catalog`

`analytics query`

Feedback commands

`feedback send`

Agent skills commands

`skills install`

`client`

`screenshot`

Environment variables

Related references