ADR-0036: Bootstrap Custom Roles from Configuration File

ADR-0036: Bootstrap Custom Roles from Configuration File

• Status: Accepted
• Date: 2026-01-25
• Deciders: Core Engineering Team

Context

Organizations deploying ContextForge need to pre-configure custom RBAC roles that match their organizational structure and access policies. Currently, the only way to create custom roles is through the Admin API after deployment, which creates additional manual steps and potential security gaps during the initial deployment window.

Common use cases requiring custom roles:

• Data Analyst role: Read-only access to tools and resources for data analysis workflows
• Auditor role: Global read access for compliance and security audits
• CI/CD role: Limited permissions for automation pipelines
• Operator role: Permissions to manage servers without full admin access

Decision

We will allow administrators to define custom roles in a JSON configuration file that is automatically loaded during database bootstrap. The feature is:

1. Disabled by default - Requires explicit opt-in via MCPGATEWAY_BOOTSTRAP_ROLES_IN_DB_ENABLED=true
2. File-based configuration - Roles defined in a JSON file specified by MCPGATEWAY_BOOTSTRAP_ROLES_IN_DB_FILE
3. Validated on load - JSON structure is validated; invalid entries are skipped with warnings
4. Idempotent - Existing roles are detected and skipped; safe to run multiple times

Configuration Schema

[
  {
    "name": "role_name",          // Required: unique identifier
    "scope": "team|global",       // Required: access scope
    "permissions": ["..."],       // Required: array of permission strings
    "description": "...",         // Optional: human-readable description
    "is_system_role": true|false  // Optional: prevent user modification
  }
]

File Resolution

When a relative path is provided:

1. Check current working directory
2. Check project root (mcpgateway/bootstrap_db.py → parent.parent)

Error Handling

Consequences

Positive

• ✅ Organizations can pre-configure roles matching their access policies
• ✅ Eliminates manual role creation after deployment
• ✅ Supports GitOps workflows (roles defined in version control)
• ✅ Reduces security gap during initial deployment
• ✅ Graceful degradation on configuration errors

Negative

• ❌ Adds complexity to bootstrap process
• ❌ Requires understanding of permission strings
• ❌ Configuration errors may go unnoticed if not monitoring logs

Neutral

• 🔄 Roles can still be created/modified via Admin API after bootstrap
• 🔄 Feature is opt-in; no impact on existing deployments

Alternatives Considered

Security Considerations

1. File access: Configuration file should be mounted read-only
2. Validation: All entries are validated before processing
3. No secrets: Role definitions don't contain sensitive data
4. Audit trail: All role creation is logged

Implementation

• mcpgateway/config.py: Add configuration settings
• mcpgateway/bootstrap_db.py: Add role loading and validation logic
• tests/unit/mcpgateway/test_bootstrap_db.py: Comprehensive test coverage

Related

• RBAC Configuration - End-user documentation
• Issue #2187 - Feature request
• PR #2188 - Implementation