Role-Based Access Control (RBAC)

Control access to MCP servers and tools based on user group membership. RBAC enables you to implement fine-grained security policies for enterprise deployments.

RBAC in Nexus allows you to:

• Restrict access to specific MCP servers based on user groups
• Apply granular tool-level permissions within servers
• Create tiered access levels (e.g., basic, premium, enterprise)
• Block suspended or restricted users
• Maintain backward compatibility with existing deployments

RBAC operates at two levels:

1. Server-level rules: Control access to entire MCP servers
2. Tool-level rules: Override server rules for specific tools

Key principles:

• Deny takes precedence: If a user is in a denied group, they're blocked regardless of allow rules
• Empty allow list blocks all: An empty allow list prevents all access (no client identification needed)
• Tool rules override server rules: Tool-specific settings take precedence
• No rules means open access: Without RBAC configuration, access remains unrestricted

RBAC with group-based access requires client identification to determine user groups:

[server.client_identification]
enabled = true  # Required for group-based access
client_id.http_header = "X-Client-ID"  # or client_id.jwt_claim = "sub"
group_id.http_header = "X-Group-ID"    # or group_id.jwt_claim = "groups"

Note: An empty allow list (allow = []) blocks all access without requiring client identification.

For detailed client identification setup, see the Client Identification documentation.

Configure valid group values for your organization:

[server.client_identification.validation]
# Define your organization's group structure
group_values = ["basic", "premium", "enterprise", "admin", "suspended"]

Control who can access entire MCP servers:

[mcp]
enabled = true

[mcp.servers.premium_tools]
cmd = ["premium-server"]
allow = ["premium", "enterprise", "admin"]  # Allowed groups
deny = ["suspended"]                        # Blocked groups

[mcp]
enabled = true

[mcp.servers.public_api]
url = "https://api.public.com/mcp"
# No allow/deny rules - accessible to all users

[mcp]
enabled = true

[mcp.servers.premium_features]
cmd = ["premium-mcp-server"]
allow = ["premium", "enterprise", "admin"]
deny = ["suspended", "trial_expired"]

[mcp]
enabled = true

[mcp.servers.admin_tools]
cmd = ["admin-server"]
allow = ["admin"]  # Only administrators can access

Override server-level rules for specific tools:

[mcp]
enabled = true

[mcp.servers.api_tools]
cmd = ["api-server"]
allow = ["basic", "premium", "enterprise"]  # Server accessible to most users

# But restrict expensive operations
[mcp.servers.api_tools.tools.bulk_export]
allow = ["enterprise"]  # Only enterprise users can bulk export

[mcp.servers.api_tools.tools.deprecated_function]
allow = []  # Empty allow list blocks all access to this tool (no client ID needed)

[mcp.servers.api_tools.tools.admin_function]
allow = ["admin"]  # Only admins can use this specific tool

Check for:

• User in deny list (deny takes precedence)
• Missing client identification
• Invalid or missing group claims in token

Verify:

• Tool-level rules don't conflict with server rules
• Tool name matches exactly
• Empty allow list not blocking access

Ensure:

• Not using empty allow list unintentionally
• Client identification is properly configured
• Groups are correctly extracted from tokens
• group_values in [server.client_identification.validation] includes all groups used in allow/deny lists

• Set up Client Identification to enable user recognition
• Configure Authentication for secure access
• Set up Rate Limiting per group
• Monitor with Telemetry and audit logs
• Review Best Practices for production deployments