CLI Reference

Complete reference for the mcpg command-line interface.

Installation

# Install globally (recommended)
npm install -g @hotnsoursoup/mcp-gateway

# Or run directly with npx
npx @hotnsoursoup/mcp-gateway <command>

Core Commands

mcpg init

Initialize the gateway with sensible defaults. Creates configuration, starts the daemon, and enables auto-start on login.

mcpg init [options]

Options:
  --port \<PORT\>     Set gateway port (default: 8989)
  --config \<PATH\>   Custom config file path
  --force           Overwrite existing configuration

This single command:

• Creates ~/.mcp-gateway/config.yaml
• Starts the daemon in the background
• Enables auto-start on boot

mcpg start

Start the gateway daemon in the background.

mcpg start [options]

Options:
  --port \<PORT\>     Override gateway port
  --config \<PATH\>   Custom config file path
  --keep-alive      Disable idle timeout (run indefinitely)

Idle Timeout

By default, the daemon shuts down after 10 minutes of no connections. Use --keep-alive to disable this.

mcpg stop

Stop the running gateway daemon.

mcpg stop

mcpg restart

Restart the gateway daemon (stop + start).

mcpg restart

mcpg status

Check if the gateway daemon is running and show basic stats.

mcpg status

Output:
  Gateway:    running (PID 12345)
  Port:       8989
  Uptime:     2h 34m
  Servers:    4 active
  Connections: 2 active

mcpg run

Run the gateway in the foreground (for debugging). Logs are printed to stdout. Use Ctrl+C to stop.

mcpg run [options]

Options:
  --port \<PORT\>     Override gateway port
  --config \<PATH\>   Custom config file path
  --verbose         Enable debug logging

mcpg logs

View gateway logs.

mcpg logs [options]

Options:
  --lines \<N\>       Show last N lines (default: 50)
  --follow, -f      Follow log output (like tail -f)
  --server \<NAME\>   Filter logs for a specific server

Configuration Commands

mcpg configure <tool>

Automatically configure an AI tool to use the gateway. Modifies the tool's MCP configuration file.

mcpg configure \<tool\>

Supported tools:
  claude    Claude Code (~/.claude/settings.json)
  cursor    Cursor IDE
  codex     Codex
  gemini    Gemini

Options:
  --remove          Remove gateway from config instead of adding

mcpg print-config <tool>

Print the MCP configuration JSON for manual setup. Use this if automatic configuration doesn't work.

mcpg print-config claude

Output:
{
  "mcpServers": {
    "mcp-gateway": {
      "transport": "http",
      "url": "http://localhost:8989/mcp"
    }
  }
}

mcpg enable-autostart

Enable auto-start on login (creates system service/launch agent).

mcpg enable-autostart

mcpg disable-autostart

Disable auto-start on login.

mcpg disable-autostart

HTTP & Authentication Commands

mcpg enable-http

Enable the HTTP endpoint with token authentication. Generates a secure token for API access.

mcpg enable-http

Output:
  HTTP endpoint enabled on :8989
  Token: mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  Configure your client with:
    Authorization: Bearer mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

mcpg disable-http

Disable HTTP authentication (localhost-only access, no token required).

mcpg disable-http

mcpg show-token

Display the current HTTP authentication token.

mcpg show-token

Output:
  Current token: mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

mcpg rotate-token

Generate a new token and invalidate the old one. All clients using the old token will need to be updated.

mcpg rotate-token

Output:
  Old token invalidated
  New token: mcp_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

Server Management Commands

mcpg list-servers

List all configured servers and their status.

mcpg list-servers

Output:
  NAME              STATUS      MEMORY    SCOPE
  context7          running     48 MB     global
  supabase          running     52 MB     workspace
  github            idle        -         credential
  filesystem        running     35 MB     global

mcpg list-catalog

List available servers that can be installed from the catalog.

mcpg list-catalog

Output:
  NAME                DESCRIPTION
  context7            Library documentation lookup
  supabase            Supabase database access
  github              GitHub API integration
  playwright          Browser automation
  ...

mcpg install <server>

Install a server from the catalog.

mcpg install \<server\> [options]

Options:
  --scope \<SCOPE\>   Set server scope (global, workspace, credential)
  --env \<KEY=VAL\>   Set environment variable

Examples:
  mcpg install context7
  mcpg install github --env GITHUB_TOKEN=ghp_xxx
  mcpg install supabase --scope workspace

mcpg uninstall <server>

Remove a server from configuration.

mcpg uninstall \<server\>

Debugging Commands

mcpg validate

Validate configuration files and check for common issues.

mcpg validate

Output:
  ✓ config.yaml syntax valid
  ✓ All server commands exist
  ✗ Missing env var: GITHUB_TOKEN (required by github server)
  ✗ Port 8989 already in use

mcpg doctor

Run diagnostics and check system health.

mcpg doctor

Output:
  System:
    ✓ Node.js v20.10.0
    ✓ npm 10.2.3
    ✓ Docker available

  Gateway:
    ✓ Daemon running (PID 12345)
    ✓ Port 8989 accessible
    ✓ Config valid

  Servers:
    ✓ context7: healthy
    ✗ supabase: failed to start (missing SUPABASE_KEY)

Global Options

These options work with all commands:

Option	Description
--help, -h	Show help for command
--version, -v	Show version number
--config \<PATH\>	Use custom config file
--quiet, -q	Suppress non-error output
--json	Output in JSON format

Environment Variables

Variable	Description	Default
MCP_GATEWAY_PORT	Gateway HTTP port	8989
MCP_GATEWAY_CONFIG	Config file path	~/.mcp-gateway/config.yaml
MCP_GATEWAY_LOG_LEVEL	Log level (debug, info, warn, error)	info
MCP_GATEWAY_IDLE_TIMEOUT	Idle timeout in seconds	600 (10 min)

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Daemon not running
4	Port already in use