Multi Agent Orchestrator MCP

# Descope OAuth 2.1 + PKCE Configuration Guide ## Current Configuration Status ### ✅ Already Configured - **OAuth 2.1 + PKCE Implementation**: Complete implementation in `src/core/descope_auth.py` - **Non-Human Identity Support**: Access key exchange for machine-to-machine authentication - **JWT Token Validation**: RS256 algorithm with proper claims validation - **Demo Mode**: Fallback authentication for development/testing - **Security Features**: Token caching, expiration validation, scope checking ### 🔧 Configuration Updates Needed Based on the current codebase analysis, here are the key configuration updates needed for production deployment: ## 1. Environment Variables (.env file) ```bash # === DESCOPE AUTHENTICATION === # Replace these with your actual Descope project values # Core Descope Settings DESCOPE_PROJECT_ID=your_actual_project_id_here # Currently: "test_project" DESCOPE_MANAGEMENT_KEY=your_management_key_here # Currently: None DESCOPE_CLIENT_ID=your_client_id_here # Currently: None DESCOPE_CLIENT_SECRET=your_client_secret_here # Currently: None # Production Settings DESCOPE_DEMO_MODE=false # Currently: true (CHANGE TO FALSE FOR PRODUCTION) # JWT Configuration JWT_ALGORITHM=RS256 # ✅ Correct JWT_VERIFY_EXPIRATION=true # ✅ Correct JWT_REQUIRE_CLAIMS=["exp", "iat", "sub", "aud"] # ✅ Correct # Security Settings TOKEN_CACHE_TTL=3600 # ✅ 1 hour cache (good for production) MAX_TOKEN_AGE_HOURS=24 # ✅ 24 hour max age ENABLE_TOKEN_REFRESH=true # ✅ Auto refresh enabled # Rate Limiting & Security RATE_LIMIT_PER_MINUTE=100 # ✅ Reasonable for production MAX_REQUEST_SIZE_MB=10 # ✅ Good security limit ``` ## 2. Descope Dashboard Configuration ### Required Descope Project Settings: #### A. OAuth 2.1 Application Configuration - **Application Type**: `Web Application` or `Machine-to-Machine` - **OAuth Flow**: `Authorization Code with PKCE` - **Redirect URIs**: - `https://server.smithery.ai/@yoriichi-07/multi_orchestrator_mcp/auth/callback` - `http://localhost:8080/auth/callback` (for local development) - **Allowed Grant Types**: - `authorization_code` - `refresh_token` - `client_credentials` (for machine-to-machine) #### B. Scopes Configuration Define these custom scopes in Descope: ``` legendary:architect # Autonomous architecture generation legendary:quality # Proactive quality assurance legendary:prompts # Evolutionary prompt optimization legendary:cloud # Last mile cloud deployment legendary:generate # Complete application generation tools:ping # Basic connectivity testing tools:orchestrate # Task orchestration tools:review # Code review capabilities tools:fix # Self-healing and fixing tools:deploy # Deployment management admin:logs # Access to system logs admin:config # Configuration management ``` #### C. Non-Human Identity Configuration - **Enable Access Keys**: `true` - **Access Key Permissions**: Include all legendary and tools scopes - **Token Lifetime**: `24 hours` (matches MAX_TOKEN_AGE_HOURS) - **Refresh Token Enabled**: `true` #### D. Security Settings - **Require PKCE**: `true` (essential for OAuth 2.1) - **Token Signing Algorithm**: `RS256` - **Token Validation**: - Verify expiration: `true` - Verify audience: `true` - Verify issuer: `true` - **CORS Settings**: Allow origins for Smithery and local development ## 3. Integration Steps ### Step 1: Create Descope Application 1. Go to Descope Console → Applications 2. Create new application: "Multi-Agent Orchestrator MCP" 3. Configure OAuth 2.1 settings as specified above ### Step 2: Generate Access Keys 1. Go to Access Keys section 2. Create new access key for machine authentication 3. Copy the access key for environment variables ### Step 3: Configure Scopes 1. Go to Authorization → Scopes 2. Create all legendary and tools scopes 3. Assign scopes to the application ### Step 4: Update Environment Variables 1. Update `.env` file with actual Descope values 2. Set `DESCOPE_DEMO_MODE=false` 3. Add access key for machine authentication ## 4. Testing Authentication ### Test Commands: ```bash # Test with demo mode (current) curl -X POST http://localhost:8080/tools/ping \ -H "Authorization: Bearer demo_token_12345" \ -H "Content-Type: application/json" \ -d '{"message": "test"}' # Test with real Descope token (after configuration) curl -X POST http://localhost:8080/tools/ping \ -H "Authorization: Bearer YOUR_REAL_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{"message": "test"}' ``` ## 5. Smithery Deployment Configuration For Smithery deployment, ensure these environment variables are set in the deployment: ```yaml # smithery.yaml or deployment config environment: DESCOPE_PROJECT_ID: "your_project_id" DESCOPE_DEMO_MODE: "false" # Other sensitive values should be set via Smithery secrets ``` ## 6. Verification Checklist - [ ] Descope project created with OAuth 2.1 + PKCE - [ ] Custom scopes defined for legendary tools - [ ] Access keys generated for machine authentication - [ ] Environment variables updated in production - [ ] Demo mode disabled (`DESCOPE_DEMO_MODE=false`) - [ ] Authentication testing completed - [ ] CORS configured for allowed origins - [ ] Token validation working with real JWT tokens ## 7. Troubleshooting Common Issues ### Issue: "Invalid token audience" - **Solution**: Ensure `DESCOPE_PROJECT_ID` matches the audience in JWT ### Issue: "Public key not found" - **Solution**: Verify JWKS endpoint is accessible and kid matches ### Issue: "Token has expired" - **Solution**: Check token lifetime settings and refresh token flow ### Issue: "Scope validation failed" - **Solution**: Verify scopes are correctly defined in Descope and included in token ## 8. Security Best Practices - Use HTTPS for all production endpoints - Store sensitive keys in secure environment variables - Enable rate limiting and request size limits - Regularly rotate access keys - Monitor authentication logs for suspicious activity - Use least privilege principle for scope assignments --- **Note**: Since screenshots were mentioned but not provided, this configuration is based on the current codebase analysis and Descope best practices. Please provide screenshots for more specific configuration guidance.