Skip to main content

Overview

The mcphub 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.
The CLI ships with the same npm package as the server — there’s nothing extra to install.

Logging in

A JWT is cached in an XDG-compliant credentials file with 0600 permissions:
  • macOS/Linux: $XDG_DATA_HOME/mcphub/credentials.json (default ~/.local/share/mcphub/credentials.json)
  • Legacy: ~/.mcphub/credentials.json is still honored when it already exists
Multiple profiles are supported, so a single shell can target staging, prod, etc. side-by-side:
You can also bypass the credentials file entirely: 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.
The hub-generated token is printed once on 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.
The 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.
Routing precedence inside 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.
Notes:
  • --type picks 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 resulting env block.
  • --to file writes 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:
The 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.
For bearer-key auth in CI, add 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.