CLI Reference
Complete command reference for the MCP Client CLI, including all commands, flags, and usage examples.
7 min read
The MCP Client CLI binary is named mcp. All commands follow the pattern:
mcp <command> [subcommand] [flags] [arguments]
Global Flags
These flags are available on every command:
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--registry | string | https://registry.mcp-hub.io | Registry endpoint URL | |
--cache-dir | string | ~/.mcp/cache | Local cache directory | |
--verbose | -v | bool | false | Enable verbose (debug) output |
--json | bool | false | Output in JSON format | |
--config | -c | string | ~/.mcp/config.yaml | Path to configuration file |
--timeout | duration | 5m | Default timeout for operations | |
--help | -h | bool | Show help for any command |
Precedence order: CLI flags override environment variables, which override the configuration file.
mcp run
Execute an MCP server from a package reference.
Synopsis
mcp run <reference> [flags]
The run command resolves a package from the registry, downloads and validates it if not cached, enforces security policies, and launches the MCP server in a sandboxed process with resource limits.
Package Reference Formats
| Format | Example | Description |
|---|---|---|
org/name@version | acme/[email protected] | Resolve by semantic version |
org/name@sha256:... | acme/my-tool@sha256:a1b2c3... | Pin to exact content digest |
org/name@latest | acme/my-tool@latest | Resolve latest version (not recommended for production) |
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--min-cert-level | int | 0 | Minimum required certification level (0-3) |
--allowed-origins | strings | Official,Verified,Community | Comma-separated list of allowed origin types |
--max-memory | string | 256m | Maximum memory limit (e.g., 512m, 1g) |
--max-cpu | float | 1.0 | Maximum CPU cores |
--max-pids | int | 64 | Maximum number of child processes |
--max-fds | int | 256 | Maximum open file descriptors |
--network | string | deny | Network policy: deny or allow (Linux only) |
--timeout | duration | 5m | Execution timeout |
--env | strings | Environment variables to pass (e.g., --env KEY=VALUE) | |
--env-file | string | Path to an environment file | |
--workdir | string | auto | Working directory for the server process |
--dry-run | bool | false | Validate policies without executing |
Examples
# Run with default settings
mcp run acme/[email protected]
# Require Security Certified level
mcp run acme/[email protected] --min-cert-level 2
# Only allow Official and Verified packages
mcp run acme/[email protected] --allowed-origins Official,Verified
# Set resource limits
mcp run acme/[email protected] --max-memory 1g --max-cpu 2.0 --max-pids 128
# Pass environment variables
mcp run acme/[email protected] --env DATABASE_URL=postgres://... --env API_KEY=secret
# Dry run (validate policies only, do not execute)
mcp run acme/[email protected] --dry-run
# Pin to exact digest for reproducibility
mcp run acme/hello-world@sha256:a1b2c3d4e5f67890...
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Server exited cleanly |
| 1 | General error |
| 2 | Policy violation (cert level, origin, etc.) |
| 3 | Sandbox setup failure |
| 4 | Download or validation failure |
| 124 | Timeout exceeded |
| 137 | Killed by resource limit (OOM) |
mcp pull
Download a package to the local cache without executing it.
Synopsis
mcp pull <reference> [flags]
The pull command is useful for pre-populating caches in CI/CD environments or for offline use. It downloads the manifest and bundle, validates SHA-256 digests, and stores them in the content-addressed cache.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--force | bool | false | Re-download even if already cached |
--verify-only | bool | false | Verify cached artifact integrity without downloading |
Examples
# Pull a specific version
mcp pull acme/[email protected]
# Force re-download
mcp pull acme/[email protected] --force
# Verify an already-cached artifact
mcp pull acme/[email protected] --verify-only
# Pull with JSON output (useful for scripting)
mcp pull acme/[email protected] --json
Output
Resolving acme/[email protected]...
Manifest: sha256:a1b2c3d4e5f6...
Bundle: sha256:f6e5d4c3b2a1...
Cert Level: 2 (Security Certified)
Downloading bundle... 2.3 MB
Validating SHA-256 digest... OK
Cached: ~/.mcp/cache/sha256/a1b2c3d4e5f6...
mcp push
Publish an MCP package to MCP Hub for certification.
Synopsis
mcp push <org/name@version> [flags]
The push command packages your MCP server source code, uploads it to MCP Hub, and initiates the certification pipeline. You must be authenticated (mcp login) before pushing.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--source | string | . (current directory) | Path to the MCP server source code |
--hub | string | https://mcp-hub.io | MCP Hub URL (not the registry) |
--language | string | auto-detect | Primary language (python, typescript, javascript, go) |
--description | string | Short description of the MCP server | |
--exclude | strings | Glob patterns to exclude from upload |
Examples
# Push from current directory
mcp push acme/[email protected]
# Push from a specific directory
mcp push acme/[email protected] --source ./dist
# Push with explicit language
mcp push acme/[email protected] --source ./src --language python
# Push to a local hub instance
mcp push acme/[email protected] --hub http://localhost:8080
# Exclude test files
mcp push acme/[email protected] --exclude "**/*_test.go" --exclude "**/testdata/**"
Output
Packaging acme/[email protected]...
Source: ./dist (14 files, 45 KB)
Language: python (auto-detected)
Uploading to https://mcp-hub.io...
Upload: 45 KB / 45 KB [====================] 100%
Certification initiated.
Job ID: job-abc123
Track at: https://mcp-hub.io/mcps/acme/my-tool/versions/1.0.0
Use 'mcp info acme/[email protected]' to check certification status.
Authentication Required
You must run mcp login before using mcp push. The push command uses your authenticated session to upload to MCP Hub.
mcp info
Display detailed information about a package.
Synopsis
mcp info <reference> [flags]
The info command queries the registry for package metadata including the manifest, certification level, score, origin, tools, resources, and findings summary.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--auth-status | bool | false | Show authentication status instead of package info |
--show-findings | bool | false | Include detailed findings in output |
Examples
# Show package information
mcp info acme/[email protected]
# Show detailed findings
mcp info acme/[email protected] --show-findings
# Check auth status
mcp info --auth-status
# JSON output for scripting
mcp info acme/[email protected] --json
Output
Package: acme/[email protected]
Manifest: sha256:a1b2c3d4e5f6...
Bundle: sha256:f6e5d4c3b2a1...
Cert Level: 2 (Security Certified)
Score: 85/100
Origin: Verified
Language: Python 3.11
Transport: STDIO
Published: 2025-01-10T14:30:00Z
Tools:
- greet Greet a user by name
- farewell Say goodbye to a user
Resources:
- templates/ Greeting templates directory
Findings Summary:
Critical: 0 High: 0 Medium: 2 Low: 5
mcp login
Authenticate with the registry.
Synopsis
mcp login [flags]
The login command stores authentication credentials in ~/.mcp/auth.json with 0600 permissions. It supports interactive login (prompts for credentials) and token-based login for CI/CD.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--registry | string | from config | Registry URL to authenticate with |
--token | string | Provide token directly (non-interactive) | |
--username | string | Username for interactive login |
Examples
# Interactive login (prompts for credentials)
mcp login
# Login with a specific registry
mcp login --registry https://registry.mcp-hub.io
# Non-interactive login with token (for CI/CD)
mcp login --token $MCP_REGISTRY_TOKEN
# Login to a local registry
mcp login --registry http://localhost:8081
Token Storage
Auth tokens are stored in ~/.mcp/auth.json:
{
"registries": {
"https://registry.mcp-hub.io": {
"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"created_at": "2025-01-15T10:00:00Z"
}
}
}
The file is created with 0600 permissions (owner read/write only). Tokens are not auto-refreshed; run mcp login again when a token expires.
mcp logout
Remove stored authentication credentials.
Synopsis
mcp logout [flags]
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--registry | string | all | Remove credentials for a specific registry only |
--all | bool | false | Remove all stored credentials |
Examples
# Remove credentials for the default registry
mcp logout
# Remove credentials for a specific registry
mcp logout --registry https://registry.mcp-hub.io
# Remove all stored credentials
mcp logout --all
mcp cache ls
List cached artifacts.
Synopsis
mcp cache ls [flags]
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--sort | string | time | Sort order: time, size, name |
--long | bool | false | Show detailed information including digests |
Examples
# List cached packages
mcp cache ls
# Detailed listing with digests
mcp cache ls --long
# JSON output
mcp cache ls --json
Output
PACKAGE VERSION SIZE CACHED
acme/hello-world 1.0.0 2.3 MB 2025-01-15 10:30
acme/data-processor 2.1.0 8.7 MB 2025-01-14 15:45
corp/internal-tool 0.5.2 1.1 MB 2025-01-13 09:20
Total: 3 packages, 12.1 MB
mcp cache rm
Remove cached artifacts.
Synopsis
mcp cache rm [reference|--all] [flags]
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--all | bool | false | Remove all cached artifacts |
--digest | string | Remove a specific digest | |
--older-than | duration | Remove artifacts older than the specified duration | |
--force | bool | false | Skip confirmation prompt |
Examples
# Remove a specific package from cache
mcp cache rm acme/[email protected]
# Remove a specific digest
mcp cache rm --digest sha256:a1b2c3d4e5f6...
# Remove all cached artifacts
mcp cache rm --all
# Remove artifacts older than 30 days
mcp cache rm --older-than 720h
# Skip confirmation
mcp cache rm --all --force
mcp doctor
Diagnose system sandbox capabilities and connectivity.
Synopsis
mcp doctor [flags]
The doctor command checks your system for sandbox capabilities, registry connectivity, cache health, and configuration validity. Use it to diagnose issues before running MCP servers.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--registry | string | from config | Override registry URL to test |
--fix | bool | false | Attempt to fix detected issues (e.g., create missing directories) |
Examples
# Full system diagnostic
mcp doctor
# Test a specific registry
mcp doctor --registry http://localhost:8081
# Attempt to fix detected issues
mcp doctor --fix
# JSON output for automation
mcp doctor --json
Diagnostic Checks
The doctor command evaluates the following:
| Check | Description |
|---|---|
| Platform | OS, architecture, and Go version |
| Resource Limits | cgroups v2 (Linux), rlimits, Job Objects (Windows) |
| Network Isolation | Network namespaces (Linux only) |
| Filesystem Isolation | Bind mounts, Landlock (Linux), UNIX perms (macOS) |
| Subprocess Control | seccomp (Linux) |
| Registry Connectivity | HTTP(S) connection and latency to registry |
| Cache Directory | Existence, permissions, disk space |
| Configuration | Config file syntax and validity |
| Auth Tokens | Token presence and file permissions |
Exit Codes
| Code | Meaning |
|---|---|
| 0 | All checks passed |
| 1 | One or more warnings (non-fatal) |
| 2 | One or more errors (action required) |