MCP Gateway v0.7.0 - 2025-09-16 - Enterprise Multi-Tenancy, RBAC, Teams, SSO

This release delivers 50+ resolved issues and represents a fundamental architectural transformation of MCP Gateway from a single-tenant system into a multi-tenant platform with comprehensive team-based resource scoping, enterprise SSO integration, and advanced database support.

🏆 Enterprise Multi-Tenancy & Security Achievements

This release implements [EPIC [#860]]: Complete Enterprise Multi-Tenancy System with Team-Based Resource Scoping, transforming MCP Gateway into a true enterprise platform (Architecture Guide) with:

• 🔐 Complete Authentication System – Email-based authentication with Argon2id password hashing replacing basic auth
• 👥 Multi-Tenant Team Management – Full team lifecycle with personal teams, invitations, and role-based access control
• 🔒 Three-Tier Resource Visibility – Private/Team/Public resource scoping across all entity types
• 🌐 Multi-Provider SSO Framework – GitHub, Google, and IBM Security Verify integration with domain trust
• 🗄️ Enhanced Database Support – Complete MariaDB and MySQL production support alongside PostgreSQL and SQLite
• 🔑 Advanced JWT Security – Asymmetric algorithms (RSA, ECDSA) with audience verification and dynamic client registration
• ⚡ Performance Optimizations – Database connection pooling configuration for multi-tenant workloads

✨ Highlights

• 🔐 Email Authentication System – Complete user authentication with Argon2id password hashing and configurable password policies (#544, [#426])
• 👥 Complete RBAC & Team System – Platform Admin, Team Owner, Team Member roles with comprehensive multi-tenancy (#283, [#860])
• 🌐 Multi-Provider SSO Integration – GitHub, Google, and IBM Security Verify with enterprise domain trust (#220, [#278], [#859])
• 🔑 Asymmetric JWT Support – RSA and ECDSA algorithms with enterprise security features and audience verification
• 🗄️ MariaDB & MySQL Support – Complete production support for MySQL-compatible databases with all features (#925)
• 🔒 Per-Virtual-Server API Keys – Scoped access tokens for individual virtual servers with team context (#282)
• 📊 Enhanced Database Schema – Multi-tenant optimized with proper indexing and performance considerations

🚨 Important Migration Notice

• Major Database Migration – This release requires database schema migration from single-tenant to multi-tenant
• Authentication Changes – Migration from username to email-based authentication system
• Configuration Updates – New environment variables required for multi-tenancy features
• Complete Migration Guide – See MIGRATION-0.7.0.md for detailed upgrade instructions

🆕 Added

🔐 Authentication & Authorization System

• Email-based User Authentication (#544) – Complete replacement of basic auth with email/password system using Argon2id hashing
• Complete RBAC Implementation (#283) – Platform Admin, Team Owner, Team Member roles with full permission system
• Enhanced JWT Token System (#87) – JWT tokens with team context, scoped permissions, and per-user expiry management
• Asymmetric JWT Algorithm Support – Complete support for enterprise security: ```bash # Multiple algorithm support: JWT_ALGORITHM=HS256 # HMAC (existing, default) JWT_ALGORITHM=RS256 # RSA public/private key JWT_ALGORITHM=ES256 # ECDSA public/private key

# Enterprise features: JWT_AUDIENCE=mcpgateway-api # Audience claim validation JWT_ISSUER=mcpgateway # Issuer claim validation * **Password Policy Engine** (#426) – Configurable security requirements with complexity rules:bash PASSWORD_MIN_LENGTH=8 PASSWORD_REQUIRE_UPPERCASE=false PASSWORD_REQUIRE_LOWERCASE=false PASSWORD_REQUIRE_NUMBERS=false PASSWORD_REQUIRE_SPECIAL=false * **Account Security Features** – Failed login attempt limits and account lockout policies:bash MAX_FAILED_LOGIN_ATTEMPTS=5 ACCOUNT_LOCKOUT_DURATION_MINUTES=30 ``` * Password Change API – Secure endpoint for changing user passwords with old password verification

👥 Team Management System

• Personal Teams Auto-Creation – Every user automatically receives a personal team on registration
• Multi-Team Membership – Users can belong to multiple teams with different roles (owner/member)
• Team Invitation System – Email-based invitations with secure tokens and configurable expiration: bash INVITATION_EXPIRY_DAYS=7 REQUIRE_EMAIL_VERIFICATION_FOR_INVITES=true
• Team Visibility Controls – Private/Public team discovery enabling cross-team collaboration
• Team Administration API – Complete CRUD operations for teams, memberships, and invitations
• Team Limits Configuration: bash MAX_TEAMS_PER_USER=50 MAX_MEMBERS_PER_TEAM=100

🔒 Resource Scoping & Visibility

• Three-Tier Visibility System applied to all resource types:
• Private: Owner-only access for sensitive resources
• Team: Team member access for collaborative work
• Public: Cross-team access for organization-wide sharing
• Comprehensive Resource Coverage – Tools, Servers, Resources, Prompts, A2A Agents all support visibility scoping
• Team-Scoped API Endpoints – All APIs enhanced with proper access validation and team-based filtering
• Cross-Team Resource Discovery – Public resources discoverable across teams for collaboration

🌐 Multi-Provider SSO Framework

• GitHub OAuth Integration (#278) – Complete GitHub SSO with organization support (Tutorial): bash SSO_GITHUB_ENABLED=true SSO_GITHUB_CLIENT_ID=your-github-client-id SSO_GITHUB_CLIENT_SECRET=your-github-client-secret
• Google OAuth Integration (#278) – Google Workspace and personal account support (Tutorial): bash SSO_GOOGLE_ENABLED=true SSO_GOOGLE_CLIENT_ID=your-google-client-id.googleusercontent.com SSO_GOOGLE_CLIENT_SECRET=your-google-client-secret
• IBM Security Verify Integration (#859) – Enterprise OIDC integration (Tutorial): bash SSO_IBM_VERIFY_ENABLED=true SSO_IBM_VERIFY_CLIENT_ID=your-ibm-verify-client-id SSO_IBM_VERIFY_CLIENT_SECRET=your-ibm-verify-client-secret SSO_IBM_VERIFY_ISSUER=https://your-tenant.verify.ibm.com/oidc/endpoint/default
• Okta OIDC Integration – Enterprise identity provider support (Tutorial): bash SSO_OKTA_ENABLED=true SSO_OKTA_CLIENT_ID=your-okta-client-id SSO_OKTA_CLIENT_SECRET=your-okta-client-secret SSO_OKTA_ISSUER=https://your-okta-domain.okta.com
• Enterprise Domain Features: bash SSO_TRUSTED_DOMAINS=[] # JSON array of trusted email domains SSO_AUTO_ADMIN_DOMAINS=[] # Email domains for auto admin privileges SSO_GITHUB_ADMIN_ORGS=[] # GitHub orgs for admin privileges SSO_GOOGLE_ADMIN_DOMAINS=[] # Google Workspace domains for admin SSO_AUTO_CREATE_USERS=true # Auto-create users on first SSO login SSO_PRESERVE_ADMIN_AUTH=true # Keep local admin auth when SSO enabled SSO_REQUIRE_ADMIN_APPROVAL=false # Require admin approval for new users

🏗️ Platform Administration

• Platform Admin Role – System-wide management capabilities separate from team roles
• Domain-Based Auto-Assignment – Automatic platform admin assignment via SSO domain configuration
• Enterprise Domain Trust – Controlled access via trusted domain configuration
• System-Wide Team Management – Administrative oversight of all teams and memberships

🗄️ Enhanced Database Support

• Complete MariaDB Support (#925) – Full production support for MariaDB 12.0+ with all MCP Gateway features: bash # MariaDB configuration: DATABASE_URL=mysql+pymysql://mysql:changeme@localhost:3306/mcp
• Complete MySQL Support (#925) – Full production support for MySQL 8.4+ with feature parity: bash # MySQL configuration: DATABASE_URL=mysql+pymysql://mysql:changeme@localhost:3306/mcp
• Database Connection Pool Configuration – Optimized settings for multi-tenant workloads: bash DB_POOL_SIZE=200 # Maximum persistent connections (optimized for SQLite) DB_MAX_OVERFLOW=5 # Additional connections beyond pool_size (reduced for SQLite) DB_POOL_TIMEOUT=60 # Seconds to wait for connection (increased for reliability) DB_POOL_RECYCLE=3600 # Seconds before recreating connection DB_MAX_RETRIES=5 # Maximum database retry attempts (increased for stability) DB_RETRY_INTERVAL_MS=2000 # Retry interval in milliseconds
• 36+ Database Tables – All tables fully compatible with MariaDB, MySQL, PostgreSQL, and SQLite
• Resolved VARCHAR Issues – All MySQL compatibility issues resolved for production deployments

🔑 Per-Virtual-Server API Keys

• Scoped API Tokens (#282) – Individual API keys for each virtual server with team context
• Token Usage Tracking – Comprehensive logging and monitoring of API token usage
• Token Revocation System – Secure token lifecycle management with revocation capabilities
• Team-Scoped Permissions – API tokens inherit team permissions and visibility rules

🔄 Changed

🔄 Authentication Migration

• Username to Email Migration – All authentication now uses email addresses: ```bash # OLD (v0.6.0 and earlier): python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 10080

# NEW (v0.7.0+): python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 ``` * JWT Token Format Enhanced – Tokens now include team context, user roles, and scoped permissions * API Authentication Updated – All documentation and examples updated for email-based authentication

📊 Database Schema Evolution

• New Multi-Tenant Tables – email_users, email_teams, email_team_members, email_team_invitations
• Enhanced Token Management – email_api_tokens, token_usage_logs, token_revocations for complete lifecycle tracking
• Extended Resource Tables – All resource tables include team_id, owner_email, visibility columns
• Performance Indexing – Strategic indexes on team_id, owner_email, visibility for optimal query performance
• Migration Scripts – Automated Alembic migrations with rollback support and verification

🚀 API Enhancements

• New Authentication Endpoints – Complete email registration, login, and password management APIs
• New Team Management Endpoints – Full CRUD operations for teams, memberships, and invitations
• Enhanced Resource Endpoints – All resource endpoints support team-scoping and visibility parameters
• New SSO Endpoints – OAuth callback handlers for GitHub, Google, and IBM Security Verify
• Backward Compatibility – Existing API endpoints remain functional with progressive enhancement

🐛 Fixed

🚨 Critical Multi-Tenancy Fixes

• Backend Multi-Tenancy Issues (#969) – Fixed critical bugs in team-based resource scoping and visibility implementation
• UI Multi-Tenancy Gaps (#967) – Added missing visibility fields and team selection throughout Admin UI
• Team Selection Implementation (#955) – Fixed team selection not properly tagging and loading resources
• Incomplete Visibility Implementation (#958) – Completed visibility system across all resource types

🔧 Authentication & Security Fixes

• OAuth MCP Server Tool Invocation (#949) – Fixed tool invocation failures for OAuth2-authenticated MCP servers
• OAuth2 Server Status Display (#948) – Fixed OAuth2 authenticated servers showing as offline after addition
• JWT Token Scoping (#941) – Fixed access token scoping issues with proper team context
• DateTime UTC Issues (#942) – Fixed UTC datetime handling across authentication and team systems

🖥️ UI/UX Improvements

• Metadata Field Population (#954) – Fixed metadata fields not being populated in resource views
• Server Creation UUID Handling (#844, [#820]) – Fixed UUID format issues in server creation and editing
• Tool Configuration Updates (#834) – Fixed existing tool configurations not updating after MCP server changes
• Global Tools Synchronization (#831) – Fixed newly added/deleted tools not reflecting in Global Tools tab

🔄 Infrastructure & Performance

• Sleep Jitter Method Call (#822) – Fixed incorrect method call in connection retry logic
• Container Base Image Migration (#928) – Migrated from UBI9 to UBI10 and Python 3.11 to 3.12
• Helm Kubernetes Version Support (#931) – Fixed Helm install issues with vendor-specific Kubernetes version suffixes

🔒 Security Enhancements

• Data Isolation – Complete team-scoped queries prevent cross-tenant data access
• Resource Ownership Validation – Every resource has verified owner_email and team_id
• Visibility Enforcement – Private/Team/Public visibility strictly enforced at database and API levels
• Secure Token Management – Invitation tokens with expiration, single-use validation, and secure storage
• Domain Restrictions – Corporate domain enforcement via SSO_TRUSTED_DOMAINS configuration
• MFA Support – Automatic enforcement of SSO provider MFA policies
• Argon2id Password Hashing – Industry-standard password hashing with configurable parameters

📚 Documentation

• Complete SSO Integration Tutorials:
• SSO Configuration Guide – General SSO configuration and best practices
• GitHub OAuth Tutorial – Step-by-step GitHub OAuth setup
• Google OAuth Tutorial – Google Workspace and personal account configuration
• IBM Security Verify Tutorial – Enterprise IBM Security Verify OIDC integration
• Okta Tutorial – Okta OIDC provider configuration
• Architecture Documentation:
• Multi-Tenancy Architecture – Complete multi-tenant system design and implementation
• OAuth Design – OAuth2 architecture and security considerations
• Migration Documentation – MIGRATION-0.7.0.md with complete upgrade instructions
• Configuration Reference – Comprehensive environment variable documentation in .env.example
• API Reference Updates – Team-scoped endpoint documentation with examples

📦 Migration Guide

⚠️ Pre-Migration Requirements

IMPORTANT: This is a major architectural change requiring database migration and configuration updates.

1. Backup Everything: ```bash # Backup database cp mcp.db mcp.db.backup.$(date +%Y%m%d_%H%M%S)

# Backup configuration cp .env .env.bak ```

1. Review Breaking Changes:
2. Database schema changes (automatically migrated)
3. Email-based authentication (manual token generation updates required)
4. New configuration variables (required for multi-tenancy)

📋 Environment Configuration Updates

Update your .env file with new multi-tenancy settings:

:::bash
#####################################
# Email-Based Authentication
#####################################

# Enable email-based authentication system
EMAIL_AUTH_ENABLED=true

# Platform admin user (bootstrap from environment)
PLATFORM_ADMIN_EMAIL=admin@example.com
PLATFORM_ADMIN_PASSWORD=changeme
PLATFORM_ADMIN_FULL_NAME=Platform Administrator

# Argon2id Password Hashing Configuration
ARGON2ID_TIME_COST=3
ARGON2ID_MEMORY_COST=65536
ARGON2ID_PARALLELISM=1

# Password Policy Configuration
PASSWORD_MIN_LENGTH=8
PASSWORD_REQUIRE_UPPERCASE=false
PASSWORD_REQUIRE_LOWERCASE=false
PASSWORD_REQUIRE_NUMBERS=false
PASSWORD_REQUIRE_SPECIAL=false

# Account Security
MAX_FAILED_LOGIN_ATTEMPTS=5
ACCOUNT_LOCKOUT_DURATION_MINUTES=30

#####################################
# Team Management
#####################################

# Enable automatic personal team creation for new users
AUTO_CREATE_PERSONAL_TEAMS=true

# Personal team naming prefix
PERSONAL_TEAM_PREFIX=personal

# Team Limits
MAX_TEAMS_PER_USER=50
MAX_MEMBERS_PER_TEAM=100

# Team Invitation Settings
INVITATION_EXPIRY_DAYS=7
REQUIRE_EMAIL_VERIFICATION_FOR_INVITES=true

#####################################
# Database Configuration (Optional)
#####################################

# Enhanced connection pooling for multi-tenant workloads
DB_POOL_SIZE=200             # Maximum persistent connections (optimized for SQLite)
DB_MAX_OVERFLOW=5            # Additional connections beyond pool_size (reduced for SQLite)
DB_POOL_TIMEOUT=60           # Seconds to wait for connection (increased for reliability)
DB_POOL_RECYCLE=3600         # Seconds before recreating connection
DB_MAX_RETRIES=5             # Maximum database retry attempts (increased for stability)
DB_RETRY_INTERVAL_MS=2000    # Retry interval in milliseconds

# MariaDB/MySQL Support (if migrating from SQLite/PostgreSQL)
# DATABASE_URL=mysql+pymysql://mysql:changeme@localhost:3306/mcp

#####################################
# SSO Configuration (Optional)
#####################################

# Master SSO switch
SSO_ENABLED=false

# GitHub OAuth
SSO_GITHUB_ENABLED=false
# SSO_GITHUB_CLIENT_ID=your-github-client-id
# SSO_GITHUB_CLIENT_SECRET=your-github-client-secret

# Google OAuth
SSO_GOOGLE_ENABLED=false
# SSO_GOOGLE_CLIENT_ID=your-google-client-id.googleusercontent.com
# SSO_GOOGLE_CLIENT_SECRET=your-google-client-secret

# IBM Security Verify OIDC
SSO_IBM_VERIFY_ENABLED=false
# SSO_IBM_VERIFY_CLIENT_ID=your-ibm-verify-client-id
# SSO_IBM_VERIFY_CLIENT_SECRET=your-ibm-verify-client-secret
# SSO_IBM_VERIFY_ISSUER=https://your-tenant.verify.ibm.com/oidc/endpoint/default

# Okta OIDC
SSO_OKTA_ENABLED=false
# SSO_OKTA_CLIENT_ID=your-okta-client-id
# SSO_OKTA_CLIENT_SECRET=your-okta-client-secret
# SSO_OKTA_ISSUER=https://your-okta-domain.okta.com

# SSO General Settings
SSO_AUTO_CREATE_USERS=true
SSO_PRESERVE_ADMIN_AUTH=true
SSO_REQUIRE_ADMIN_APPROVAL=false

# Enterprise Domain Configuration
# SSO_TRUSTED_DOMAINS=[]
# SSO_AUTO_ADMIN_DOMAINS=[]
# SSO_GITHUB_ADMIN_ORGS=[]
# SSO_GOOGLE_ADMIN_DOMAINS=[]

#####################################
# JWT Configuration Updates
#####################################

# Enhanced JWT configuration with audience and issuer
JWT_AUDIENCE=mcpgateway-api
JWT_ISSUER=mcpgateway

# Asymmetric JWT algorithms (optional, for enterprise deployments)
# JWT_ALGORITHM=RS256  # For RSA public/private key
# JWT_ALGORITHM=ES256  # For ECDSA public/private key

🔄 Database Migration

Migrations run automatically on startup:

:::bash
# Start development server (migrations run automatically)
make dev

# Or for production
make serve

# Verify migration success
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     http://127.0.0.1:4444/version | jq

🔑 JWT Token Generation Updates

Update token generation to use email addresses:

:::bash
# Generate development tokens (NEW FORMAT)
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
    --username admin@example.com --exp 10080 --secret my-test-key)

# Test API access
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     http://127.0.0.1:4444/version | jq

🔐 Post-Migration Security

1. Change Platform Admin Password: bash # Use the password change API after migration curl -X POST http://127.0.0.1:4444/auth/email/change-password \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ -d '{"old_password": "changeme", "new_password": "your-secure-password"}'

2. Configure SSO (if desired) using the tutorials in documentation

3. Set up Teams and invite users via the Admin UI or API

📖 Complete Migration Resources

• MIGRATION-0.7.0.md – Detailed step-by-step upgrade guide with troubleshooting
• Multi-Tenancy Architecture – Understanding the new system design
• SSO Configuration Guide – Setting up enterprise authentication

🚨 Breaking Changes

• Database Schema – New multi-tenant tables and extended resource tables (automatically migrated)
• Authentication System – Migration from username to email-based authentication:
• Action Required: Update JWT token generation to use email addresses
• Action Required: Update .env with new authentication configuration
• API Changes – New endpoints added, existing endpoints enhanced with team parameters:
• Backward Compatible: Existing endpoints work with new team-scoping parameters
• Configuration – New required environment variables for multi-tenancy:
• Action Required: Copy updated .env.example and configure multi-tenancy settings

📋 Issues Closed

Primary Epic: - Closes [#860] - [EPIC]: Complete Enterprise Multi-Tenancy System with Team-Based Resource Scoping

Core Security & Authentication: - Closes [#544] - Database-Backed User Authentication with Argon2id (replace BASIC auth) - Closes [#283] - Role-Based Access Control (RBAC) - User/Team/Global Scopes for full multi-tenancy support - Closes [#426] - Configurable Password and Secret Policy Engine - Closes [#87] - Epic: Secure JWT Token Catalog with Per-User Expiry and Revocation - Closes [#282] - Per-Virtual-Server API Keys with Scoped Access

SSO Integration: - Closes [#220] - Authentication & Authorization - SSO + Identity-Provider Integration - Closes [#278] - Authentication & Authorization - Google SSO Integration Tutorial - Closes [#859] - Authentication & Authorization - IBM Security Verify Enterprise SSO Integration

Database & Infrastructure: - Closes [#925] - Add MySQL database support to MCP Gateway - Closes [#928] - Migrate container base images from UBI9 to UBI10 and Python from 3.11 to 3.12

Multi-Tenancy Implementation: - Closes [#969] - Backend Multi-Tenancy Issues - Critical bugs and missing features - Closes [#967] - UI Gaps in Multi-Tenancy Support - Visibility fields missing for most resource types - Closes [#958] - Incomplete Visibility Implementation - Closes [#955] - Team Selection implementation not tagging or loading added servers, tools, gateways

Bug Fixes & Improvements: - Closes [#949] - Tool invocation for an MCP server authorized by OAUTH2 fails - Closes [#948] - MCP OAUTH2 authenticate server is shown as offline after is added - Closes [#946] - Alembic migrations fails in docker compose setup - Closes [#942] - DateTime UTC Fixes Required - Closes [#941] - Access Token scoping not working - Closes [#931] - Helm install does not work when kubeVersion has vendor specific suffix - Closes [#844] - Creating a new virtual server with a custom UUID, removes the hyphens from the UUID field - Closes [#834] - Existing tool configurations are not updating after changes to the MCP server configuration - Closes [#831] - Newly added or deleted tools are not reflected in Global Tools tab after server reactivation - Closes [#822] - Incorrect _sleep_with_jitter Method Call - Closes [#820] - Unable to create a new server with custom UUID - Closes [#570] - Word wrap in codemirror - Closes [#491] - UI Keyboard shortcuts

Development & Documentation: - Closes [#589] - Sample MCP Server - Python PowerPoint Editor (python-pptx) - Closes [#986] - Plugin Request: Implement Argument Normalizer Plugin (Native) - Closes [#323] - Add Developer Guide for using fast-time-server via JSON-RPC commands using curl or stdio - Closes [#19] - Add Developer Guide for using MCP via the CLI (curl commands, JSON-RPC)

---

🌟 Release Contributors

This release represents the largest architectural transformation in MCP Gateway's history, implementing comprehensive enterprise multi-tenancy with the largest contributor base to date!

🏆 Top Contributors in 0.7.0

• Mihai Criveti (@crivetimihai) - Release coordination, multi-tenancy architecture design, SSO framework implementation, database migration system, RBAC implementation, team management system, database schema evolution, multi-tenant query optimization and comprehensive testing infrastructure
• Madhav Kandukuri (@madhav165) - RBAC updates and fixes, testing coordination and UI fixes
• Keval Mahajan (@kevalmahajan) - Authentication system fixes, JWT enhancements, password policies, and security validation framework

🎉 New Contributors

Welcome to our growing community of first-time contributors who joined us in 0.7.0:

• Philip Miglinci @pmig added support for JWT asymmetric jwt encoding and decoding [#973] to support dynamic client registration - and added and End-to-End Example on how to use Contextforge with HyprMCP to support MCP client OAuth & DCR with the Context7 MCP server [#1029]

---

🔗 Resources

• 📚 Docs: https://ibm.github.io/mcp-context-forge/
• 🐳 Container: ghcr.io/ibm/mcp-context-forge:v0.7.0
• 🐍 PyPI: mcp-contextforge-gateway
• 📈 Full changelog: Compare v0.6.0…v0.7.0
• 📋 Migration Guide: MIGRATION-0.7.0.md

Enterprise Software Notice: MCP Gateway v0.7.0 introduces enterprise multi-tenancy. While the core platform is stable, new enterprise features may evolve. Please refer to SECURITY.md and our Roadmap for more info.