CLI Reference

MCPlexer provides a single binary with subcommands for running the gateway, managing configuration, and operating the daemon.

terminal

mcplexer <command> [flags]

serve

Start the MCP gateway. This is the primary command — it launches MCPlexer and begins accepting client connections.

terminal

# Default: stdio mode (for Claude Desktop, Cursor, etc.) mcplexer serve # HTTP mode with web dashboard mcplexer serve --mode=http --addr=127.0.0.1:8080 # Socket mode mcplexer serve --mode=stdio --socket=/tmp/mcplexer.sock

Name	Type	Default	Description
`--mode`	string	stdio	Transport mode: stdio, http, or socket.
`--addr`	string	127.0.0.1:8080	Listen address for HTTP mode.
`--socket`	string	—	Unix socket path for socket mode.

connect

Bridge stdin/stdout to a running MCPlexer daemon socket. This allows MCP clients that only support stdio to connect to a daemon-mode MCPlexer instance.

terminal

mcplexer connect --socket=/tmp/mcplexer.sock

Name	Type	Default	Description
`--socket`	string	—	Path to the Unix socket. Can also be set via MCPLEXER_SOCKET_PATH.

Environment variables

connect also reads MCPLEXER_CLIENT_CWD to pass the client's working directory to the daemon for workspace resolution.

init

Create the SQLite database and a default YAML configuration file. Run this once when first setting up MCPlexer.

terminal

mcplexer init # Creates: # ~/.mcplexer/mcplexer.db # ~/.mcplexer/mcplexer.yaml

setup

Run the one-step setup: starts the daemon, writes the Claude Desktop config, and opens the dashboard.

terminal

mcplexer setup

status

Print a summary of the current MCPlexer state — workspace count, server count, active processes, and sessions.

terminal

mcplexer status # MCPlexer Status (db: ~/.mcplexer/mcplexer.db) # Workspaces: 2 # Downstream servers: 3 # Auth scopes: 1 # Active sessions: 0

dry-run

Simulate route resolution for a tool call without actually executing it. Useful for verifying that your routing configuration is correct.

terminal

mcplexer dry-run <workspace-id> <tool-name> # Example: mcplexer dry-run ws-abc123 github__list_repos # Matched route: rule-def456 # Downstream: github-mcp # Auth scope: github-token # Policy: allow

secret

Manage encrypted secrets stored with age encryption. Requires the MCPLEXER_AGE_KEY environment variable pointing to your age key file.

Age key required

All secret commands require MCPLEXER_AGE_KEY to be set. Generate a key with age-keygen -o key.txt.

secret put

Store a secret value for an auth scope.

terminal

mcplexer secret put <scope-id> <key> <value> # Example: mcplexer secret put github-token GITHUB_TOKEN ghp_abc123...

secret get

Retrieve a decrypted secret value.

terminal

mcplexer secret get <scope-id> <key> # Example: mcplexer secret get github-token GITHUB_TOKEN

secret list

List all secret keys for an auth scope (values are not shown).

terminal

mcplexer secret list <scope-id> # Example: mcplexer secret list github-token # GITHUB_TOKEN # GITHUB_ORG

secret delete

Remove a secret from an auth scope.

terminal

mcplexer secret delete <scope-id> <key> # Example: mcplexer secret delete github-token GITHUB_ORG

daemon

Manage the MCPlexer background daemon. The daemon runs MCPlexer as a persistent process listening on a Unix socket.

daemon start

Start the daemon in the background.

terminal

mcplexer daemon start

daemon stop

Stop a running daemon.

terminal

mcplexer daemon stop

daemon status

Check whether the daemon is running.

terminal

mcplexer daemon status # MCPlexer daemon: running (PID 12345)

daemon logs

View daemon log output.

terminal

mcplexer daemon logs

control-server

Run a read-only MCP control server over stdio. This exposes MCPlexer's internal state (workspaces, routes, servers, audit logs) as MCP tools that an AI client can query.

terminal

mcplexer control-server

Set MCPLEXER_CONTROL_READONLY=true to enforce read-only mode.

Name	Type	Default	Description
`MCPLEXER_CONTROL_READONLY`	env var	true	When true, the control server only exposes read operations.

Config Methods File Locations