---
title: "CLI Reference"
description: "Complete reference for the @mcp-use/cli build and deployment tool"
icon: "terminal"
---

The `@mcp-use/cli` is a build and development tool for creating MCP servers with integrated UI widgets. It provides commands for development, building, deployment, and authentication.

## What's New

<CardGroup cols={2}>
  <Card title="Hot Module Reload" icon="flame" href="#hot-module-reloading-hmr">
    `mcp-use dev` hot-reloads tools, prompts, and resources without dropping connected clients.
  </Card>
  <Card title="--tunnel flag" icon="train-front-tunnel" href="/tunneling/index">
    `mcp-use start --tunnel` exposes your local server through a public URL for ChatGPT, Claude, and other remote clients.
  </Card>
  <Card title="skills add" icon="wand" href="#skills-add-install-ai-agent-skills">
    Install mcp-use agent skills into Cursor, Claude Code, and Codex presets with one command.
  </Card>
  <Card title="generate-types" icon="type" href="#generate-types-type-generation">
    Auto-derive TypeScript types from your Zod tool schemas for fully-typed widget code.
  </Card>
  <Card title="client" icon="terminal" href="/typescript/client/cli">
    `mcp-use client` drives MCP servers from the terminal with full OAuth support, plus `client screenshot` for headless widget capture in agent visual feedback loops.
  </Card>
</CardGroup>

## Installation

<Tip>
  When using `create-mcp-use-app`, the CLI is automatically installed as a
  project dependency.
</Tip>

```bash 
# Install globally
npm install -g @mcp-use/cli

# Or use with npx (no installation needed)
npx @mcp-use/cli dev

# Install as project dependency
npm install --save-dev @mcp-use/cli

````


---

## Commands

### `dev` - Development Server

Start a development server with hot reload, automatic TypeScript compilation, and auto-opening inspector.

```bash
mcp-use dev [options]
```

**What happens in dev mode:**

1. TypeScript files are compiled in watch mode
2. UI widgets are built with hot reload
3. Server runs with automatic restart on changes
4. Inspector automatically opens at `http://localhost:3000/inspector`
5. MCP endpoint is available at `http://localhost:3000/mcp`

**Options:**

| Option                    | Description                                                                  | Default           |
| ------------------------- | ---------------------------------------------------------------------------- | ----------------- |
| `-p, --path <path>`       | Project directory                                                            | Current directory |
| `--port <port>`           | Server port                                                                  | 3000              |
| `--host <host>`           | Bind address; `0.0.0.0` listens on all interfaces                            | `0.0.0.0`         |
| `--mcp-dir <dir>`         | Folder holding the MCP entry + resources (e.g. `src/mcp`)                    | -                 |
| `--entry <file>`          | Explicit server entry file                                                   | Auto-detected     |
| `--widgets-dir <dir>`     | Path to widgets directory                                                    | `resources`       |
| `--no-open`               | Don't auto-open inspector                                                    | false             |
| `--no-hmr`                | Disable Hot Module Reloading                                                 | false             |
| `--tunnel`                | Expose the dev server through a public tunnel URL                            | false             |

<Tip>
  Use `--mcp-dir` when your MCP server lives inside an existing project (e.g. a Next.js app).
  With `--mcp-dir src/mcp`, the CLI looks for `src/mcp/index.ts` as the entry and
  `src/mcp/resources/` as the widgets directory.
</Tip>

**Examples:**

```bash
# Basic development
mcp-use dev

# Custom port
mcp-use dev --port 8080

# Disable inspector auto-open
mcp-use dev --no-open

# Disable HMR (uses tsx watch instead)
mcp-use dev --no-hmr

# Custom project path
mcp-use dev -p ./my-server

# MCP server inside a Next.js app
mcp-use dev --mcp-dir src/mcp

# Share the dev server publicly (useful with ChatGPT/Claude remote MCP)
mcp-use dev --tunnel
```

#### Hot Module Reloading (HMR)

HMR is enabled by default in development mode. It allows you to modify tools, prompts, and resources without restarting the server or dropping client connections.

**What can be hot-reloaded:**

- Adding new tools, prompts, resources, or resource templates
- Updating existing registrations (descriptions, schemas, handlers)
- Removing registrations

