github IBM/mcp-context-forge v1.0.0-BETA-2
v1.0.0-BETA-2 - 2026-01-20 - Performance, Scale & Reliability
on GitHub

9 hours ago

This release delivers massive performance improvements, enterprise-scale reliability, and production-hardening with 219 issues resolved.

🏆 Major Achievements

Release 1.0.0-BETA-2 represents a transformational upgrade for production deployments:

  • ⚡ 100+ Performance Optimizations - N+1 query elimination, connection pooling (PgBouncer), caching (L1/L2), Granian HTTP server, orjson serialization
  • 🔧 80+ Bug Fixes - RBAC, pagination, OAuth, Admin UI, multi-tenancy, and MCP protocol compliance
  • 🔐 Security Enhancements - JWT lifecycle management, environment isolation, team membership validation
  • 🏗️ Platform Expansion - ppc64le (IBM POWER) architecture, external PostgreSQL support, Helm improvements
  • 📊 Observability - Prometheus/Grafana monitoring profile, metrics rollup optimization, detailed request logging

Performance Highlights: Under sustained load testing (10,000+ concurrent users), this release achieves 10x+ latency reduction through N+1 query elimination, 50%+ connection reduction via PgBouncer pooling, and 3x+ throughput improvement with Granian HTTP server.

⚠️ Breaking Changes

🐘 PostgreSQL Driver Migration: psycopg2 → psycopg3

Action Required: Update your DATABASE_URL connection string format. 

# OLD (psycopg2) - No longer supported
DATABASE_URL=postgresql://postgres:password@localhost:5432/mcp

# NEW (psycopg3) - Required format
DATABASE_URL=postgresql+psycopg://postgres:password@localhost:5432/mcp

Why this change?

  • psycopg3 provides native async support, better performance, and improved connection handling
  • Eliminates psycopg2-binary dependency issues on ARM64 and Alpine Linux
  • Required for PgBouncer transaction pooling compatibility

Migration steps:

  1. Update DATABASE_URL to use postgresql+psycopg:// prefix
  2. Restart the gateway - no data migration required
  3. For Docker Compose users: Update your .env file or docker-compose.yml

🔌 Federation Auto-Discovery Deprecated

  • Removed DiscoveryService - mDNS/Zeroconf auto-discovery is no longer supported
  • Removed ForwardingService - Functionality consolidated into ToolService
  • Deprecated environment variables: FEDERATION_ENABLED, FEDERATION_DISCOVERY, FEDERATION_PEERS, FEDERATION_SYNC_INTERVAL
  • Retained: FEDERATION_TIMEOUT for gateway request timeouts
  • Unaffected: Gateway peer management via /gateways REST API remains fully functional

✨ Highlights

🛑 Gateway-Orchestrated Tool Cancellation

Real-time cancellation of long-running tool executions

A new cancellation system provides gateway-authoritative control over running tool operations with multi-worker coordination.

Features

  • REST API Endpoints - POST /cancellation/cancel and GET /cancellation/status/{request_id}
  • Real Task Interruption - Actual asyncio task cancellation, not just status marking
  • Multi-Worker Support - Redis pubsub propagates cancellations across all workers
  • Session Broadcasting - notifications/cancelled sent to all connected MCP sessions
  • Zero-Overhead Disable - Set MCPGATEWAY_TOOL_CANCELLATION_ENABLED=false to disable completely 
# Cancel a running tool execution
curl -X POST http://localhost:4444/cancellation/cancel \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"request_id": "abc123", "reason": "User requested cancellation"}'

🚀 Granian HTTP Server

3x+ throughput improvement over Gunicorn

Migrated from Gunicorn to Granian, a high-performance Rust-based HTTP server optimized for async Python.

Benefits

  • Native Async - Purpose-built for ASGI applications
  • Backpressure Handling - Overload protection for high-concurrency scenarios
  • Lower Latency - Reduced per-request overhead
  • Better Resource Utilization - Improved CPU and memory efficiency

🔗 PgBouncer Connection Pooling

50%+ database connection reduction

Built-in PgBouncer support for Docker Compose and Helm deployments provides efficient connection pooling.

Benefits

  • Connection Multiplexing - Fewer database connections under load
  • Transaction Pooling - Connections released after each transaction
  • Idle Connection Management - Automatic cleanup of idle connections
  • Read Replica Support - Horizontal scaling with PostgreSQL replicas

💾 L1/L2 Distributed Cache

