Install and start the gateway

Preparation and installation

Prepare an HTTPS MCP URL, writable persistent storage and a separately retained configuration encryption key. Remote administration additionally requires an HTTPS admin origin and a locally initialized administrator account. Run one active Hub instance; PostgreSQL does not coordinate multiple Hub runtimes.

Install mcphub on the gateway host and mcpbridge on user computers. Administrators using the management CLI also need the latter. Server downloads:

Download the server archive and SHA256SUMS from the v2.4.0 release. The following installs Linux arm64; change the filename for your platform and use shasum -a 256 on macOS:

sha256sum mcphub_v2.4.0_linux_arm64.tar.gz
# Compare exactly with the same filename in SHA256SUMS before extracting.
mkdir -p mcphub-release "$HOME/.local/bin"
tar -xzf mcphub_v2.4.0_linux_arm64.tar.gz -C mcphub-release
install -m 755 mcphub-release/mcphub "$HOME/.local/bin/mcphub"
export PATH="$HOME/.local/bin:$PATH"

After installation, run mcphub --version; expect mcphub 2.4.0 (server). validate and serve are server commands. The renamed client mcpbridge connects Agents and cannot start or validate the gateway. Updating source does not replace an existing binary in the directory; use the path of the executable you just installed.

This PATH setting applies to the current terminal. For later runs, use "$HOME/.local/bin/mcphub" directly or add the tools directory to your service environment. With Go 1.26.8 installed:

go install github.com/SamuelSupe/mcphub/v2/cmd/mcphub@v2.4.0

Go installs into go env GOBIN, or $(go env GOPATH)/bin when GOBIN is empty. Add that directory to PATH too.

The v2.4.0 server archive includes the same templates as the online guide. Its default config.example.yaml enables local administration and SQLite with backends: []; only the MCP URL and configuration encryption key are required. Start the console, add each service with its own credentials, test the connection, then publish reviewed tools and configure access. Use the remote templates for team administration, or the independent advanced YAML-only example for deployments without a console.

validate --config PATH checks configuration without creating a SQLite database. serve --config PATH initializes fresh storage and starts the service, writing JSON logs to stderr.

Before deployment, check example selection and configuration ownership, environment/secret syntax and the deployment variable inventory. Add optional modules only when needed.

Local management UI

The default template enables built-in accounts, a loopback console, SQLite, the personal portal and backends: []. The console listens on 127.0.0.1:8081 and requires account sign-in. Use the remote templates and HTTPS for remote access.

Copy the packaged template into a fresh deployment directory and set the public address and persistent key:

cp mcphub-release/config.example.yaml config.yaml
export MCPHUB_PUBLIC_URL=https://hub.example.com/mcp
umask 077
mkdir -p secrets
test -f secrets/config.key || openssl rand -base64 32 > secrets/config.key
export MCPHUB_CONFIG_KEY="$(cat secrets/config.key)"
mcphub validate --config config.yaml
mcphub serve --config config.yaml

In another terminal on the server, enter the same directory, load both variables and initialize the administrator:

export MCPHUB_PUBLIC_URL=https://hub.example.com/mcp
export MCPHUB_CONFIG_KEY="$(cat secrets/config.key)"
mcphub init-admin --config config.yaml --username admin

Password input is hidden and requires at least 12 characters. There is no default password or anonymous web bootstrap. Sign in to the local console, create users and groups, assign group permissions and add members in Users & groups, then add backends → test connections → publish tools.

Only the public address and configuration key are required. Do not set MCPHUB_AUTH_ISSUER or fixed backend variables. The key is Base64-encoded 32 bytes; generate it once and retain the same private file. Inject both variables into your service manager: MCPHub does not load .env. SQLite uses data/mcphub.db next to the YAML file.

The built-in issuer is derived from the public origin with /sso. A fresh gateway with no backends can return /readyz 200 without an external OIDC provider. Readiness does not prove public HTTPS or business backend acceptance. MCPBridge and remote users need working HTTPS, OAuth metadata and portal routes. See built-in accounts for passwords, disabling, MFA and local recovery.

Remote administrators and PostgreSQL

Remote management adds HTTPS administrator sign-in using built-in accounts or optional enterprise SSO, browser sessions, mcpbridge admin and configuration audit attribution. Admin tokens must include admin.public_url in their audience and all admin.required_scopes (default mcphub:admin). Ordinary MCP login does not grant management access.

mcpbridge login --admin --server https://admin.example.com --client-id mcpbridge-admin --profile ops
mcpbridge admin --profile ops get /overview
mcpbridge admin --profile ops get /backends
mcpbridge admin --profile ops get /tool-groups
mcpbridge admin --profile ops get /events

Choose SQLite (default) or PostgreSQL (database_driver: postgres and database_dsn_env). This supports one gateway instance, without multi-instance runtime synchronization. See the deployment guide for account initialization, browser login, API writes, databases and HTTPS proxies.