**What requires a restart:**

- Server configuration changes (name, version, port)
- Adding new middleware
- Changes to OAuth configuration

Connected clients automatically receive `list_changed` notifications and refresh their cached lists.

---

### `build` - Production Build

Build your MCP server for production deployment.

```bash
mcp-use build [options]
```

**What happens during build:**

1. TypeScript is compiled to JavaScript
2. All `.tsx` files in `resources/` are bundled as standalone HTML pages
3. Assets are hashed for optimal caching
4. Output is optimized and minified
5. Build manifest (`dist/mcp-use.json`) is created

**Options:**

| Option                    | Description                                                                  | Default           |
| ------------------------- | ---------------------------------------------------------------------------- | ----------------- |
| `-p, --path <path>`       | Project directory                                                            | Current directory |
| `--mcp-dir <dir>`         | Folder holding the MCP entry + resources (e.g. `src/mcp`)                    | -                 |
| `--entry <file>`          | Explicit server entry file                                                   | Auto-detected     |
| `--widgets-dir <dir>`     | Path to widgets directory                                                    | `resources`       |
| `--with-inspector`        | Include inspector in build                                                   | false             |
| `--inline`                | Inline all widget JS/CSS into HTML (required for the VS Code MCP Apps host)  | false             |
| `--no-inline`             | Keep widget JS/CSS as separate files (default)                               | true              |
| `--no-typecheck`          | Skip the `tsc --noEmit` typecheck step (faster builds; transpile-only)       | false             |

**Examples:**

```bash
# Basic build
mcp-use build

# Build with inspector included
mcp-use build --with-inspector

# Build specific project
mcp-use build -p ./my-server

# Build MCP server inside a Next.js app
mcp-use build --mcp-dir src/mcp

# Inline-bundled widgets for VS Code MCP Apps (CSP-locked host)
mcp-use build --inline

# Fastest build: skip the typecheck pass
mcp-use build --no-typecheck
```

<Tip>
  Use the `MCP_SERVER_URL` environment variable during build to configure widget
  asset paths for static deployments (e.g., Supabase Storage).
</Tip>

---

### `start` - Production Server

Start the production server from built files.

```bash
mcp-use start [options]
```

**Options:**

| Option                    | Description                                                        | Default           |
| ------------------------- | ------------------------------------------------------------------ | ----------------- |
| `-p, --path <path>`       | Project directory                                                  | Current directory |
| `--port <port>`           | Server port                                                        | 3000              |
| `--entry <file>`          | Explicit server entry file (overrides the build manifest)          | Auto-detected     |
| `--mcp-dir <dir>`         | Folder holding the MCP entry + resources (e.g. `src/mcp`)          | -                 |
| `--tunnel`                | Expose via tunnel                                                  | false             |

**Examples:**

```bash
# Start production server
mcp-use start

# Custom port
mcp-use start --port 8080

# Start with tunnel (exposes server publicly)
mcp-use start --tunnel

# Start specific project
mcp-use start -p ./my-server

# Start MCP server inside a Next.js app
mcp-use start --mcp-dir src/mcp
```

<Note>
  The `start` command looks for the server entry point in the build manifest
  (`dist/mcp-use.json`). If not found, it falls back to checking
  `dist/index.js`, `dist/server.js`, etc. When `--mcp-dir` is set, the
  TypeScript source is run directly via `tsx` instead of expecting pre-built
  `.js` files.
</Note>

<Tip>
  `--tunnel` creates a public URL via Manufact Cloud  -  ideal for testing with ChatGPT, Claude, or any remote MCP client before you deploy. The subdomain persists across restarts (stored in `dist/mcp-use.json`). See the [Tunneling guide](/tunneling/index) for rate limits, expiry, and the standalone `npx @mcp-use/tunnel` command.
</Tip>

---

### `deploy` - Cloud Deployment

Deploy your MCP server to Manufact Cloud.

```bash
mcp-use deploy [options]
```

**Options:**

| Option                  | Description                                                                          | Default        |
| ----------------------- | ------------------------------------------------------------------------------------ | -------------- |
| `--name <name>`         | Custom deployment name                                                               | Auto-generated |
| `--port <port>`         | Server port                                                                          | 3000           |
| `--runtime <runtime>`   | Runtime: `node` or `python`                                                          | Auto-detected  |
| `--open`                | Open deployment in browser after a successful deploy                                 | false          |
| `--env <key=value>`     | Environment variable (repeatable)                                                    | -              |
| `--env-file <path>`     | Path to a `.env` file with environment variables                                     | -              |
| `--new`                 | Force creation of a new deployment (don't reuse the project link)                    | false          |
| `--root-dir <path>`     | Root directory inside the repo to deploy from (for monorepos)                        | Repo root      |
| `--org <slug-or-id>`    | Deploy to a specific organization (by slug or ID)                                    | Active org     |
| `-y, --yes`             | Skip confirmation prompts (for non-interactive / CI use)                             | false          |
| `--region <region>`     | Deploy region: `US`, `EU`, or `APAC`                                                 | `US`           |
| `--build-command <cmd>` | Custom build command (overrides auto-detection)                                      | Auto-detected  |
| `--start-command <cmd>` | Custom start command (overrides auto-detection)                                      | Auto-detected  |

**Examples:**

```bash
# Basic deployment
mcp-use deploy

# Deploy with custom name and open in browser
mcp-use deploy --name my-server --open

# Deploy with environment variables
mcp-use deploy --env DATABASE_URL=postgres://... --env API_KEY=secret

# Deploy with .env file
mcp-use deploy --env-file .env.production

# Python runtime
mcp-use deploy --runtime python

# Monorepo: deploy a subdirectory
mcp-use deploy --root-dir apps/mcp-server

# Force a brand-new deployment instead of reusing the linked one
mcp-use deploy --new --name my-server-v2

# Non-interactive deploy to a specific org and region
mcp-use deploy --org manufact-inc --region EU --yes
```

**Deployment Process:**

1. Checks if project is a GitHub repository
2. Prompts to install GitHub App if needed
3. Creates or links deployment project
4. Builds and deploys from GitHub
5. Returns deployment URLs (MCP endpoint and Inspector)

<Tip>
  The deploy command automatically creates a `.mcp-use/project.json` file to
  link your local project to the cloud deployment for stable URLs across
  redeployments.
</Tip>

---

### Authentication Commands

#### `login` - Authenticate with Manufact Cloud

```bash
mcp-use login
```

Starts an OAuth-style device code flow to authenticate with [Manufact Cloud](https://manufact.com). Opens a browser window to complete authentication.

**Options:**

- `--api-key <key>`  -  Skip the browser flow and save an API key directly. Intended for CI/CD.
- `--org <slug|id|name>`  -  Pick an organization up-front and skip the post-login prompt. Use this when running in agent harnesses or non-TTY environments where the interactive selection cannot be answered.

**What happens:**

1. CLI generates a device code
2. Opens browser to authentication page
3. Stores session token in `~/.mcp-use/config.json`
4. If you have more than one organization and `--org` was not supplied, CLI prompts you to pick one. Without a TTY, the command fails with a message pointing at `--org` rather than hanging.

#### `whoami` - Check Authentication Status

```bash
mcp-use whoami
```

Displays your current authentication status and user information.

#### `logout` - Sign Out

```bash
mcp-use logout
```

Removes authentication credentials from `~/.mcp-use/config.json`.

---

### Organization Commands

Manage which Manufact Cloud organization the CLI talks to. Every `deploy`, `deployments`, and `servers` call resolves against the active org unless `--org` overrides it.

```bash
mcp-use org list       # List orgs you belong to (active marked with ←)
mcp-use org current    # Show the currently active org
mcp-use org switch     # Interactive picker that updates ~/.mcp-use/config.json
```

<Tip>
  For non-interactive flows (CI, agents), pass `--org <slug|id|name>` directly to `login` / `deploy` / `servers ls` / `deployments ls` instead of switching state up-front.
</Tip>

---

### Deployment Management

The `deploy` command above creates a deployment; the `deployments` subcommand inspects and manages existing ones.

```bash
mcp-use deployments list                 # Aliased as `deployments ls`
mcp-use deployments get <deployment-id>
mcp-use deployments logs <deployment-id> [-b|--build] [-f|--follow]
mcp-use deployments restart <deployment-id> [-f|--follow]
mcp-use deployments stop <deployment-id>
mcp-use deployments start <deployment-id>
mcp-use deployments delete <deployment-id> [-y|--yes]   # alias: `rm`
```

| Subcommand | Description |
| ---------- | ----------- |
| `list` / `ls` | List deployments visible to the active org |
| `get` | Show core details for one deployment |
| `logs` | Tail runtime logs by default; pass `-b/--build` for build logs and `-f/--follow` to stream |
| `restart` | Trigger a new deployment on the same server (with optional build-log follow) |
| `stop` | Take a running deployment offline |
| `start` | Bring a stopped deployment back online |
| `delete` / `rm` | Delete a deployment (irreversible — prompts unless `-y` is passed) |

---

### Server Management

`mcp-use servers` manages the Git-backed deploy targets that own one or more deployments.

```bash
mcp-use servers list [--org <slug-or-id>] [--limit <n>] [--skip <n>] [--sort <field:asc|desc>]
mcp-use servers get <id-or-slug>
mcp-use servers delete <server-id> [-y] [--org <slug-or-id>]   # alias: `rm`
```

Environment variables on a server are managed under `servers env`:

```bash
mcp-use servers env list --server <id> [--show-values]
mcp-use servers env add --server <id> KEY=VALUE \
  [--env production,preview,development] [--sensitive]
mcp-use servers env update <var-id> --server <id> \
  [--value <value>] [--env <envs>] [--sensitive|--no-sensitive]
mcp-use servers env remove <var-id> --server <id>   # alias: `rm`
```

| Subcommand | Notes |
| ---------- | ----- |
| `env list` | Values are masked by default — pass `--show-values` to reveal non-sensitive ones |
| `env add` | `--env` defaults to all three environments when omitted |
| `env update` | Use `--no-sensitive` to unmark a previously-sensitive var |
| `env remove` | Address the var by its UUID (find it via `env list`) |

<Tip>
  Use `mcp-use servers ls` to discover server IDs, then `mcp-use deployments ls` (or `get <id>`) to drill into individual deploys. The two commands are intentionally split: a server is a long-lived target; deployments are immutable builds against it.
</Tip>

---

### Client Commands

`mcp-use client` is the interactive MCP **client** that lives inside the same binary as the build/deploy commands above. Use it to drive a running MCP server from the terminal — call tools, read resources, get prompts, run OAuth flows, or capture a PNG of a widget for an agent's visual feedback loop.

```bash
# Save an MCP server under a short name
mcp-use client connect <name> <url>           # OAuth or --auth <token> for bearer
mcp-use client connect <name> "<cmd args>" --stdio

# Per-server commands (every subcommand takes the name positional)
mcp-use client <name> tools list
mcp-use client <name> tools call <tool> [args...] [--screenshot]
mcp-use client <name> resources list
mcp-use client <name> prompts list
mcp-use client <name> auth status
mcp-use client <name> screenshot --tool <name> [args...]
mcp-use client <name> interactive
mcp-use client <name> disconnect

# Ad-hoc widget screenshot, no saved server needed
mcp-use client screenshot --mcp <url> --tool <name> [args...]

# Manage saved servers
mcp-use client list
mcp-use client remove <name>
```

| Scope | Actions |
| ----- | ------- |
| `tools` | `list`, `call <tool> [args...]`, `describe <tool>` |
| `resources` | `list`, `read <uri>`, `subscribe <uri>`, `unsubscribe <uri>` |
| `prompts` | `list`, `get <prompt> [args...]` |
| `auth` | `status`, `refresh`, `logout` (OAuth servers only) |
| `screenshot` | Render the tool's UI resource headlessly and write a PNG |

<Card title="Full Client CLI reference" icon="terminal" href="/typescript/client/cli">
  Connect/list/remove, every scope, the arg-parsing rules, OAuth flows, ad-hoc vs. saved-server screenshot forms, `--cdp-url` for remote browsers, and storage layout. Read this if you're using `mcp-use client` from your terminal or from an agent harness.
</Card>

---

### Skills Commands

#### `skills add` - Install AI Agent Skills

```bash
mcp-use skills add [options]
```

Downloads the latest mcp-use skills from [github.com/mcp-use/mcp-use](https://github.com/mcp-use/mcp-use) and installs them into all agent preset directories.

**What happens:**

1. Downloads the latest skills from GitHub
2. Installs them into all agent preset directories:
   - `.cursor/skills/` (Cursor)
   - `.claude/skills/` (Claude Code)
   - `.agent/skills/` (Codex)

**Options:**

| Option              | Description       | Default           |
| ------------------- | ----------------- | ----------------- |
| `-p, --path <path>` | Project directory | Current directory |

**Examples:**

```bash
# Install skills in current project
mcp-use skills add

# Install skills in a specific project
mcp-use skills add -p ./my-server
```

#### `skills install` - Alias for `skills add`

```bash
mcp-use skills install [options]
```

Identical to `skills add`. Use whichever you prefer.

<Tip>
  Skills are also installed automatically when creating a new project with
  `create-mcp-use-app` (unless `--no-skills` is passed).
</Tip>

---

## Build Artifacts & Generated Files

The CLI generates several files during build, deployment, and development. Understanding these files helps with debugging and advanced configuration.

### `dist/mcp-use.json` - Build Manifest

**Location:** `<project>/dist/mcp-use.json`

**Created by:** `mcp-use build`

**Purpose:** Stores metadata about the built server, including widget information, build details, and runtime configuration.

**Structure:**

```json
{
  "includeInspector": true,
  "buildTime": "2025-02-04T10:30:00.000Z",
  "buildId": "a1b2c3d4e5f6g7h8",
  "entryPoint": "dist/index.js",
  "widgets": {
    "weather-display": {
      "title": "Weather Display",
      "description": "Shows weather information",
      "props": {
        "type": "object",
        "properties": {
          "city": { "type": "string" }
        }
      }
    }
  },
  "tunnel": {
    "subdomain": "my-server-abc123"
  }
}
```

**Contents:**

- `includeInspector` - Whether inspector was included in build
- `buildTime` - ISO timestamp of build
- `buildId` - Unique build identifier (hash)
- `entryPoint` - Path to server entry point for `mcp-use start`
- `widgets` - Map of widget names to their metadata (title, description, props schema)
- `tunnel` - Tunnel configuration (subdomain persists across restarts)

**Usage:**

- Read by `mcp-use start` to locate the server entry point
- Stores tunnel subdomain for consistent URLs
- Contains widget schemas for runtime widget rendering

---

### `.mcp-use/project.json` - Deployment Link

**Location:** `<project>/.mcp-use/project.json`

**Created by:** `mcp-use deploy`

**Purpose:** Links your local project to a cloud deployment, ensuring stable URLs across redeployments.

**Structure:**

```json
{
  "deploymentId": "dep_abc123xyz",
  "deploymentName": "my-mcp-server",
  "deploymentUrl": "https://my-server.deploy.mcp-use.com",
  "linkedAt": "2025-02-04T10:00:00.000Z",
  "serverId": "srv_def456uvw"
}
```

**Contents:**

- `deploymentId` - Unique deployment identifier
- `deploymentName` - Human-readable deployment name
- `deploymentUrl` - Full URL to deployed server
- `linkedAt` - ISO timestamp when link was created
- `serverId` - Server identifier in cloud platform

**Gitignore:**

The CLI automatically adds `.mcp-use/` to your `.gitignore` as this file contains deployment-specific information that shouldn't be committed.

---

### `.mcp-use/sessions.json` - Development Sessions

**Location:** `<project>/.mcp-use/sessions.json`

**Created by:** `mcp-use dev` (automatically)

**Purpose:** Persists session metadata during development to survive hot reloads and server restarts.

**Structure:**

```json
{
  "session-id-1": {
    "clientCapabilities": { ... },
    "clientInfo": { "name": "claude-desktop", "version": "1.0.0" },
    "protocolVersion": "2024-11-05",
    "logLevel": "info",
    "lastAccessedAt": 1707048000000
  },
  "session-id-2": { ... }
}
```

**Contents:**

- Session ID mapped to session metadata
- Client capabilities and info
- Protocol version
- Log level
- Last access timestamp

**Behavior:**

- Only used in development mode (NODE_ENV !== 'production')
- Enables seamless hot reload without losing client connections
- Automatically cleaned up (expired sessions removed on load)

<Note>
  In production, sessions are stored in memory by default. Use [Redis
  Storage](/typescript/server/session-management/redis-storage) for production
  deployments with multiple server instances.
</Note>

---

### `~/.mcp-use/config.json` - User Authentication

**Location:** `~/.mcp-use/config.json` (user home directory)

**Created by:** `mcp-use login`

**Purpose:** Stores user-level CLI authentication credentials.

**Structure:**

```json
{
  "apiKey": "your-api-key-here",
  "apiUrl": "https://cloud.manufact.com/api/v1"
}
```

**Contents:**

- `apiKey` - Authentication token for Manufact Cloud
- `apiUrl` - Backend API URL (can be customized for local development)

**Usage:**

- Used by `mcp-use deploy`, `mcp-use whoami`
- Removed by `mcp-use logout`
- Can be customized with `MCP_API_URL` and `MCP_WEB_URL` environment variables

---

## Environment Variables

### Development & Build

| Variable         | Description                       | Default     |
| ---------------- | --------------------------------- | ----------- |
| `PORT`           | Server port                       | 3000        |
| `NODE_ENV`       | Environment mode                  | development |
| `MCP_SERVER_URL` | Server URL for widget asset paths | -           |

**Examples:**

```bash
# Custom port
PORT=8080 mcp-use dev

# Production build with custom MCP URL
MCP_SERVER_URL=https://myserver.com mcp-use build
```

### Deployment & Cloud

| Variable      | Description               | Default                           |
| ------------- | ------------------------- | --------------------------------- |
| `MCP_WEB_URL` | Frontend URL (auth pages) | https://manufact.com              |
| `MCP_API_URL` | Backend API URL           | https://cloud.manufact.com/api/v1 |

**Examples:**

```bash
# Local development environment
export MCP_WEB_URL=http://localhost:3000
export MCP_API_URL=http://localhost:8000
mcp-use login
mcp-use deploy
```

<Tip>
  See the [CLI README
  ENVIRONMENT.md](https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/cli/ENVIRONMENT.md)
  for detailed environment configuration examples.
</Tip>

---


### `generate-types` - Type Generation

Generate TypeScript type definitions for your MCP tools from Zod schemas.

```bash
mcp-use generate-types [options]
```

**What it does:**

1. Scans your server's tool registrations
2. Converts Zod schemas to TypeScript types
3. Generates `.mcp-use/tool-registry.d.ts` with type augmentation
4. Enables full TypeScript IntelliSense in widget code

**Options:**

| Option              | Description                | Default           |
| ------------------- | -------------------------- | ----------------- |
| `-p, --path <path>` | Project directory          | Current directory |
| `--server <file>`   | Server entry file          | `index.ts`        |

**Examples:**

```bash
# Generate types for current project
mcp-use generate-types

# Custom project path
mcp-use generate-types -p ./my-server

# Custom server entry file
mcp-use generate-types --server src/server.ts
```


**When to use:**

<Tip>
Type generation is **automatic** during `mcp-use dev`. You typically don't need to run this command manually.
</Tip>

Run manually when:
- Setting up CI/CD pipelines
- After pulling changes that modify tool schemas
- Troubleshooting type inference issues
- Building without running dev server

**TypeScript configuration:**

Ensure your `tsconfig.json` includes the generated types:

```json
{
  "include": ["index.ts", "src/**/*", "resources/**/*", ".mcp-use/**/*"]
}
```

**How it works:**

The CLI introspects your server's tool registrations and converts Zod schemas to TypeScript type strings. The generated file uses TypeScript's module augmentation to add types to the `ToolRegistry` interface, which `useCallTool` uses for automatic type inference.

---

## Next Steps

- [Server Configuration](/typescript/server/configuration) - Advanced server configuration
- [Deployment Guide](/typescript/server/deployment/mcp-use) - Deploy to Manufact Cloud
- [UI Widgets](/typescript/server/mcp-apps) - Build interactive widgets
- [Session Management](/typescript/server/session-management) - Configure session storage