Dramatic reduction in database queries

New two-tier caching architecture with in-memory L1 and Redis L2 layers.

Cached Operations

  • JWT verification results
  • Tool lookups by name
  • Team membership queries
  • Global configuration
  • JSON schema validators
  • Jinja templates
  • Crypto key material

📦 orjson Serialization

5-6x faster JSON encoding

Replaced stdlib json with orjson throughout the codebase for significant serialization performance gains.

🆕 Added

🏗️ Platform & Architecture

  • ppc64le (IBM POWER) Support (#2205) - Container images for IBM POWER systems
  • External PostgreSQL Support (#1722, #2052) - CloudNativePG compatible external database hosting
  • Helm extraEnvFrom Support (#2047) - Mount secrets and configmaps as environment variables
  • Full Stack CI/CD (#1148) - Single configuration build and deployment pipeline

🔐 Authentication & Security

  • OAuth 2.0 Browser-Based SSO (#2022) - RFC 9728 compliant OAuth authentication
  • Microsoft EntraID Integration (#2054) - Role and group claim mapping for enterprise SSO
  • Query Parameter Authentication (#2195, #1580) - API key auth via query parameters for A2A agents
  • RFC 8707 OAuth Resource Indicators (#2149) - JWT tokens instead of opaque tokens from OAuth providers
  • Configurable Password Enforcement (#1843) - Control password change requirements

🎛️ Admin UI & Developer Experience

  • Architecture Overview Tab (#1978) - Visual architecture diagram
  • Optimized Table Layouts (#1977) - Reduced horizontal scrolling
  • Tool List/Spec Refresh (#1984) - Polling, API, and list_changed support
  • Gateway Re-discovery (#1910) - Refresh tools for registered gateways
  • Client CLI (#1414) - Command-line interface for gateway operations
  • Virtual Server Tool Naming (#1318) - <server_name>_<tool_name> format
  • Form Field Validation (#1933) - Focus-out validation

📊 Observability & Metrics

  • Execution Metrics Recording Switch (#1804) - DB_METRICS_RECORDING_ENABLED toggle
  • Monitoring Profile (#1844) - Prometheus + Grafana + exporters
  • Audit Trail Toggle (#1743) - AUDIT_TRAIL_ENABLED flag
  • Observability Path Exclusions (#2068) - Restrict tracing to MCP/A2A endpoints

⚡ Resilience & Reliability

  • Database Startup Resilience (#2025) - Exponential backoff with jitter
  • Resilient Session Handling (#1766) - Connection pool exhaustion recovery
  • Session Persistence & Pooling (#975, #1918) - MCP client session pooling
  • MCP _meta Field Propagation (#2094) - Metadata support in tool calls
  • Forced Password Change (#974) - Require default password changes

🧪 Testing & Performance

  • Rust MCP Test Server (#1908) - High-performance test server
  • Performance Test Profiling (#2061) - Guidelines and profiling
  • Locust Load Test Improvements (#1806) - 4000+ concurrent user support

🐛 Fixed

🔐 Authentication & Authorization

  • CORS Preflight on /mcp (#2152) - OPTIONS requests no longer return 401
  • OAuth Opaque Tokens (#2149) - Fixed JWT verification failures
  • JWT Audience Validation (#1792) - Properly disables issuer validation
  • Basic Auth & API Key A2A (#2002) - Fixed A2A agent authentication
  • Non-admin API Tokens (#1501) - Non-admin users can create tokens
  • Password Change Flag (#1842, #1914) - API password change clears flag
  • Login 500 on Password Change (#1653) - Fixed 500 error
  • email_auth HTTPException (#1841) - Router no longer swallows exceptions

👥 Multi-Tenancy & RBAC

  • team_id in RBAC (#2183) - Fixed None for non-admin gateway list
  • HTMX Team Filters (#1966) - Partial endpoints respect team_id
  • A2A Agent Team ID (#1956) - New agents include team ID
  • Tool Visibility (#1582, #1915) - Tools honor gateway visibility
  • Resource Visibility (#1497) - Toggle no longer hides resources
  • Team Add Member (#1644) - Owners can add without permission
  • User Creation is_admin (#1643) - POST /admin/users respects flag
  • team_id Dict Parsing (#1486) - Handle dict in token claims

📊 Admin UI

  • Pagination (#2108) - Fixed broken pagination
  • Show Inactive Toggle (#2080, #2111) - Updates tables correctly
  • Action Buttons Scroll (#2077) - Not hidden by scroll
  • Button Clutter (#2073) - Cleaned up action column
  • Add Server Button (#2072) - Consistent behavior
  • Metrics Tables Readability (#2058) - Improved display
  • Token Usage Stats (#2031) - Fixed null/zero values
  • LLM Chat Server Status (#1707) - Correct status tagging
  • SSE Stream Timeout (#1948) - No more idle timeouts
  • Form Field Focus (#1916) - Required fields don't trap focus
  • Input Cursors (#1463) - Display in text fields
  • Token Validity (#1742) - Respects selected period
  • Chart.js Canvas Reuse (#1788) - Fixed disappearing graphs
  • Resource Fullscreen (#1787) - Mode no longer vanishes
  • initializeSearchInputs (#2121) - Fixed recurrent calls

🔧 MCP Protocol & Tools

  • tools/list Limit (#1937, #1664) - Returns all tools
  • REST Stale Visibility (#2018) - Updates reflected immediately
  • Prompt Namespacing (#1762) - Proper name/ID resolution
  • LLM Settings (#1725) - Provider-specific config support
  • Virtual Server LangChain (#1508) - Fixed tool invocation
  • Claude Desktop Types (#1357) - Fixed invalid type responses
  • Deeply Nested Schemas (#1875) - Tool import works
  • Text Response REST (#1576) - REST API with text responses
  • ExceptionGroup Unwrap (#1902) - Shows root cause
  • A2A Agent Test (#840) - Fixed test functionality

🗄️ Database & Sessions

  • Session State Leakage (#2055) - Pool isolates state between users
  • Entity Parsing Failure (#2172) - Single failure doesn't stop listing
  • Idle-in-Transaction (#1885, #1934) - Fixed stuck connections
  • PgBouncer Timeout (#1877) - Idle timeout errors recognized
  • User Deletion FK (#1663) - Fixed foreign key constraint
  • Transaction Rollbacks (#1108) - Fixed high rollback rate
  • Existing Postgres DB (#1465) - Builds with existing databases
  • Alembic Migrations (#2096) - Fixed incorrect placement

🐳 Deployment & Infrastructure

  • ARM64 Support (#1913, #1581) - Fixed broken compatibility
  • Docker nginx Volume (#2134) - Fixed volume mount conflicts
  • Helm Pod Restart (#1423) - Fixed deployment restarts
  • Docker Start Error (#1526) - Fixed startup errors
  • External Plugin Start (#1633) - Auto-start works
  • DATABASE_URL Encoding (#1533) - Fixed interpolation error
  • PassThrough Headers (#1530) - Env var config works
  • Settings Parsing (#1415) - Fixed Pydantic parsing
  • Native Plugin Issues (#2103) - Fixed several plugins

🌐 Gateway & Federation

  • Gateway Registration (#1047, #1440) - Fixed registration
  • Self-Signed HTTPS (#1539) - Self-signed certificates work
  • Spring MCP OOM (#1549) - Fixed JVM OutOfMemoryError

🔒 Security

  • Environment Isolation Warnings (#2141) - Optional environment claim validation
  • REQUIRE_USER_IN_DB (#2128) - Require users exist in database
  • JWT Lifecycle Management (#2127) - Enhanced token revocation and refresh
  • MCP Team Validation (#2125) - Team membership validation

⚡ Performance

🗄️ Database Query Optimization

🔗 Connection Pooling

  • PgBouncer Integration (#1750, #1753) - Docker Compose and Helm
  • PostgreSQL Read Replicas (#1861) - Horizontal scaling support
  • HTTP Client Pool (#1676, #1897) - Configurable httpx limits
  • DB Connection Exhaustion (#1706) - Sessions released during HTTP calls

💾 Caching

  • L1/L2 Auth Cache (#1881) - Memory before Redis
  • JWT Verification Cache (#1677) - Token verification results
  • Tool Lookup Cache (#1940) - L1 memory + L2 Redis
  • Team Membership Cache (#1773, #1888) - User teams and token scoping
  • GlobalConfig Cache (#1715) - Configuration lookups
  • Jinja Template Cache (#1814) - Compiled templates
  • JSON Schema Cache (#1809) - Validators for tool output

⚡ Transport & Protocol

  • Async I/O (#2164) - Replaced blocking calls
  • SSE Serialization (#1838) - Avoid bytes→str overhead
  • MCP Health Check (#2033, #1691) - Lightweight ping

🔌 Plugin Framework

  • Plugin Manager Init (#2010) - Once per worker, not per request
  • Hook Execution (#1678) - Optimized execution path
  • has_hooks_for (#1777, #1778) - Skip when no hooks registered
  • Memory Optimization (#1608) - Copy-on-write for context state

⚙️ Core Optimizations

  • LRU Cache Eviction (#1614) - O(n) → O(1)
  • Stream Parser Buffer (#1613) - O(n²) → O(n)
  • Performance Tracker (#1610, #1757) - O(n) → O(1)
  • Session Cleanup (#1616) - Parallelized with asyncio.gather()

🔄 Changed

🚀 Server Infrastructure

  • Granian HTTP Server (#1695) - Migrated from Gunicorn
  • Granian Backpressure (#1859) - Overload protection
  • uvicorn[standard] (#1699) - Enhanced with uvloop and httptools
  • Nginx Optimization (#1768, #1719) - High-concurrency proxy

📦 JSON Serialization

  • orjson Migration (#2113, #1696, #2030) - Replaced stdlib json
  • ORJSONResponse (#1692) - Default response class

⚡ Metrics Performance Defaults

  • Raw metrics now deleted after hourly rollups exist (1 hour retention)
  • METRICS_DELETE_RAW_AFTER_ROLLUP: false → true
  • METRICS_DELETE_RAW_AFTER_ROLLUP_HOURS: 168 → 1
  • METRICS_RETENTION_DAYS: 30 → 7
  • Set METRICS_DELETE_RAW_AFTER_ROLLUP=false to preserve previous behavior

🔄 Redis & Caching

  • Hiredis Parser (#1702) - Default Redis parser
  • Async Redis Client (#1661) - Shared async factory
  • Distributed Cache (#1680) - L1 + L2 layers

📦 Migration Guide

From v1.0.0-BETA-1 to v1.0.0-BETA-2

Database migrations run automatically on startup. Backup recommended before upgrading.

1. Update DATABASE_URL (Required for PostgreSQL)

# Update connection string format
# OLD: postgresql://postgres:password@localhost:5432/mcp
# NEW: postgresql+psycopg://postgres:password@localhost:5432/mcp

2. Update Docker Compose

# Backup database
docker compose exec postgres pg_dump -U postgres mcp > backup.sql

# Pull new image
docker pull ghcr.io/ibm/mcp-context-forge:1.0.0-BETA-2

# Start - migrations run automatically
docker compose up -d

3. New Environment Variables

# Tool cancellation (enabled by default)
MCPGATEWAY_TOOL_CANCELLATION_ENABLED=true

# Metrics recording (enabled by default)
DB_METRICS_RECORDING_ENABLED=true

# Audit trail (enabled by default)
AUDIT_TRAIL_ENABLED=true

# Require users exist in database (optional)
REQUIRE_USER_IN_DB=false

4. Removed Environment Variables

# These are no longer used
FEDERATION_ENABLED
FEDERATION_DISCOVERY
FEDERATION_PEERS
FEDERATION_SYNC_INTERVAL

📋 Issues Closed

Total: 219 issues resolved

Platform & Architecture (5 issues)

  • #2205 - ppc64le (IBM POWER) architecture support
  • #1722, #2052 - External PostgreSQL support
  • #2047 - Helm extraEnvFrom support
  • #1148 - Full stack CI/CD pipeline

Authentication & Security (9 issues)

Performance (60+ issues)

Bug Fixes (80+ issues)

🔗 Resources

Documentation

Source Code

ContextForge Ecosystem

Container Images

Community

Quick Start

# Pull the latest image (auto-selects architecture)
docker pull ghcr.io/ibm/mcp-context-forge:1.0.0-BETA-2

# Run with minimal configuration
docker run -d --name mcpgateway \
  -p 4444:4444 \
  -e PLATFORM_ADMIN_EMAIL=admin@example.com \
  -e PLATFORM_ADMIN_PASSWORD=changeme \
  ghcr.io/ibm/mcp-context-forge:1.0.0-BETA-2

# Access Admin UI
open http://localhost:4444/admin

Next Planned Release: v1.0.0 GA (Q1 2026) - Production-ready release

Check out latest releases or
releases around IBM/mcp-context-forge v1.0.0-BETA-2

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

NewReleases is sending notifications on new releases.

Get notifications