Overview
Themcphub binary doubles as a CLI for the running hub. Invoke mcphub with no arguments to start the server (the original behavior); pass a subcommand to drive a remote (or local) hub over its HTTP API.
Logging in
0600 permissions:
- macOS/Linux:
$XDG_DATA_HOME/mcphub/credentials.json(default~/.local/share/mcphub/credentials.json) - Legacy:
~/.mcphub/credentials.jsonis still honored when it already exists
staging, prod, etc. side-by-side:
Resolution order: flag → environment variable → active profile.
Global options
Commands
servers
groups
<group> accepts either the UUID or the human-readable name; the CLI resolves the name to an id by listing groups first.
keys
Manage bearer keys. Admins manage system-level and user-level keys; ordinary users manage their own
user-level keys.
create — copy it before navigating away.
tools — discover what to call
tools is the agent-friendly index for call: it answers what tools exist, what params each one takes, which server hosts it without having to hand-parse servers list JSON.
tools get text view prints a parameter table marking which keys are required, followed by the full JSON schema and a ready-to-paste mcphub call ... example with the required params filled in.
call
Call an MCP tool against the active profile’s hub. By default /mcp/$smart is used so smart routing picks the right tool. The recommended agent workflow is tools list → tools get → call.
call: --smart > --server <name> > --group <name> > default ($smart). All three resolve to the same /mcp/<slug> endpoint; --server is the natural pair for tools list/tools get output.
key=value argument coercion:
Pass
--no-coerce to treat every value as a string.
export
Download mcp_settings.json from the running hub.
discover / install (marketplace)
When the hub has systemConfig.discovery.enabled = true, the CLI can browse the public marketplace and install servers into your own hub or directly into a client-side config file.
--typepicks the installation method (npm,docker,uvx,pip,binary). If omitted, the hub picks the first available; if the requested type doesn’t exist, the CLI lists the alternatives.--env KEY=VAL(repeatable) injects environment values — both predeclared and additional keys are merged into the resultingenvblock.--to filewrites atomically (temp file + rename), so a crashed write can’t corrupt your client config.
mcphub call initializes an MCP session before invoking the tool, accepts JSON or SSE responses, and closes the session after the call. This supports both older sessionful hubs and current hubs through their compatible Streamable HTTP endpoint.
Exit codes
Autonomous-agent recipe
Every command supports--json and reads MCPHUB_URL / MCPHUB_TOKEN, so an agent can drive the entire discover → call loop from JSON:
tools list --json response is intentionally flat ({server, serverStatus, name, description, enabled}) so an agent can filter in one pass without traversing nested servers[*].tools[*].
Scripting and CI
The CLI is JSON-friendly:--json is honored by every command, and MCPHUB_URL / MCPHUB_TOKEN make it easy to skip the credentials file in CI.
MCPHUB_TOKEN_KIND=bearer (or --bearer). Note that only system-level bearer keys with accessType=all authorize the /api/* management surface. Scoped system keys and user-level keys are for MCP transports only.