Users, roles and authentication

Administration access

The administration panel requires authentication in MCPBox 1.4.0. Create the first local administrator as described in first launch, then use the access settings to manage users, passwords, sessions and agent tokens.

System role	Scopes	Intended use
reader	pro:read	Read protected administrative data.
operator	pro:read, pro:write	Day-to-day configuration and operational changes.
admin	pro:admin	Full administration, including privileged changes and revocation.

The pro: scope names and /api/pro/* routes are compatibility identifiers. They do not refer to a paid edition. Ordinary API reads require pro:read, most writes require pro:write, and deletions, CLI mutations/execution and project token actions require pro:admin. Individual endpoints can impose their own scope.

Sessions and agent tokens

Local sign-in creates a session. Administrators can review and revoke sessions. Use a dedicated administrative agent token with the needed scopes and lifetime for automation; do not reuse a person's session token. A raw token is returned on creation, so save it at that point.

Administrative API requests use:

Authorization: Bearer <admin-session-or-agent-token>

Agent tokens administer MCPBox according to their scopes. They are not project endpoint Bearer tokens or OAuth client secrets. Project access is configured separately in connections.

MCPBOX_PRO_BOOTSTRAP_TOKEN remains available as a bootstrap administrative credential for compatibility. Keep it secret if used; local administrator sign-in is the normal first-run workflow.

Optional OIDC sign-in

Set these environment variables before starting MCPBox:

Variable	Value
MCPBOX_PRO_OIDC_ISSUER_URL	Your OIDC provider's issuer URL.
MCPBOX_PRO_OIDC_CLIENT_ID	Registered client ID.
MCPBOX_PRO_OIDC_CLIENT_SECRET	Registered client secret.
MCPBOX_PRO_OIDC_REDIRECT_URL	The externally reachable admin URL plus /api/pro/sso/callback.

Register the same redirect URL with the provider. For example, an admin deployment at https://admin.example.com uses https://admin.example.com/api/pro/sso/callback.

Optional settings:

Variable	Default / purpose
MCPBOX_PRO_OIDC_PROVIDER_NAME	OIDC, shown in sign-in.
MCPBOX_PRO_OIDC_SCOPES	openid profile email, space-separated.
MCPBOX_PRO_OIDC_DEFAULT_ROLE	reader for new users.
MCPBOX_PRO_OIDC_AUTO_CREATE_USERS	true; controls automatic account creation.
MCPBOX_PRO_OIDC_SESSION_DAYS	30.
MCPBOX_PRO_OIDC_ALLOWED_HD	Optional hosted-domain restriction.

Restart after changing OIDC environment settings. OIDC signs users into the panel; project OAuth is a separate mechanism. PolicyBox was removed in v1.4.0; see migration.