Skip to main content
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:
The CLI package can also be installed directly:
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:
Options: Examples:
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, sets PORT, and sets MCP_URL to the tunnel URL or local server URL when MCP_URL is not already set.
  • 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 writes development session metadata to .mcp-use/sessions.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:
The command accepts --path, --entry, and --mcp-dir with the same meanings as dev and build. Arguments after -- are forwarded to TypeScript:
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:
Options: Examples:
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:
Options: Examples:
Notes and behavior:
  • Address precedence is CLI flag, environment variable, server configuration, then default: --portPORTconfig.port3000, and --hostHOSTconfig.host127.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.
Tunnel limits and lifecycle: The standalone package is also available:
See the Tunneling guide for client setup and testing workflows.

deploy

Purpose: Create or update a Manufact Cloud deployment for an MCP server. Syntax:
Options: Examples:
Notes and behavior:
  • The default path deploys from GitHub and prompts to install or connect the GitHub App when needed.
  • --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/project.json to link the local project to the cloud server.
  • The CLI adds .mcp-use/ to .gitignore when it writes a project link.
  • 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:
Options: Examples:
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:
Options: None. Examples:
Notes and behavior: The command reads ~/.mcp-use/config.json.

logout

Purpose: Remove saved Manufact Cloud credentials. Syntax:
Options: None. Examples:
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. 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:
Subcommands: Examples:
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.
  • delete prompts for confirmation unless --yes is set.

Server management commands

Purpose: Manage cloud servers, which are long-lived Git-backed deploy targets that own deployments. Syntax:
Subcommands: Examples:
Notes and behavior:
  • servers update --branch changes the production branch for future production deploys.
  • 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, add, update, and remove environment variables on a cloud server. Syntax:
Subcommands: Examples:
Notes and behavior:
  • Values are masked by default. --show-values reveals non-sensitive values.
  • --env <environments> accepts comma-separated production, preview, and development.
  • env add --env defaults to all three environments when omitted.
  • --branch <name> scopes preview environment variables to a branch. Omit --branch for production resolution.
  • env update and env remove accept either a variable key or UUID.

client

Purpose: Save HTTP MCP server connections, call tools, read resources, get prompts, and manage OAuth credentials from the terminal. Syntax:
Top-level subcommands: Per-server scopes: Every action in this table accepts --json except where the top-level table does not advertise it. Examples:
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.
  • --no-open, --json, and non-TTY operation never prompt or open a browser. They print the authorization URL to stderr while the loopback callback continues waiting.
  • 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.

CLI Client guide

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

generate-types

Purpose: Generate TypeScript module augmentation for MCP tool schemas. Syntax:
Options: Examples:
Notes and behavior:
  • The command writes .mcp-use/tool-registry.d.ts.
  • mcp-use dev runs type generation automatically.
  • mcp-use build also attempts type generation when it can find a server entry, but build-time generation failures are non-blocking.
  • Include .mcp-use/**/* in tsconfig.json so widget code can see generated types.

Environment variables

Examples: