github IBM/mcp-context-forge v0.7.0
v0.7.0 - 2025-09-16 - Enterprise Multi-Tenancy, RBAC, Teams, SSO
on GitHub

latest release: v0.8.0
one month ago

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: 
    # 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: 
    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: 
    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: 
    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: 
    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): 
    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): 
    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): 
    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): 
    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: 
    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: 
    # 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: 
    # MySQL configuration:
DATABASE_URL=mysql+pymysql://mysql:changeme@localhost:3306/mcp
  • Database Connection Pool Configuration – Optimized settings 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
  • 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: 
    # 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:
  • Architecture Documentation:
  • 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: 

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

# Backup configuration
cp .env .env.bak

  2. Review Breaking Changes:

    • Database schema changes (automatically migrated)
    • Email-based authentication (manual token generation updates required)
    • New configuration variables (required for multi-tenancy)

📋 Environment Configuration Updates

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

#####################################
# 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: 

# 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: 

# 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: 

    # 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

🚹 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

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.

Check out latest releases or
releases around IBM/mcp-context-forge v0.7.0

Don't miss a new mcp-context-forge release

NewReleases is sending notifications on new releases.

Get notifications