{{ service.description or "No description available." }}
{% for tag in service.tags %}
{{ tag }}
{% endfor %}
{{ service.num_tools }} tools
{{ service.health_status }}
{% if service.last_checked_iso %}
Last checked: {{ service.last_checked_iso }}
{% endif %}
{% endfor %}
{% if user_context.can_modify_servers %}
{% endif %}
```
### Real-Time WebSocket Integration
The UI includes real-time health status updates via WebSocket connections:
```mermaid
sequenceDiagram
participant UI as Dashboard UI
participant WS as WebSocket Connection
participant HMS as Health Monitoring Service
participant SS as Server Service
Note over UI,SS: WebSocket Initialization
UI->>WS: Connect to /ws/health_status
WS->>HMS: Register new connection
HMS->>UI: Send initial health status data
Note over UI,SS: Real-Time Health Updates
loop Background Health Checks
HMS->>SS: Check server health status
SS-->>HMS: Updated health data
HMS->>HMS: Compare with previous status
alt Status Changed
HMS->>WS: Broadcast health update
WS->>UI: Send updated status
UI->>UI: Update service card UI
end
end
Note over UI,SS: User-Triggered Actions
UI->>SS: Toggle server state
SS->>HMS: Immediate health check
HMS->>WS: Broadcast status update
WS->>UI: Real-time status update
UI->>UI: Update toggle switch & status
```
#### WebSocket Client Implementation
```javascript
// Real-time health status WebSocket connection
class HealthStatusManager {
constructor() {
this.ws = null;
this.reconnectInterval = 5000;
this.maxReconnectAttempts = 10;
this.reconnectAttempts = 0;
}
connect() {
const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
const wsUrl = `${protocol}//${window.location.host}/ws/health_status`;
this.ws = new WebSocket(wsUrl);
this.ws.onopen = () => {
console.log('Health status WebSocket connected');
this.reconnectAttempts = 0;
};
this.ws.onmessage = (event) => {
try {
const healthData = JSON.parse(event.data);
this.updateHealthStatusUI(healthData);
} catch (error) {
console.error('Error parsing health status data:', error);
}
};
this.ws.onclose = () => {
console.log('Health status WebSocket disconnected');
this.attemptReconnect();
};
this.ws.onerror = (error) => {
console.error('WebSocket error:', error);
};
}
updateHealthStatusUI(healthData) {
for (const [servicePath, status] of Object.entries(healthData)) {
const serviceCard = document.querySelector(`[data-service-path="${servicePath}"]`);
if (serviceCard) {
// Update health status indicator
const statusElement = serviceCard.querySelector('.health-status');
if (statusElement) {
statusElement.textContent = status.status;
statusElement.className = `health-status ${status.status.replace(/[^a-zA-Z0-9]/g, '-')}`;
}
// Update tool count
const toolCountElement = serviceCard.querySelector('.tool-count');
if (toolCountElement) {
toolCountElement.textContent = `${status.num_tools} tools`;
}
// Update timestamp
const timestampElement = serviceCard.querySelector('.timestamp');
if (timestampElement && status.last_checked_iso) {
timestampElement.textContent = `Last checked: ${status.last_checked_iso}`;
}
}
}
}
attemptReconnect() {
if (this.reconnectAttempts < this.maxReconnectAttempts) {
this.reconnectAttempts++;
console.log(`Attempting to reconnect (${this.reconnectAttempts}/${this.maxReconnectAttempts})...`);
setTimeout(() => this.connect(), this.reconnectInterval);
} else {
console.error('Max reconnection attempts reached');
}
}
}
// Initialize WebSocket connection when page loads
document.addEventListener('DOMContentLoaded', () => {
const healthManager = new HealthStatusManager();
healthManager.connect();
});
```
### Server Management UI Workflows
#### Service Toggle Workflow
```mermaid
sequenceDiagram
participant U as User
participant UI as Dashboard UI
participant R as Registry Backend
participant HMS as Health Monitoring
participant WS as WebSocket
U->>UI: Click toggle switch
UI->>UI: Disable toggle (show loading)
UI->>R: POST /toggle/{service_path}
R->>R: Check user permissions
alt Insufficient Permissions
R->>UI: 403 Forbidden
UI->>UI: Show error message
UI->>UI: Revert toggle state
else Sufficient Permissions
R->>R: Update service state
R->>HMS: Trigger immediate health check
HMS->>HMS: Perform health check
R->>UI: 200 OK with new state
UI->>UI: Update toggle state
HMS->>WS: Broadcast health update
WS->>UI: Real-time status update
UI->>UI: Update status indicators
end
```
#### Server Creation Workflow (Admin Only)
```mermaid
flowchart TD
Start([User clicks "Add Server"]) --> CheckPerms{User has modify permissions?}
CheckPerms -->|No| ShowError[Show permission error]
CheckPerms -->|Yes| ShowForm[Display server creation form]
ShowForm --> UserFillsForm[User fills server details]
UserFillsForm --> ValidateForm{Form validation passes?}
ValidateForm -->|No| ShowValidationErrors[Show validation errors]
ValidateForm -->|Yes| SubmitForm[Submit form to backend]
SubmitForm --> BackendValidation[Backend validates data]
BackendValidation --> ServerExists{Server path already exists?}
ServerExists -->|Yes| ShowConflictError[Show conflict error]
ServerExists -->|No| CreateServer[Create server entry]
CreateServer --> UpdateFAISS[Update FAISS index]
UpdateFAISS --> UpdateNginx[Regenerate Nginx config]
UpdateNginx --> BroadcastUpdate[Broadcast health update]
BroadcastUpdate --> Success[Redirect to dashboard]
ShowError --> End([End])
ShowValidationErrors --> ShowForm
ShowConflictError --> ShowForm
Success --> End
classDef success fill:#e8f5e8,stroke:#4caf50,stroke-width:2px
classDef error fill:#ffebee,stroke:#f44336,stroke-width:2px
classDef process fill:#e3f2fd,stroke:#2196f3,stroke-width:2px
classDef decision fill:#fff3e0,stroke:#ff9800,stroke-width:2px
class Success success
class ShowError,ShowValidationErrors,ShowConflictError error
class ShowForm,UserFillsForm,SubmitForm,BackendValidation,CreateServer,UpdateFAISS,UpdateNginx,BroadcastUpdate process
class CheckPerms,ValidateForm,ServerExists decision
```
## Authorization & Permissions
### Permission Model Overview
The registry implements a sophisticated role-based access control (RBAC) system with multiple layers of authorization:
```mermaid
graph TB
subgraph "User Identity Layer"
User[User Account]
Groups[User Groups from IdP]
AuthMethod[Authentication Method]
end
subgraph "Permission Mapping Layer"
ScopeMapping[Group → Scope Mapping auth_server/scopes.yml]
Scopes[MCP Scopes]
ServerAccess[Accessible Server List]
end
subgraph "Capability Layer"
ReadAccess[Read Access View servers & tools]
ModifyAccess[Modify Access Toggle, edit servers]
AdminAccess[Admin Access Full system control]
ServerSpecific[Server-Specific Access Fine-grained permissions]
end
subgraph "UI Rendering Layer"
AdminUI[Admin Interface Elements]
ModifyUI[Modification Controls]
ReadOnlyUI[Read-Only Displays]
FilteredContent[Filtered Server Lists]
end
User --> Groups
User --> AuthMethod
Groups --> ScopeMapping
ScopeMapping --> Scopes
Scopes --> ServerAccess
ServerAccess --> ReadAccess
ServerAccess --> ModifyAccess
ServerAccess --> AdminAccess
ServerAccess --> ServerSpecific
ReadAccess --> FilteredContent
ModifyAccess --> ModifyUI
AdminAccess --> AdminUI
ServerSpecific --> FilteredContent
classDef identity fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
classDef mapping fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
classDef capability fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
classDef ui fill:#fff3e0,stroke:#f57c00,stroke-width:2px
class User,Groups,AuthMethod identity
class ScopeMapping,Scopes,ServerAccess mapping
class ReadAccess,ModifyAccess,AdminAccess,ServerSpecific capability
class AdminUI,ModifyUI,ReadOnlyUI,FilteredContent ui
```
### Role Definitions & Capabilities
#### 1. Administrator Role (`mcp-admin` group)
**Full System Access**:
- View, create, edit, and delete all servers
- Access to all MCP tools regardless of server
- System configuration and user management
- Complete audit trail visibility
**Granted Scopes**:
- `mcp-servers-unrestricted/read`
- `mcp-servers-unrestricted/execute`
**UI Capabilities**:
- All server cards visible and interactive
- Edit buttons on all servers
- "Add New Server" functionality
- Toggle switches on all services
- Admin-only configuration panels
#### 2. Regular User Role (`mcp-user` group)
**Limited Read Access**:
- View only servers explicitly assigned to user
- Read-only access to server information
- Cannot modify server configurations
- Cannot toggle server states
**Granted Scopes**:
- `mcp-servers-restricted/read` (limited scope)
**UI Capabilities**:
- Filtered server list (only accessible servers)
- Read-only status indicators instead of toggles
- No edit buttons or admin controls
- Basic server information display
#### 3. Server-Specific Roles (`mcp-server-{name}` groups)
**Targeted Access**:
- Access to specific servers based on group name
- Execute permissions for assigned servers
- May include toggle permissions for specific services
**Example Scopes**:
- `mcp-servers-fininfo/read` + `mcp-servers-fininfo/execute`
- `mcp-servers-currenttime/read` + `mcp-servers-currenttime/execute`
**UI Capabilities**:
- Filtered view showing only assigned servers
- Toggle functionality for assigned servers
- Edit access may be granted for specific servers
### Scope Configuration System
The authorization system uses a YAML-based configuration file (`auth_server/scopes.yml`) to map groups to permissions:
```yaml
# Group to scope mappings
group_mappings:
# Administrator - full access
mcp-admin:
- "mcp-servers-unrestricted/read"
- "mcp-servers-unrestricted/execute"
# Regular user - restricted read-only access
mcp-user:
- "mcp-servers-restricted/read"
# Server-specific access groups
mcp-server-fininfo:
- "mcp-servers-fininfo/read"
- "mcp-servers-fininfo/execute"
mcp-server-currenttime:
- "mcp-servers-currenttime/read"
- "mcp-servers-currenttime/execute"
# Scope definitions with server mappings
mcp-servers-fininfo/read:
- server: "Financial Info Proxy"
permissions: ["read"]
mcp-servers-fininfo/execute:
- server: "Financial Info Proxy"
permissions: ["read", "execute"]
mcp-servers-currenttime/read:
- server: "Current Time API"
permissions: ["read"]
mcp-servers-currenttime/execute:
- server: "Current Time API"
permissions: ["read", "execute"]
# Unrestricted scopes (for admins)
mcp-servers-unrestricted/read:
# Grants access to all servers
mcp-servers-unrestricted/execute:
# Grants execute access to all servers
```
### Permission Checking Implementation
#### Enhanced Authentication Dependency
```python
# registry/auth/dependencies.py
def enhanced_auth(session: str = Cookie(alias="mcp_gateway_session")) -> Dict[str, Any]:
"""Enhanced authentication dependency with full permission context"""
session_data = get_user_session_data(session)
username = session_data['username']
groups = session_data.get('groups', [])
auth_method = session_data.get('auth_method', 'traditional')
logger.info(f"Enhanced auth for {username}: groups={groups}, auth_method={auth_method}")
# Map groups to scopes based on authentication method
if auth_method == 'oauth2':
# OAuth2 users get scopes based on Cognito group mappings
scopes = map_cognito_groups_to_scopes(groups)
logger.info(f"OAuth2 user {username} mapped to scopes: {scopes}")
else:
# Traditional users get admin privileges by default
scopes = ['mcp-servers-unrestricted/read', 'mcp-servers-unrestricted/execute']
if not groups:
groups = ['mcp-admin']
# Calculate accessible servers from scopes
accessible_servers = get_user_accessible_servers(scopes)
# Determine modification permissions
can_modify = user_can_modify_servers(groups, scopes)
# Check for admin privileges
is_admin = 'mcp-admin' in groups
user_context = {
'username': username,
'groups': groups,
'scopes': scopes,
'auth_method': auth_method,
'provider': session_data.get('provider', 'local'),
'accessible_servers': accessible_servers,
'can_modify_servers': can_modify,
'is_admin': is_admin
}
logger.debug(f"Final user context for {username}: {user_context}")
return user_context
```
#### Group to Scope Mapping
```python
# registry/auth/dependencies.py
def map_cognito_groups_to_scopes(groups: List[str]) -> List[str]:
"""Map Cognito groups to MCP scopes using scopes.yml configuration"""
scopes = []
group_mappings = SCOPES_CONFIG.get('group_mappings', {})
for group in groups:
if group in group_mappings:
group_scopes = group_mappings[group]
scopes.extend(group_scopes)
logger.debug(f"Mapped group '{group}' to scopes: {group_scopes}")
else:
logger.debug(f"No scope mapping found for group: {group}")
# Remove duplicates while preserving order
unique_scopes = list(dict.fromkeys(scopes))
logger.info(f"Final mapped scopes: {unique_scopes}")
return unique_scopes
def get_user_accessible_servers(user_scopes: List[str]) -> List[str]:
"""Get list of all servers the user has access to based on their scopes"""
accessible_servers = set()
for scope in user_scopes:
# Check for unrestricted access
if scope in ['mcp-servers-unrestricted/read', 'mcp-servers-unrestricted/execute']:
return ['*'] # Special marker for all servers
# Get servers for specific scopes
server_names = get_servers_for_scope(scope)
accessible_servers.update(server_names)
return list(accessible_servers)
def user_can_modify_servers(user_groups: List[str], user_scopes: List[str]) -> bool:
"""Check if user can modify servers (toggle, edit)"""
# Admin users can always modify
if 'mcp-admin' in user_groups:
return True
# Users with unrestricted execute access can modify
if 'mcp-servers-unrestricted/execute' in user_scopes:
return True
# Check for any execute permissions
execute_scopes = [scope for scope in user_scopes if '/execute' in scope]
return len(execute_scopes) > 0
```
### Server Access Filtering
#### Permission-Based Server Filtering
```python
# registry/services/server_service.py
def get_all_servers_with_permissions(self, accessible_servers: Optional[List[str]] = None) -> Dict[str, Dict[str, Any]]:
"""Get servers filtered by user permissions"""
all_servers = self.get_all_servers()
# Admin users or users with unrestricted access see all servers
if accessible_servers is None or '*' in accessible_servers:
logger.info("User has unrestricted server access")
return all_servers
# Filter servers based on accessible server names
filtered_servers = {}
for path, server_info in all_servers.items():
server_name = server_info.get("server_name", "")
if server_name in accessible_servers:
filtered_servers[path] = server_info
logger.debug(f"Server '{server_name}' accessible to user")
else:
logger.debug(f"Server '{server_name}' filtered out for user")
logger.info(f"Filtered server list: {len(filtered_servers)} of {len(all_servers)} servers accessible")
return filtered_servers
def user_can_access_server_path(self, path: str, accessible_servers: List[str]) -> bool:
"""Check if user can access a specific server path"""
if '*' in accessible_servers:
return True # Unrestricted access
server_info = self.get_server_info(path)
if not server_info:
return False
server_name = server_info.get("server_name", "")
return server_name in accessible_servers
```
### Route-Level Permission Enforcement
#### Protected Route Examples
```python
# registry/api/server_routes.py
@router.get("/", response_class=HTMLResponse)
async def read_root(request: Request,
user_context: Annotated[dict, Depends(enhanced_auth)]):
"""Main dashboard with permission-based server filtering"""
# Filter servers based on user permissions
if user_context['is_admin']:
all_servers = server_service.get_all_servers()
logger.info(f"Admin user accessing all {len(all_servers)} servers")
else:
all_servers = server_service.get_all_servers_with_permissions(
user_context['accessible_servers']
)
logger.info(f"User accessing {len(all_servers)} permitted servers")
# Render dashboard with filtered content
return templates.TemplateResponse("index.html", {
"request": request,
"services": service_data,
"username": user_context['username'],
"user_context": user_context
})
@router.post("/toggle/{service_path:path}")
async def toggle_service_route(service_path: str,
user_context: Annotated[dict, Depends(enhanced_auth)]):
"""Service toggle with multi-level permission checking"""
# Check global modification permission
if not user_context['can_modify_servers']:
logger.warning(f"User {user_context['username']} attempted toggle without modify permissions")
raise HTTPException(status_code=403,
detail="You do not have permission to modify servers")
# For non-admin users, check specific server access
if not user_context['is_admin']:
if not server_service.user_can_access_server_path(
service_path, user_context['accessible_servers']):
logger.warning(f"User {user_context['username']} attempted to access {service_path} without permission")
raise HTTPException(status_code=403,
detail="You do not have access to this server")
# Proceed with toggle operation
return perform_toggle_operation(service_path, user_context)
@router.get("/api/server_details/{service_path:path}")
async def get_server_details(service_path: str,
user_context: Annotated[dict, Depends(enhanced_auth)]):
"""Server details with permission-based filtering"""
# Handle special '/all' endpoint for admins
if service_path == '/all':
if user_context['is_admin']:
return server_service.get_all_servers()
else:
return server_service.get_all_servers_with_permissions(
user_context['accessible_servers']
)
# Check individual server access
server_info = server_service.get_server_info(service_path)
if not server_info:
raise HTTPException(status_code=404, detail="Service not found")
if not user_context['is_admin']:
if not server_service.user_can_access_server_path(
service_path, user_context['accessible_servers']):
raise HTTPException(status_code=403,
detail="Access denied to this server")
return server_info
```
### Permission Validation Flow
```mermaid
flowchart TD
RequestStart([HTTP Request]) --> ExtractSession[Extract Session Cookie]
ExtractSession --> ValidateSession{Session Valid?}
ValidateSession -->|No| Unauthorized[Return 401 Unauthorized]
ValidateSession -->|Yes| ExtractUserContext[Extract User Co
…(truncated)
Registry