Self-registration
Administrators can enable Allow self-registration under Settings → Security. It is disabled by default. When enabled, the login page offers Create account. New accounts are always regular users; registration cannot grant administrator privileges. Usernames still referenced by resource ownership, sharing lists, authentication state, or user configuration cannot be claimed through self-registration, even after the original account is deleted. Passwords must contain at least eight characters, including a letter, a number, and a special character. The setting is stored assystemConfig.auth.allowRegistration in mcp_settings.json
and works with both file and database storage. It takes effect without a restart.
When password login is disabled by the effective SSO configuration, local registration is
also refused and the registration entry is hidden. Existing accounts remain available.
Overview
The dashboard API supports the following authentication paths (configured forward auth is evaluated first):- Bearer key — a static token created from the dashboard or
/api/auth/keys. - Better Auth session cookie — issued by GitHub / Google login (optional).
- JWT — issued by
POST /api/auth/login, sent via thex-auth-tokenheader or?token=query. skipAuthguest — only whensystemConfig.routing.skipAuthistrue, the dashboard API treats unauthenticated calls as a synthetic adminguestuser.
{ username, password, isAdmin }. There are no manager or viewer roles; permissions are binary (admin or not). Social accounts that log in via Better Auth live in a separate mcphub_better_auth_* table but are mapped to the same username / isAdmin shape at request time.
Per-server visibility
Each server has avisibility setting (private / group / public) that controls which non-admin users can discover and call the server. Admins always have access. The same filter is applied to dashboard listings, direct tool and prompt calls, group routes, and $smart routing.
'private'(default): only the server’sowner(and admins) can see it. Servers seeded frommcp_settings.jsonmigrate in with'private'to preserve the historical admin-only behaviour.'public': every authenticated user can see and call the server. Use this for servers you want to share across all users of the same MCPHub instance — including social-login users created by Better Auth.'group': the owner, usernames listed insharedWithUsers, and members of groups listed insharedWithUserGroupscan see and call it. Sharing grants runtime access only; selected users cannot edit or delete the server.
userGroups: ["readers"] can use a server with visibility: "group" and sharedWithUserGroups: ["readers"]. Membership changes apply on the next authenticated request, including existing user-key and OAuth sessions. Sharing a group route does not grant access to its underlying servers: configure both as needed. Sharing grants usage, not configuration management, and tool policies can further restrict it.
The visibility is editable per server from the dashboard (Server form → Advanced Options → Visibility). Edit an existing server to select local usernames for 'group' sharing. For deployments where every user should see every server (single-user self-hosted, small trusted team), an operator can set the relevant servers to 'public' from the dashboard.
Login (JWT)
The dashboard and any script that does not present a bearer key uses the JWT flow:x-auth-token header:
JWT_SECRET. If JWT_SECRET is not set, MCPHub generates an ephemeral random secret at startup; this is fine for development but means every restart invalidates outstanding tokens. Set JWT_SECRET explicitly in production.
Issued JWTs expire after a fixed 24 hours (DASHBOARD_TOKEN_EXPIRY in src/utils/userSession.ts); the lifetime is not configurable via environment variables.
JWTs, passkeys and MCPHub OAuth grants are bound to the user’s current password hash. Deleting the local user or changing their password invalidates those credentials; recreating the same username does not restore them. JWT authorization reads the user’s current administrator status. User deletion also removes OAuth tokens, pending authorization codes on the handling instance, and entries in server/group sharing lists.
Upgrading from credentials without a session version requires signing in again and reconnecting OAuth clients. Database deployments add a nullable session_version column to oauth_tokens through the normal startup schema synchronization. Restart every replica when upgrading.
POST /api/auth/register follows the opt-in self-registration policy above and always creates a non-admin user. Use the administrator user-management API to assign roles.
The first admin account is created at startup by initializeDefaultUser(). If no users exist, MCPHub creates admin and uses ADMIN_PASSWORD if set. When running through pnpm dev, it uses admin123; other starts generate a random password and print it to the server logs.
Passkeys
Local accounts can sign in with a passkey (WebAuthn) instead of a password. A passkey is a discoverable credential held by the user’s device, password manager, or security key, so the login page asks for no username: select Sign in with a passkey and confirm with the device’s fingerprint, face, screen lock, or PIN. To add one, open the user menu → Passkeys → Add passkey, enter an optional name and the current password, then follow the browser prompt. The password confirms the session owner before a long-lived credential is added. The page lists each passkey with when it was added and last used and whether it is synced, and removes any of them after confirmation. An account can hold up to 20 passkeys.- Secure context: browsers offer passkeys only on HTTPS pages or on
localhost, and only for a domain name, not an IP address. - Bound to the host name: a passkey belongs to the host name the dashboard was opened with when it was created (the WebAuthn relying-party ID). MCPHub takes it from the browser’s
Origin, stores it with the passkey, and accepts the passkey only under that host. Opening the dashboard under another host name requires a separate passkey there. Behind a reverse proxy, pass the originalOrigin(orHostand protocol) through to MCPHub. - Session: passkey sign-in issues the same 24-hour JWT as password login and requires user verification on the authenticator. Each challenge expires after five minutes and is accepted once; in replica mode the spent challenge is recorded in the shared
oauth_statetable, so this holds across replicas. Signature counters reject a cloned authenticator that reports them: the stored counter only moves forward, also when sign-ins race, while authenticators that always report 0 (most synced passkeys) keep working. Challenges are signed withJWT_SECRET, so the two requests of a sign-in may reach different replicas. - Policy: passkeys are a local-account credential, so SSO-only sign-in refuses passkey sign-in and registration as well; stored passkeys work again when password login is re-enabled. Bearer keys, forward-auth identities, and skip-auth mode cannot register passkeys, and users created by SSO keep signing in through their provider because they have no known local password.
- Lifecycle: like JWTs and OAuth grants, passkeys are bound to the account’s current password. Changing or resetting the password, or deleting and recreating the user, revokes them, and the user adds them again afterwards. Remove the passkey of a lost device from the Passkeys page; after an account compromise, reset the password to revoke every passkey.
- Storage: file mode keeps passkeys in
<settings file>.passkeys.jsonwith owner-only permissions, outsidemcp_settings.jsonand configuration exports. Database mode uses theuser_passkeystable; withDB_SYNCHRONIZE=false, applydocs/migrations/0008-passkeys.sqlbefore upgrading. Migrating from file to database mode copies passkeys with their users. - Rate limits: issuing sign-in challenges is capped by
PASSKEY_RATE_LIMIT_MAXperPASSKEY_RATE_LIMIT_WINDOW_MS(default 100 per 15 minutes). Failed passkey sign-ins and failed password confirmations count against the login limiter (AUTH_RATE_LIMIT_MAX).
Bearer keys
Administrators and owners of user-level keys can select Reset Bearer key in Settings. After confirmation,POST /api/auth/keys/:id/reset generates a new token and returns it once for viewing and copying. The previous token stops working immediately. The key ID, name, kind, owner, enabled status and resource scope stay unchanged. Only the hash and prefix are stored; list responses remain masked.
Bearer keys are long-lived static tokens managed at /api/auth/keys. Tokens are generated by the backend and returned in plaintext only once, in the create or reset response. Later list and update responses contain a masked value.
Admins can create and manage all keys. Regular users can create, rename, enable, disable and delete
their own user-level keys from the settings page. User-level keys are MCP transport credentials only:
they are never accepted by the dashboard / management API. When used on
/mcp, /mcp/$smart or a
group/server endpoint, MCPHub resolves the current owner record and applies that user’s live server
visibility. The optional /:user/mcp/... routes remain supported, but the URL username must match the
key owner.
Personal keys support accessType: 'all' (the default, retaining the owner’s permissions) or accessType: 'groups' with a non-empty allowedGroups array. Select the scope when creating or editing a key in Settings. The API accepts existing group names or IDs and saves group IDs. A restricted key can use only /mcp/{allowed-group} and /mcp/$smart/{allowed-group} (and equivalent SSE/user-scoped routes). Global /mcp, global $smart, direct-server routes, and other groups are denied, even when the target server belongs to an allowed group. This preserves group capability selections. Multiple allowed groups are accessed through their individual endpoints, without an aggregate global catalog.
The key scope always intersects with the owner’s current group/server visibility and group capability selections; it never grants additional permissions. An administrator-owned personal key still obeys its group scope. Group deletion or an empty persisted allow list denies access rather than restoring unrestricted access. Existing keys without a group restriction retain their behavior. Recognized personal keys still enforce their identity and scope when enableBearerAuth is false; anonymous requests remain governed by that deployment setting.
System-level keys preserve the original scoped-key behavior. Only system-level keys with
accessType === 'all' are accepted by the dashboard / management API middleware. Restricted
system-level keys are enforced at the MCP transport layer.
accessType: 'exclude' is the inverse of an allow list: the key can use the global /mcp and
/mcp/$smart endpoints, but servers named in excludedServers and every member of a group named
in excludedGroups disappear from listings, smart routing, and tool/prompt/resource calls. A
group route whose members are all excluded is rejected, and a server that belongs to both an
excluded and a non-excluded group stays excluded. Exclusions fail safe when a name goes stale: a
leftover entry only denies something that no longer exists. The scope requires at least one
excluded group or server and is available only to system-level keys.
The header name can be customized via systemConfig.routing.bearerAuthHeaderName (default Authorization). The legacy systemConfig.routing.bearerAuthKey field is preserved only for one-time migration into the bearer key store.
To globally turn off bearer auth on MCP endpoints, set systemConfig.routing.enableBearerAuth to false.
MCPHub OAuth authorization server
WhensystemConfig.oauthServer.enabled is true, MCPHub exposes an OAuth 2.0 / OIDC-compatible server (@node-oauth/oauth2-server). Endpoints:
OAuth access tokens issued here authenticate MCP transport requests and
/oauth/userinfo. They are not dashboard API credentials and are rejected on /api/*; use a dashboard JWT, Better Auth session, configured forward auth, or a system all-access bearer key for management.
Better Auth (GitHub / Google / local OIDC)
Better Auth is optional and initialized once at process startup. That means any change to eitherBETTER_AUTH_* environment variables or stored systemConfig.auth.betterAuth values still requires a restart.
Non-secret Better Auth settings can now live either in environment variables or in systemConfig.auth.betterAuth (from mcp_settings.json or the database-backed system config). The priority order is:
BETTER_AUTH_*environment variablessystemConfig.auth.betterAuth- Built-in defaults
.env.example):
BETTER_AUTH_ENABLED— master switch for Better Auth.BETTER_AUTH_URL— public base URL of MCPHub (used to build redirect URIs).BETTER_AUTH_BASE_PATH— optional mount path override for the Better Auth handler.BETTER_AUTH_TRUSTED_ORIGINS— optional extra trusted origins (comma-separated, whitespace-separated, or JSON array).BETTER_AUTH_DISABLE_PASSWORD_LOGIN— turn off username/password login while an SSO provider is enabled (see SSO-only sign-in).BETTER_AUTH_GOOGLE_ENABLED— enable / disable Google login when credentials are present.GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET— for Google login.BETTER_AUTH_GITHUB_ENABLED— enable / disable GitHub login when credentials are present.GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET— for GitHub login.BETTER_AUTH_OIDC_ENABLED— enable / disable the generic OIDC provider.BETTER_AUTH_OIDC_PROVIDER_ID— OIDC provider identifier (defaults tooidc).BETTER_AUTH_OIDC_DISCOVERY_URL— discovery URL for a local issuer.BETTER_AUTH_OIDC_SCOPES— optional requested scopes for local OIDC login.BETTER_AUTH_OIDC_PKCE— optional PKCE toggle for local OIDC login.BETTER_AUTH_OIDC_PROMPT— optionalpromptparameter for local OIDC login.OIDC_CLIENT_ID/OIDC_CLIENT_SECRET— for a local OIDC provider.
systemConfig.auth.betterAuth.providers.oidc with:
enabledproviderIddiscoveryUrl- optional
scopes,pkce, andprompt
discoveryUrl should point at the provider’s /.well-known/openid-configuration endpoint. OIDC_DISCOVERY_URL remains supported as a legacy alias for BETTER_AUTH_OIDC_DISCOVERY_URL, and it can still be referenced from config files via ${OIDC_DISCOVERY_URL}. The login page shows a generic Continue with OIDC button when this provider is enabled.
If the dashboard runs behind a different public origin, set BETTER_AUTH_TRUSTED_ORIGINS (or systemConfig.auth.betterAuth.trustedOrigins) to allow that origin to start the login flow. If no explicit trusted origins are configured, MCPHub automatically trusts the origins from BETTER_AUTH_URL and systemConfig.install.baseUrl when they are set.
Better Auth in MCPHub currently requires PostgreSQL-backed storage (
DB_URL). File-only mode does not support Better Auth sessions, including local OIDC login.${BASE_PATH}${betterAuthConfig.basePath} (default /api/auth/better). BETTER_AUTH_BASE_PATH overrides the stored betterAuth.basePath value at startup. A valid Better Auth session cookie counts as authentication for the dashboard API. The mapped MCPHub user is admin only if a local user with the same username exists and is marked admin.
Local OIDC login follows the same mapping rule as GitHub / Google login: MCPHub resolves a local username from the Better Auth session (email ?? name ?? id). If that username does not exist yet, MCPHub auto-creates a non-admin local user. OIDC login never auto-promotes a user to admin.
SSO-only sign-in
To allow sign-in only through the SSO providers, turn on Disable password login in Settings → Better Auth, or setsystemConfig.auth.betterAuth.disablePasswordLogin: true. The login page then shows only the provider buttons, and POST /api/auth/login answers 403. Unlike the other Better Auth settings, it takes effect without a restart.
- No lockout: it applies only while at least one provider is actually enabled (Better Auth on, database mode, credentials present) and was enabled when MCPHub started, since a provider’s sign-in route is set up only at startup. Otherwise password login stays available: after enabling a new provider, restart MCPHub before the switch applies.
- Recovery:
BETTER_AUTH_DISABLE_PASSWORD_LOGINoverrides the stored setting in both directions. If the identity provider is unavailable, set it tofalseand restart to sign in with a local password again. Keep a strong password on the local admin for that case. - Scripts and the CLI cannot use the password login while it is disabled. Use a system-level bearer key with access type
all, which authenticates the management API (mcphub config set-token <key> --bearerfor the CLI). - Tokens issued by earlier password logins stay valid until they expire. Changing a local password still works, so the recovery password can be rotated.
- Passkeys are refused too while password login is disabled, because they sign in to local accounts.
Forward auth (JWKS-verified gateway identity)
When MCPHub runs behind an API gateway or identity-aware proxy that already authenticates users, forward auth lets MCPHub trust the gateway’s JWT instead of asking users to log in again. MCPHub verifies the token itself against the identity provider’s JWKS, so it remains the security boundary. Forward auth is off by default and applies to both the dashboard API and the MCP transport routes (/mcp/*, /sse/*, and their user-scoped variants).
Authorization: Bearer <jwt> by default).
Some gateways send the JWT in a header of their own without a Bearer prefix; Cloudflare Access, for example, adds Cf-Access-Jwt-Assertion to every request it admits. Set jwks.tokenHeader to that header name to read the token from it, sent either raw or as Bearer <jwt>. Once a token header is set, forward auth reads only that header, while the bearer header keeps working for bearer keys and OAuth tokens. MCPHub never forwards the token header to upstream servers, even when it is listed in passthroughHeaders. An invalid header name disables forward auth.
- The token is verified against
jwks.uri. Keys are cached and refetched when a token carries an unknownkid, so key rotation at the identity provider needs no restart. iss,aud, andexpare always validated;subandexpare required. A 30-second clock tolerance applies.- Only asymmetric algorithms are accepted (
RS*,PS*,ES*,EdDSA; defaultRS256andES256). ListingHS*ornonedisables forward auth. jwks.urimust usehttps(plainhttpis allowed only forlocalhost).issuerandaudienceare required. If the configuration is incomplete or invalid, forward auth stays disabled and MCPHub logs an error.
- Forward auth is checked before bearer keys, OAuth tokens, Better Auth sessions, and dashboard JWTs.
- A token that is not a JWT, or whose
issis not the configured issuer, is ignored and the other methods run as usual. - A token from the configured issuer that fails verification (bad signature, expired, wrong audience, disallowed algorithm) or cannot be mapped to a user is rejected with
401. MCPHub never falls back to another authentication method for it.
- The identity is the pair (
iss,sub). It is stored in the user’sssoUserIdunder aforward-auth:namespace, separate from Better Auth identities. A Better Auth login never adopts a forward-auth user, and forward auth never adopts a Better Auth user. - On first sight, MCPHub creates a non-admin local user. Its username comes from
usernameClaim, falling back toemailClaim, thensub. - Existing accounts are never linked by username or email. If the username or email already belongs to another account, including
admin, the request is rejected with401. - Once bound, the local username does not change when the user is renamed at the identity provider, because servers, groups, and keys reference the username.
- Admin status always comes from the local user record. Role claims in the JWT are ignored.
- With
autoCreate: false, only identities already bound to a local user are accepted. Because existing accounts are never linked, this effectively rejects every new identity.
Read-only mode
SetREADONLY=true to prevent any mutating request from succeeding. The middleware permits:
- All
GETrequests. - All paths starting with
${basePath}/tools/(so OpenAPI tool execution still works).
403.
Skip-auth mode (local development only)
The flag exists purely to make local iteration painless: you can hit the dashboard API fromcurl or a frontend dev server without pasting a JWT. If you need API access from automated tooling instead, prefer a scoped bearer key (/api/auth/keys) over skipAuth.
Password policy
Local user passwords are validated bysrc/utils/passwordValidation.ts (length and character-class rules). Failed validations on POST /api/users or PUT /api/users/:username return 400 with the failed checks under errors.
See also
- Users API — local user CRUD.
- OAuth API — OAuth client management endpoints.
- MCP Settings — where
routing,oauth, andauth.betterAuthconfiguration lives.