UI Registration vs SSO Registration in MetaMCP: Configuration Guide

UI Registration controls built-in email/password sign-ups while SSO Registration governs automatic account creation via external identity providers, and both settings operate independently through environment variables or the admin dashboard.

MetaMCP provides granular control over user onboarding through two distinct registration pathways in the metatool-ai/metamcp repository. Administrators can independently manage whether new users create accounts through the native login form or through single sign-on integrations like Google, Azure AD, or OIDC providers. Understanding the differences between these registration modes ensures your authentication policies align with the actual implementation in the bootstrap service and frontend components.

What is UI Registration?

UI Registration governs access to the built-in email and password registration form displayed on MetaMCP's login page. When enabled, visitors can self-register by submitting credentials directly through the web interface. When disabled via BOOTSTRAP_DISABLE_REGISTRATION_UI or the admin toggle, the registration form is suppressed and the backend rejects attempts to create accounts through the native signup endpoint.

What is SSO Registration?

SSO Registration controls whether MetaMCP automatically provisions new user accounts when individuals authenticate through external identity providers such as Google, Azure AD, Keycloak, or generic OIDC providers. When enabled, first-time users logging in via SSO receive automatic account creation. When disabled via BOOTSTRAP_DISABLE_REGISTRATION_SSO, the system blocks automatic account provisioning for external authentications even if the identity verification succeeds.

How to Configure Registration Controls

Environment Variable Configuration

The backend reads registration controls during the bootstrap phase in apps/backend/src/lib/bootstrap.service.ts. The system parses BOOTSTRAP_DISABLE_REGISTRATION_UI and BOOTSTRAP_DISABLE_REGISTRATION_SSO using the parseBool utility, defaulting both to false (enabled).

// apps/backend/src/lib/bootstrap.service.ts
export interface EnvConfig {
  disableUiRegistration: boolean;
  disableSsoRegistration: boolean;
  // ...
}

// Configuration parsing
disableUiRegistration: parseBool(
  process.env.BOOTSTRAP_DISABLE_REGISTRATION_UI,
  false,
),
disableSsoRegistration: parseBool(
  process.env.BOOTSTRAP_DISABLE_REGISTRATION_SSO,
  false,
),

These variables are documented in the repository's example.env file:

# example.env

BOOTSTRAP_DISABLE_REGISTRATION_UI=false   # Allow form-based sign-ups

BOOTSTRAP_DISABLE_REGISTRATION_SSO=true   # Block SSO-based sign-ups

Admin Dashboard Configuration

The Settings → Authentication page provides visual toggles labeled "Disable UI Registration" and "Disable SSO Registration". These controls modify the underlying environment configuration through the backend API and take effect immediately.

<Switch
  label="Disable UI Registration"
  checked={config.disableUiRegistration}
  onChange={toggleUiRegistration}
/>
<Switch
  label="Disable SSO Registration"
  checked={config.disableSsoRegistration}
  onChange={toggleSsoRegistration}
/>

Implementation Details

During application initialization, the bootstrap service evaluates the EnvConfig interface settings to determine registration availability. The disableUiRegistration and disableSsoRegistration booleans gate the respective signup routes and SSO callback logic, returning registration disabled errors when attempts occur on blocked pathways.

When restrictions are active, the service logs the configuration state:

// apps/backend/src/lib/bootstrap.service.ts
if (config.disableUiRegistration) {
  console.log('✓ UI registration disabled');
}
if (config.disableSsoRegistration) {
  console.log('✓ SSO registration disabled');
}

Four Possible Configuration States

Because these switches operate independently, administrators can implement specific onboarding policies:

1. UI Only — Disable SSO Registration while allowing email/password sign-ups for manual user vetting.
2. SSO Only — Disable UI Registration to force all new accounts through corporate identity providers.
3. Closed Registration — Disable both to completely prevent new sign-ups while maintaining existing users.
4. Open Registration — Enable both to allow self-service account creation through any available method.

Summary

• UI Registration controls the native email/password registration form, configured via BOOTSTRAP_DISABLE_REGISTRATION_UI or the "Disable UI Registration" toggle in Settings → Authentication.
• SSO Registration governs automatic account creation through external identity providers, configured via BOOTSTRAP_DISABLE_REGISTRATION_SSO or the "Disable SSO Registration" toggle.
• Both settings default to enabled (false) and are parsed in apps/backend/src/lib/bootstrap.service.ts during the bootstrap phase using the EnvConfig interface.
• The system allows four independent states: UI-only, SSO-only, closed, or open registration.

Frequently Asked Questions

Can I disable email registration but still allow users to sign up via Google or Azure AD?

Yes. Set BOOTSTRAP_DISABLE_REGISTRATION_UI=true while keeping BOOTSTRAP_DISABLE_REGISTRATION_SSO=false. This blocks the built-in registration form while preserving automatic account creation when users authenticate through configured SSO providers in MetaMCP.

What happens if a user tries to log in via SSO when SSO Registration is disabled?

The authentication attempt will fail with a registration disabled error. The user cannot create a new account through SSO, though existing users can still log in. Administrators must manually create accounts or temporarily enable SSO Registration to allow new user provisioning.

Do these settings affect existing user accounts?

No. Both UI Registration and SSO Registration controls only affect the creation of new accounts. Existing users retain full login capabilities regardless of these configuration changes, including password resets for UI accounts and continued SSO access for previously provisioned users.

Where are these configurations defined in the MetaMCP source code?

The registration flags are defined in the EnvConfig interface within apps/backend/src/lib/bootstrap.service.ts. The environment variables are documented in example.env, and the admin UI implementation references these same configuration keys to render the authentication settings toggles according to the current bootstrap configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}