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:dev
Purpose: Start a development server with TypeScript watching, view builds, automatic reloads, and the Inspector.
Syntax:
Examples:
- The MCP endpoint is served at
/mcp. - Address precedence is
--port/--host, thenPORT/HOST, then the defaults.devdoes not import the server until after its listener is chosen, so it cannot use a server-configured address. - The Inspector supplied by
mcp-useis mounted at/mcp/inspectorand opens automatically unless--no-openis set. - Inspector UI, proxy, and OAuth routes remain local-only. A public tunnel exposes the MCP endpoint but returns
404for/mcp/inspector. - The command sets
NODE_ENV=development, setsPORT, and setsMCP_URLto the tunnel URL or local server URL whenMCP_URLis 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 devwrites 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:
--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:
Examples:
- The command bundles the default-exported server as
.mcp-use/build/index.jsand writes.mcp-use/build/manifest.json. - Each
views/<name>/view.tsxbuilds to hashed external assets under.mcp-use/build/views/<name>/by default. - Pass
--inlineto embed each view’s bundled JavaScript and CSS directly in the HTML returned byresources/read. There is no--no-inline; omit--inlineto use external assets. - The build is transpile-only. Run
mcp-use typecheckas a separate project script when type checking is required. - TypeScript path aliases come from the selected project’s
tsconfig.json. - If
MCP_ASSETS_URLis set for an external build, view paths are rewritten to that asset origin using the server’sbasePath. 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:
Examples:
- 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. --tunnelstarts 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; runmcp-use buildfirst. - It imports the manifest’s built
entryPointand requires that module to default-export anMCPServer. startdoes not rediscover source entries or views.--entry,--mcp-dir, and--views-dirbelong todevandbuild.- The command sets
NODE_ENV=productionwhen it is not already defined and loads the selected project’s production.envvalues before importing the built entry. - The build manifest never records Inspector state.
--with-inspectoris 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-inspectorbehind 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.
The standalone package is also available:
deploy
Purpose: Create or update a Manufact Cloud deployment for an MCP server.
Syntax:
Examples:
- The default path deploys from GitHub and prompts to install or connect the GitHub App when needed.
--no-githubpacks 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-githubis only required on the first deploy for that path. - The command writes
.mcp-use/project.jsonto link the local project to the cloud server. - The CLI adds
.mcp-use/to.gitignorewhen it writes a project link. - Environment variables passed through
--envand--env-fileare synced to the target branch preview environment when--branchis 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:
Examples:
- Interactive login starts a device-code flow and opens a browser.
--device-codeskips the browser and redeems the code through the same token endpoint. The CLI then creates, validates, and stores a persistent API key.--api-keyand--device-codecannot be combined. An explicit--device-codetakes precedence overMCP_USE_API_KEY.- The CLI never writes the device code, bearer token, or API key to human-readable or JSON output.
- If
--orgis omitted, the CLI stores the account-default organization when one is available. MCP_USE_API_KEYcan provide the API key for non-interactive login.
whoami
Purpose: Print the current authentication status and user information.
Syntax:
~/.mcp-use/config.json.
logout
Purpose: Remove saved Manufact Cloud credentials.
Syntax:
~/.mcp-use/config.json.
Organization commands
Organization commands control the active Manufact Cloud organization for cloud commands.
Notes and behavior:
deploy,deployments, andserversuse the active organization unless--orgoverrides it.- For CI or agent runs, pass
--org <org>tologin,deploy,servers, ordeploymentscommands 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:
Examples:
logsshows runtime logs by default. Use--buildfor build logs.restartredeploys the same server and uses the deployment branch unless--branchis set.deleteprompts for confirmation unless--yesis set.
Server management commands
Purpose: Manage cloud servers, which are long-lived Git-backed deploy targets that own deployments. Syntax:
Examples:
servers update --branchchanges the production branch for future production deploys.- Pass an empty string to
--build-command,--start-command,--root-dir,--watch-paths, or--deploy-branchesto clear that setting. --wait-for-ciand--no-wait-for-cicontrol whether auto-deploys wait for other check runs before deploying.servers deleteprompts for confirmation unless--yesis set.
Server environment commands
Purpose: List, add, update, and remove environment variables on a cloud server. Syntax:
Examples:
- Values are masked by default.
--show-valuesreveals non-sensitive values. --env <environments>accepts comma-separatedproduction,preview, anddevelopment.env add --envdefaults to all three environments when omitted.--branch <name>scopes preview environment variables to a branch. Omit--branchfor production resolution.env updateandenv removeaccept 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:
Per-server scopes:
Every action in this table accepts
--json except where the top-level table does not advertise it.
Examples:
- 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-oauthprevents automatic OAuth when the server returns401.--protocol autoprefers the modern wire and falls back to legacy.legacyselects only the legacy wire.modernselects 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. --jsonmay appear anywhere afterclient. 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 describeemits one tool object. - Tool
isErrorresults exit1and retain the original protocol result inerror.detailsunder--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:
Examples:
- The command writes
.mcp-use/tool-registry.d.ts. mcp-use devruns type generation automatically.mcp-use buildalso attempts type generation when it can find a server entry, but build-time generation failures are non-blocking.- Include
.mcp-use/**/*intsconfig.jsonso widget code can see generated types.
Environment variables
Examples: