mcp-use - The fullstack MCP framework to develop MCP Apps for ChatGPT / Claude and MCP Servers for AI Agents.

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

Hot Module Reload

mcp-use dev hot-reloads tools, prompts, and resources without dropping connected clients.

--tunnel flag

mcp-use start --tunnel exposes your local server through a public URL for ChatGPT, Claude, and other remote clients.

skills add

Install mcp-use agent skills into Cursor, Claude Code, and Codex presets with one command.

generate-types

Auto-derive TypeScript types from your Zod tool schemas for fully-typed widget code.

client

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.

Installation

When using create-mcp-use-app, the CLI is automatically installed as a project dependency.

# 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.

mcp-use dev [options]

What happens in dev mode:

TypeScript files are compiled in watch mode
UI widgets are built with hot reload
Server runs with automatic restart on changes
Inspector automatically opens at http://localhost:3000/inspector
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

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.

Examples:

# 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.

mcp-use build [options]

What happens during build:

TypeScript is compiled to JavaScript
All .tsx files in resources/ are bundled as standalone HTML pages
Assets are hashed for optimal caching
Output is optimized and minified
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:

# 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

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

`start` - Production Server

Start the production server from built files.

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:

# 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

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.

--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 for rate limits, expiry, and the standalone npx @mcp-use/tunnel command.

`deploy` - Cloud Deployment

Deploy your MCP server to Manufact Cloud.

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:

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

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

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.

Authentication Commands

mcp-use login

Starts an OAuth-style device code flow to authenticate with Manufact Cloud. 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:

CLI generates a device code
Opens browser to authentication page
Stores session token in ~/.mcp-use/config.json
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

mcp-use whoami

Displays your current authentication status and user information.

`logout` - Sign Out

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.

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

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.

Deployment Management

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

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.

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:

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`)

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.

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.

# 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

Full Client CLI reference

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.

Skills Commands

`skills add` - Install AI Agent Skills

mcp-use skills add [options]

Downloads the latest mcp-use skills from github.com/mcp-use/mcp-use and installs them into all agent preset directories. What happens:

Downloads the latest skills from GitHub
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:

# 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`

mcp-use skills install [options]

Identical to skills add. Use whichever you prefer.

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

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:

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

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

{
  "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)

In production, sessions are stored in memory by default. Use Redis Storage for production deployments with multiple server instances.

`~/.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:

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

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

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

See the CLI README ENVIRONMENT.md for detailed environment configuration examples.

`generate-types` - Type Generation

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

mcp-use generate-types [options]

What it does:

Scans your server’s tool registrations
Converts Zod schemas to TypeScript types
Generates .mcp-use/tool-registry.d.ts with type augmentation
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:

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

Type generation is automatic during mcp-use dev. You typically don’t need to run this command manually.

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:

{
  "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 - Advanced server configuration
Deployment Guide - Deploy to Manufact Cloud
UI Widgets - Build interactive widgets
Session Management - Configure session storage

Documentation Index

​What’s New

Hot Module Reload

--tunnel flag

skills add

generate-types

client

​Installation

​Commands

​dev - Development Server

​Hot Module Reloading (HMR)

​build - Production Build

​start - Production Server

​deploy - Cloud Deployment

​Authentication Commands

​login - Authenticate with Manufact Cloud

​whoami - Check Authentication Status

​logout - Sign Out

​Organization Commands

​Deployment Management

​Server Management

​Client Commands

Full Client CLI reference

​Skills Commands

​skills add - Install AI Agent Skills

​skills install - Alias for skills add

​Build Artifacts & Generated Files

​dist/mcp-use.json - Build Manifest

​.mcp-use/project.json - Deployment Link

​.mcp-use/sessions.json - Development Sessions

​~/.mcp-use/config.json - User Authentication

​Environment Variables

​Development & Build

​Deployment & Cloud

​generate-types - Type Generation

​Next Steps

What’s New

Installation

Commands

`dev` - Development Server

Hot Module Reloading (HMR)

`build` - Production Build

`start` - Production Server

`deploy` - Cloud Deployment

Authentication Commands

`login` - Authenticate with Manufact Cloud

`whoami` - Check Authentication Status

`logout` - Sign Out

Organization Commands

Deployment Management

Server Management

Client Commands

Skills Commands

`skills add` - Install AI Agent Skills

`skills install` - Alias for `skills add`

Build Artifacts & Generated Files

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

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

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

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

Environment Variables

Development & Build

Deployment & Cloud

`generate-types` - Type Generation

Next Steps