CLI Reference

MCP Hangar provides a comprehensive command-line interface for managing MCP servers.

Installation

pip install mcp-hangar
# or
uv pip install mcp-hangar

Synopsis

mcp-hangar [OPTIONS] COMMAND [ARGS]...

Global Options

These options are available for all commands:

Commands

init

Interactive setup wizard for MCP Hangar. Guides you through MCP server selection and configuration in under 5 minutes.

Synopsis

mcp-hangar init [OPTIONS]

Options

MCP Server Bundles

Examples

# Interactive setup
mcp-hangar init

# Install starter bundle
mcp-hangar init --bundle starter

# Install specific mcp_servers
mcp-hangar init --mcp_servers filesystem,github,sqlite

# Non-interactive with developer bundle
mcp-hangar init -y --bundle developer

# Custom config location
mcp-hangar init --config-path ~/my-config.yaml

# Skip Claude Desktop integration
mcp-hangar init --skip-claude

What It Does

1. Detects Claude Desktop installation
2. Presents MCP server categories for selection
3. Collects required configuration (API keys, paths)
4. Generates config.yaml file
5. Updates Claude Desktop configuration
6. Shows next steps

status

Display health dashboard of all configured MCP servers with real-time updates.

Synopsis

mcp-hangar status [OPTIONS] [MCP_SERVER]

Arguments

Options

MCP Server States

Examples

# Show all mcp_servers
mcp-hangar status

# Watch mode with live updates
mcp-hangar status --watch

# Faster refresh rate
mcp-hangar status -w -i 0.5

# Show detailed information
mcp-hangar status --details

# Single mcp_server details
mcp-hangar status github

# JSON output for scripting
mcp-hangar --json status

Output Columns

Standard view:

• MCP Server name
• State indicator
• Tools count

Detailed view (--details):

• MCP Server name
• State indicator
• Mode (subprocess/docker/remote)
• Tools count
• Memory usage
• Uptime

add

Add a MCP server from the MCP Registry to your configuration.

Synopsis

mcp-hangar add [OPTIONS] NAME

Arguments

Options

Available MCP servers

The registry is a fixed list of these eleven. google-drive, sentry, raygun, everart and sequential-thinking were listed here and are not in it -- mcp-hangar add sentry answers Did you mean: sqlite, slack? and installs nothing. For anything outside the list, add the server to config.yaml yourself.

Examples

# Add by exact name
mcp-hangar add github

# Search for mcp_servers
mcp-hangar add --search database

# Skip confirmation
mcp-hangar add filesystem -y

# Add without hot-reload
mcp-hangar add postgres --no-reload

Configuration Prompts

When adding a MCP server that requires configuration, you'll be prompted for:

• Secrets (API keys, tokens): Hidden input, stored securely
• Paths (directories, files): Path validation
• Text (URLs, names): Standard input

Environment variables are detected automatically. If GITHUB_TOKEN is set, you'll be asked whether to use it.

remove

Remove a MCP server from your configuration.

Synopsis

mcp-hangar remove [OPTIONS] NAME

Arguments

Options

Examples

# Remove with confirmation
mcp-hangar remove github

# Remove without confirmation
mcp-hangar remove filesystem -y

# Remove from config but keep running
mcp-hangar remove postgres --keep-running

Behavior

1. Validates MCP server exists in configuration
2. Prompts for confirmation (unless -y)
3. Stops running instance (unless --keep-running)
4. Removes from config.yaml
5. Attempts hot-reload of server

serve

Start the MCP Hangar server. This is the default command when no subcommand is specified.

Synopsis

mcp-hangar serve [OPTIONS]
# or simply:
mcp-hangar [OPTIONS]

Options

Transport Modes

stdio (default)

JSON-RPC over stdin/stdout. Used by Claude Desktop and similar clients.

mcp-hangar serve
mcp-hangar --config config.yaml serve

HTTP

HTTP server with Streamable HTTP transport. Used by LM Studio and web clients.

mcp-hangar serve --http
mcp-hangar serve --http --port 9000
mcp-hangar serve --http --host 127.0.0.1 --port 8080

Binding a non-loopback host requires authentication. When --host is anything other than a loopback address (e.g. the default 0.0.0.0), Hangar refuses to start unless authentication is configured (auth) or the --unsafe-no-auth flag is passed to explicitly accept an unauthenticated listener. A loopback bind (--host 127.0.0.1) is exempt. This prevents accidentally exposing an unauthenticated gateway on a routable interface.

HTTP Endpoints

When running in HTTP mode:

Log Levels

• DEBUG - Detailed debugging information
• INFO - General operational information (default)
• WARNING - Warning messages
• ERROR - Error messages only
• CRITICAL - Critical errors only

Examples

# stdio mode (for Claude Desktop)
mcp-hangar serve

# HTTP mode on default port
mcp-hangar serve --http

# HTTP mode with custom port
mcp-hangar serve --http -p 9000

