Skip to main content

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 as systemConfig.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):
  1. Bearer key — a static token created from the dashboard or /api/auth/keys.
  2. Better Auth session cookie — issued by GitHub / Google login (optional).
  3. JWT — issued by POST /api/auth/login, sent via the x-auth-token header or ?token= query.
  4. skipAuth guest — only when systemConfig.routing.skipAuth is true, the dashboard API treats unauthenticated calls as a synthetic admin guest user.
All persistent user records are stored as { 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 a visibility 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’s owner (and admins) can see it. Servers seeded from mcp_settings.json migrate 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 in sharedWithUsers, and members of groups listed in sharedWithUserGroups can see and call it. Sharing grants runtime access only; selected users cannot edit or delete the server.
Administrators assign user groups in Users → Edit → User groups, using comma-separated, case-sensitive names. The same name on multiple users identifies one user group; clearing a user’s list removes all memberships. These user groups are independent of server Groups. Server owners select existing user groups in the server sharing controls; group-route sharing offers the same selection. For example, a user with 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:
The response includes a JWT. Send it on subsequent requests using the x-auth-token header:
The JWT is signed with 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 original Origin (or Host and 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_state table, 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 with JWT_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.json with owner-only permissions, outside mcp_settings.json and configuration exports. Database mode uses the user_passkeys table; with DB_SYNCHRONIZE=false, apply docs/migrations/0008-passkeys.sql before upgrading. Migrating from file to database mode copies passkeys with their users.
  • Rate limits: issuing sign-in challenges is capped by PASSKEY_RATE_LIMIT_MAX per PASSKEY_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

When systemConfig.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)

Upgrading from MCPHub v1.1.14 or earlier: Better Auth 1.7 uses /sign-in/social for generic OIDC login and changes the provider callback from /oauth2/callback/<providerId> to /callback/<providerId>. Add the new exact redirect URI to your identity provider before upgrading: <public MCPHub URL><Better Auth basePath>/callback/<providerId>. With the default mount and provider ID, this is https://mcphub.example.com/api/auth/better/callback/oidc. Include any installation BASE_PATH and custom BETTER_AUTH_BASE_PATH. Keep the old URI allowed while older instances remain in service. This is the identity provider callback, not the dashboard destination after login.
Better Auth is optional and initialized once at process startup. That means any change to either BETTER_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:
  1. BETTER_AUTH_* environment variables
  2. systemConfig.auth.betterAuth
  3. Built-in defaults
Provider credentials remain environment-variable only. Required variables (see .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 to oidc).
  • 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 — optional prompt parameter for local OIDC login.
  • OIDC_CLIENT_ID / OIDC_CLIENT_SECRET — for a local OIDC provider.
For a local issuer (for example Keycloak, Authentik, or Dex), you can either configure the metadata entirely through environment variables, or keep the non-secret values in systemConfig.auth.betterAuth.providers.oidc with:
  • enabled
  • providerId
  • discoveryUrl
  • optional scopes, pkce, and prompt
The 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.
When enabled, Better Auth mounts at ${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 set systemConfig.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_LOGIN overrides the stored setting in both directions. If the identity provider is unavailable, set it to false and 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> --bearer for 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).
The JWT is read from the configured bearer header (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.
Verification
  • The token is verified against jwks.uri. Keys are cached and refetched when a token carries an unknown kid, so key rotation at the identity provider needs no restart.
  • iss, aud, and exp are always validated; sub and exp are required. A 30-second clock tolerance applies.
  • Only asymmetric algorithms are accepted (RS*, PS*, ES*, EdDSA; default RS256 and ES256). Listing HS* or none disables forward auth.
  • jwks.uri must use https (plain http is allowed only for localhost). issuer and audience are required. If the configuration is incomplete or invalid, forward auth stays disabled and MCPHub logs an error.
Request handling
  • Forward auth is checked before bearer keys, OAuth tokens, Better Auth sessions, and dashboard JWTs.
  • A token that is not a JWT, or whose iss is 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.
Identity mapping
  • The identity is the pair (iss, sub). It is stored in the user’s ssoUserId under a forward-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 to emailClaim, then sub.
  • 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 with 401.
  • 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.
Forward-auth settings are read on each request, so changes do not require a restart. Each field can be overridden by an environment variable; see Environment variables.

Read-only mode

Set READONLY=true to prevent any mutating request from succeeding. The middleware permits:
  • All GET requests.
  • All paths starting with ${basePath}/tools/ (so OpenAPI tool execution still works).
Other methods receive 403.

Skip-auth mode (local development only)

skipAuth disables dashboard authentication entirely. When systemConfig.routing.skipAuth = true, every unauthenticated request to ${basePath}/api/* is automatically treated as a synthetic admin user ({ username: 'guest', isAdmin: true }). Anyone who can reach the API — including a misconfigured reverse proxy, a forgotten port-forward, or a public cloud IP — gets full administrative access: they can read every server’s secrets, create / delete users, mint bearer keys, and exfiltrate the entire mcp_settings.json. Never enable this in staging, production, demo, or any deployment that is reachable beyond localhost. Bind MCPHub to 127.0.0.1 while developing, and double-check that skipAuth is false before deploying. MCP transport routes (/mcp/*, /sse/*) are not affected by skipAuth and continue to require their own credentials.
The flag exists purely to make local iteration painless: you can hit the dashboard API from curl 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 by src/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, and auth.betterAuth configuration lives.