Authentication & Security

​

Overview

1. Bearer key — a static token created from the dashboard or /api/auth/keys.
2. MCPHub OAuth access token — issued by MCPHub’s own authorization server (optional).
3. Better Auth session cookie — issued by GitHub / Google login (optional).
4. JWT — issued by POST /api/auth/login, sent via the x-auth-token header or ?token= query.
5. skipAuth guest — only when systemConfig.routing.skipAuth is true, the dashboard API treats unauthenticated calls as a synthetic admin guest user.

​

Per-server visibility

• '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 and usernames listed in the server’s sharedWithUsers array can see and call it. Sharing grants runtime access only; selected users cannot edit or delete the server.

​

Login (JWT)

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "username": "admin", "password": "your-password" }'

curl http://localhost:3000/api/servers \
  -H "x-auth-token: <jwt>"

​

Bearer keys

​

MCPHub OAuth authorization server

​

Better Auth (GitHub / Google / local OIDC)

1. BETTER_AUTH_* environment variables
2. systemConfig.auth.betterAuth
3. Built-in defaults

• 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.

• enabled
• providerId
• discoveryUrl
• optional scopes, pkce, and prompt

​

SSO-only sign-in

• 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.

​

Forward auth (JWKS-verified gateway identity)

"systemConfig": {
  "auth": {
    "forwardAuth": {
      "enabled": true,
      "mode": "jwks",
      "jwks": {
        "uri": "https://idp.example.com/.well-known/jwks.json",
        "issuer": "https://idp.example.com/",
        "audience": "mcphub",
        "algorithms": ["RS256", "ES256"]
      },
      "usernameClaim": "preferred_username",
      "emailClaim": "email",
      "autoCreate": true
    }
  }
}

• 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.

• 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.

• 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.

​

Read-only mode

• All GET requests.
• All paths starting with ${basePath}/tools/ (so OpenAPI tool execution still works).

​

Skip-auth mode (local development only)

​

Password policy

​

See also

• Users API — local user CRUD.
• OAuth API — OAuth client management endpoints.
• MCP Settings — where routing, oauth, and auth.betterAuth configuration lives.