# With debug logging
mcp-hangar serve --log-level DEBUG

# With log file
mcp-hangar serve --log-file /var/log/mcp-hangar.log

# JSON logs for log aggregation
mcp-hangar serve --json-logs

# Full production setup
mcp-hangar serve --http --host 0.0.0.0 --port 8000 \
  --log-level INFO --json-logs --log-file /var/log/mcp.log

completion

Generate shell completion scripts for tab-completion support.

Synopsis

mcp-hangar completion COMMAND

Subcommands

Installation

Bash

# System-wide
mcp-hangar completion bash | sudo tee /etc/bash_completion.d/mcp-hangar

# User-only
mcp-hangar completion bash >> ~/.bashrc

Zsh

# Add to fpath
mcp-hangar completion zsh > ~/.zfunc/_mcp-hangar

# Add to .zshrc if not already present:
# fpath=(~/.zfunc $fpath)
# autoload -Uz compinit && compinit

Fish

mcp-hangar completion fish > ~/.config/fish/completions/mcp-hangar.fish

Auto-install

# Detect shell and install
mcp-hangar completion install

# Specify shell
mcp-hangar completion install zsh

auth

Authentication management. Currently exposes a one-time administrator bootstrap.

auth bootstrap-admin

Grant the one-time global admin role to an existing principal, using the server's own durable auth backend. Solves the chicken-and-egg problem where a fresh durable auth store with anonymous access disabled cannot create its first administrator through the protected API. Added in 1.5.0.

The claim also mints an API key for that principal. Whether its secret is printed is --show-key's decision, and the claim succeeds exactly once, so it is a decision to make before running the command rather than after.

Synopsis

mcp-hangar auth bootstrap-admin --config PATH --principal PRINCIPAL [OPTIONS]

Options

Behavior

• Uses the same durable backend the server uses (never an in-memory store); the claim is a single atomic operation.
• Fails closed when auth.enabled is false, allow_anonymous is true, or the storage driver is non-durable (memory / event_sourcing).
• A second run is refused without mutating storage — exactly one bootstrap succeeds.
• Grants a global admin role to the principal, and mints an API key for it as part of the same claim. The key is stored hashed; its secret is printed only with --show-key, and is not recoverable afterwards. The grant is auditable.
• Since 2.5.0: omitting --show-key is refused when no OIDC issuer is configured, before the claim is spent. API keys are then the only way in, so a run that withheld the secret would leave an admin nobody could present and a claim that cannot be made again. The refusal names the flag while re-running still works.
• Since 2.5.0: a configuration with no authenticator at all — API keys disabled and no trusted issuer — is refused on the same grounds.

Example

An OIDC deployment: the principal authenticates on its own identity, so no secret is needed.

mcp-hangar auth bootstrap-admin --config /etc/mcp-hangar/config.yaml --principal user:alice@example.com

A deployment authenticated by API keys. Capture the secret from this run — there is no second one:

mcp-hangar auth bootstrap-admin --config /etc/mcp-hangar/config.yaml \
  --principal service:my-app --show-key

config

Answer "is this configuration valid" without starting a gateway.

config check

mcp-hangar config check [PATH]

Reports every key that Hangar does not read. A key it does not read is kept and ignored, so the setting simply does not apply -- which is why a misspelling surfaces as a server that will not start, or as authentication that is quietly off, rather than as a configuration error.

PATH defaults to $MCP_CONFIG, then ./config.yaml.

$ mcp-hangar config check config.yaml
FAIL config.yaml: 2 key(s) nothing reads:

  auth has unknown key(s) ['enabledd']; allowed keys: ['allow_anonymous',
  'api_key', 'enabled', 'oidc', 'opa', 'rate_limit', 'role_assignments', 'storage']
  mcp_servers.math has unknown key(s) ['commandd']; allowed keys: [...]

The command is always strict. Loading a config only warns about an unknown key today -- see Unknown keys for what changes in 3.0.0 -- but this command exists to be asked the question directly, so it answers it. That makes it the thing to run in CI, and before a rollout.

Checked: top-level section names, the direct keys of each section, and the keys of an mcp_servers.<id> spec. Not checked: anything deeper.

Configuration File

Default Locations

The CLI searches for configuration in this order:

1. --config option
2. MCP_CONFIG environment variable
3. ~/.config/mcp-hangar/config.yaml
4. ./config.yaml (current directory)

Example Configuration

mcp_servers:
  filesystem:
    mode: subprocess
    command:
      - npx
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - "/home/user/documents"

  github:
    mode: subprocess
    command:
      - npx
      - -y
      - "@modelcontextprotocol/server-github"
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}

  my-api:
    mode: remote
    endpoint: https://api.example.com/mcp

logging:
  level: INFO
  json_format: false

event_store:
  enabled: true
  driver: sqlite
  path: data/events.db

Environment Variables

Exit Codes

See Also

• Quick Start Guide
• HTTP Transport Guide