Seed MCP Server

Appearance

Implemented Enhancements ​

This page documents all production-ready features that have been successfully implemented in Seed MCP Server.

Production Status ​

🎉 Seed is Production-Ready! (2026-01-07)

All 7 high-priority production-readiness features plus 8 medium-priority enhancements have been implemented, making Seed suitable for enterprise deployments with comprehensive operational features, error handling, and monitoring capabilities.

Implementation metrics:

  • Total effort: 45.5-55.5 hours
  • Test coverage: 771 tests passing (93.02% coverage)
  • All features thoroughly tested and documented

Authentication & Session Management ​

Automatic Token Refresh ​

FeatureStatusDocumentationTime
Automatic Token Refresh✅ IMPLEMENTEDArchitecture Docs3 hours

Automatically refresh expired OAuth access tokens using stored refresh tokens, preventing mid-conversation interruptions. Transparently handles token expiration with server-side refresh logic, Redis-backed token storage, and configurable refresh buffer times.

Key features:

  • Proactive refresh (token refreshed before expiration)
  • Reactive refresh (fallback if proactive fails)
  • Redis-backed pending token mechanism
  • Configurable refresh buffer (default: 5 minutes before expiration)
  • Comprehensive test coverage

Implementation date: 2026-01-06

Token Revocation ​

FeatureStatusDocumentationTime
Token Revocation✅ IMPLEMENTEDRFC 7009 Compliant4 hours

RFC 7009 OAuth token revocation endpoint allowing users to invalidate compromised tokens. Supports both local and upstream IdP revocation, uses Redis SCAN for efficient token lookup, and always returns HTTP 200 per specification.

Key features:

  • RFC 7009 compliant /oauth/revoke endpoint
  • Access token revocation with Redis cache (5-minute TTL)
  • Refresh token revocation proxied to upstream IdP
  • Efficient token lookup using Redis SCAN
  • Always returns 200 OK per specification

Implementation date: 2026-01-06

Token Refresh Race Condition ​

FeatureStatusDocumentationTime
Token Refresh Race Condition✅ IMPLEMENTEDDistributed Locking3-4 hours

Implemented distributed locking for token refresh operations to prevent concurrent refresh attempts. Eliminates single-use refresh token failures and reduces IdP load through Redis-based locking mechanism.

Key features:

  • Redis-based distributed locking (SETNX)
  • Prevents concurrent refresh attempts
  • Eliminates "refresh token already used" errors
  • Reduces IdP load
  • Critical for multi-window/multi-device scenarios

Implementation date: 2026-01-06

Token Update Notification ​

FeatureStatusDocumentationTime
Token Update Notification✅ IMPLEMENTEDResponse Headers2-3 hours

Notifies clients when tokens are refreshed via X-Token-Refreshed and X-New-Access-Token response headers. Eliminates unnecessary retry cycles and provides seamless token update experience.

Key features:

  • X-Token-Refreshed: true header when token refreshed
  • X-New-Access-Token header with new token value
  • Eliminates unnecessary retry cycles
  • Seamless token update for Claude clients
  • Improves user experience during long sessions

Implementation date: 2026-01-06

Session Expiration Notification ​

FeatureStatusDocumentationTime
Session Expiration Notification✅ IMPLEMENTEDResponse Headers1-2 hours

Informs clients when their MCP session will expire via the X-Session-Expires-At response header. Enables proactive session management, user warnings before disconnection, and better client-side session lifecycle handling.

Key features:

  • X-Session-Expires-At header with ISO 8601 timestamp
  • Calculated as current time + session TTL (24 hours default)
  • Updates on every request due to sliding window
  • No surprise disconnections
  • Better UX for long-running sessions

Implementation date: 2026-01-06

JWKS Key Rotation ​

FeatureStatusDocumentationTime
JWKS Key Rotation✅ IMPLEMENTEDAuthentication Architecture3-4 hours

Graceful JWKS key rotation handling with dual-cache architecture maintaining current and previous keys during a configurable grace period. Eliminates authentication failures during IdP key rotation with automatic detection and fallback.

Key features:

  • Dual-cache structure (current + previous keys)
  • Automatic key rotation detection by comparing key IDs
  • Configurable grace period (default: 10 minutes via OIDC_JWKS_GRACE_PERIOD_MS)
  • Three-tier fallback: current keys → previous keys → refresh cache
  • Structured logging for rotation events and previous key usage
  • Zero authentication failures during key rotation

Edge case resolution: When IdP rotates keys during active requests, JWTs signed with old keys continue to work during grace period through automatic fallback to previous keys.

Implementation date: 2026-01-07

Production Readiness ​

Graceful Shutdown ​

FeatureStatusDocumentationTime
Graceful Shutdown✅ IMPLEMENTEDSignal Handling6-8 hours

Comprehensive shutdown handling for Docker and Kubernetes with SIGTERM/SIGINT signal handling. Closes MCP sessions gracefully, stops JWKS refresh, closes Redis connections, and returns 503 during shutdown.

Key features:

  • SIGTERM and SIGINT signal handling
  • Stops accepting new connections via server.close()
  • 5-second grace period for active requests
  • Closes all MCP sessions in parallel
  • Closes Redis connections properly
  • Stops JWKS refresh timer
  • Health endpoint returns 503 during shutdown
  • Prevents re-entrance with shutdown flag

Kubernetes integration: Works automatically with Kubernetes pod termination - no special configuration needed.

Implementation date: 2026-01-06

Configuration Validation ​

FeatureStatusDocumentationTime
Configuration Validation✅ IMPLEMENTEDStartup Validation6-8 hours

Validates all configuration at startup to prevent runtime failures. Checks URL formats, numeric ranges, production requirements, and provides clear error messages. 42 test cases with 96.26% coverage.

Key features:

  • Validates all config values at startup
  • URL format validation (HTTP/HTTPS, redis://)
  • Port ranges (1-65535)
  • Numeric limits and TTL values
  • Production-specific security requirements
  • Exits with clear error messages if validation fails
  • 42 comprehensive test cases
  • 96.26% test coverage

Common validations:

  • Missing OIDC configuration when AUTH_REQUIRED=true
  • Invalid URL formats
  • Invalid port ranges
  • TTL values too short
  • Production security requirements

Implementation date: 2026-01-06

Health Check Improvements ​

FeatureStatusDocumentationTime
Health Check Improvements✅ IMPLEMENTEDKubernetes Probes4-6 hours

Enhanced health endpoints with comprehensive dependency validation. Includes separate liveness (/health) and readiness (/health/ready) probes with Redis connectivity, JWKS cache validation, and session capacity monitoring.

Key features:

  • Liveness probe (/health) - Process health, returns 503 during shutdown
  • Readiness probe (/health/ready) - Dependency health checks
  • Redis connectivity with circuit breaker state
  • JWKS cache with expiration tracking
  • Session capacity with utilization metrics
  • Kubernetes-compatible probe endpoints

Kubernetes deployment example:

yaml
livenessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 10
  periodSeconds: 10
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health/ready
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 5
  failureThreshold: 3

Implementation date: 2026-01-06

Error Handling & Resilience ​

Redis Connection Failure Handling ​

FeatureStatusDocumentationTime
Redis Connection Failure✅ IMPLEMENTEDCircuit Breaker8 hours

Implemented circuit breaker pattern for Redis operations with graceful degradation. Prevents cascading failures with consistent fallback behavior across session store, token store, and rate limiting. Automatic reconnection with exponential backoff.

Key features:

  • Circuit breaker pattern for Redis operations
  • Graceful degradation when Redis unavailable
  • Rate limiting "fails open" (allows requests through)
  • Session operations return clear errors
  • Automatic reconnection with exponential backoff
  • Health check integration shows circuit breaker state
  • Prevents cascading failures

Fallback behaviors:

  • Rate limiting: Allows requests through when Redis unavailable
  • Session store: Returns clear error messages
  • Token store: Distinguishes between Redis failures and token issues
  • Consistent error handling across all components

Implementation date: 2026-01-06

JWKS Discovery Retry ​

FeatureStatusDocumentationTime
JWKS Discovery Retry✅ IMPLEMENTEDExponential Backoff2.5 hours

Automatic retry mechanism with exponential backoff for JWKS (JSON Web Key Set) discovery failures. When the IdP is unavailable during initial JWKS fetch, the server schedules background retries instead of failing completely, allowing authentication to succeed once the IdP recovers.

Key features:

  • Background retries with exponential backoff (1s, 2s, 4s, 8s, 16s max)
  • Automatic recovery when IdP becomes available
  • Graceful degradation during IdP outages
  • Clean shutdown handling cancels pending retries
  • Structured logging tracks retry attempts

Retry strategy:

  • Attempt 1: 1 second delay
  • Attempt 2: 2 seconds delay
  • Attempt 3: 4 seconds delay
  • Attempt 4: 8 seconds delay
  • Attempt 5+: 16 seconds delay (capped)

Benefits:

  • Server starts successfully even if IdP unavailable
  • No manual intervention required when IdP recovers
  • Exponential backoff prevents overwhelming IdP during recovery
  • Clear error messages during outage period

Implementation date: 2026-01-07

Security & Rate Limiting ​

OAuth Authorize Rate Limiting ​

FeatureStatusDocumentationTime
OAuth Authorize Rate Limiting✅ IMPLEMENTEDRate Limiting Architecture2-3 hours

Distributed rate limiting for the OAuth authorization endpoint to prevent DoS attacks and authorization redirect flooding. Uses Redis-backed sliding window with per-IP and global limits.

Key features:

  • Per-IP limit: 10 requests per minute (default)
  • Global limit: 1,000 requests per minute (default)
  • 1-minute sliding window
  • Redis-backed distributed rate limiting
  • Prevents authorization redirect flooding
  • Reduces IdP load and audit log noise

Configuration:

bash
OAUTH_AUTHORIZE_RATE_LIMIT_WINDOW_MS=60000   # 1 minute
OAUTH_AUTHORIZE_RATE_LIMIT_MAX=10            # Per-IP limit
OAUTH_AUTHORIZE_GLOBAL_RATE_LIMIT_MAX=1000   # Global limit

Implementation date: 2026-01-06

Permissions-Policy Header ​

FeatureStatusDocumentationTime
Permissions-Policy Header✅ IMPLEMENTEDSecurity Architecture30 minutes

Defense-in-depth security header that restricts browser features and prevents unauthorized access to sensitive APIs. Disables 19 browser features that an MCP server/OAuth proxy doesn't need.

Key features:

  • Disables 19 sensitive browser features (camera, microphone, geolocation, etc.)
  • Applied globally via middleware
  • Format: feature=() where () = empty allowlist (disabled for all origins)
  • Complements authentication, CORS, and Helmet security headers
  • Defense-in-depth layer

Disabled features:

camera, microphone, geolocation, payment, usb, magnetometer,
gyroscope, accelerometer, ambient-light-sensor, autoplay,
encrypted-media, fullscreen, midi, picture-in-picture,
speaker-selection, sync-xhr, vr, xr-spatial-tracking, display-capture

Implementation date: 2026-01-06

PKCE Validation Timing ​

FeatureStatusDocumentationTime
PKCE Validation Timing✅ IMPLEMENTEDOAuth Architecture1-2 hours

Early PKCE parameter validation at the OAuth authorization endpoint before proxying to the IdP. Validates code_challenge_method, code_challenge length (43-128 chars), and base64url format compliance per RFC 7636.

Key features:

  • Validates code_challenge_method is "plain" or "S256"
  • Validates code_challenge length is 43-128 characters (RFC 7636 Section 4.2)
  • Validates code_challenge contains only base64url characters (A-Z, a-z, 0-9, -, _)
  • OAuth-compliant error redirects with state parameter preservation
  • JSON fallback errors when no redirect_uri provided
  • 12 comprehensive test cases

Benefits:

  • Immediate error feedback before starting OAuth flow
  • Reduced IdP load from invalid requests
  • Fewer wasted authorization redirects
  • Better user experience with clear error messages

Implementation date: 2026-01-07

Observability & Metrics ​

Token Refresh Metrics ​

FeatureStatusDocumentationTime
Token Refresh Metrics✅ IMPLEMENTEDPrometheus Metrics2-3 hours

Comprehensive Prometheus metrics for token refresh operations providing visibility into refresh success rates, durations, and pending token claims. Essential for monitoring OAuth token lifecycle and IdP performance.

Key features:

  • Token refresh attempts counter (type: proactive/reactive, result: success/failure/skipped)
  • Token refresh duration histogram with buckets [0.1, 0.5, 1, 2, 5] seconds
  • Pending tokens claimed counter
  • Instrumented in attemptTokenRefresh() and claimPending()
  • 6 comprehensive test cases
  • Grafana dashboard with 3 new panels

Grafana visualizations:

  • Stacked area chart for refresh attempts by result
  • Line chart for p50/p95/p99 latency percentiles
  • Stat panel for total pending tokens claimed

Use cases:

  • Monitor token refresh success rate: success / total
  • Track IdP performance via duration metrics
  • Alert on high failure rates or latency degradation
  • Capacity planning for IdP connections

Implementation date: 2026-01-07

OAuth Flow Metrics ​

FeatureStatusDocumentationTime
OAuth Flow Metrics✅ IMPLEMENTEDPrometheus Metrics2-3 hours

Comprehensive Prometheus metrics for OAuth 2.1 authorization and token flows providing visibility into authorization requests, token exchanges, and dynamic client registrations. Essential for monitoring OAuth operations and IdP performance.

Key features:

  • OAuth authorization requests counter (result: success/error/invalid_client)
  • OAuth token exchanges counter (grant_type: authorization_code/refresh_token, result: success/failure)
  • OAuth token exchange duration histogram with buckets [0.1, 0.5, 1, 2, 5] seconds
  • Instrumented across 3 OAuth endpoints with 14 total instrumentation points
  • 6 comprehensive test cases
  • Grafana dashboard with 3 new panels

Grafana visualizations:

  • Stacked area chart for authorization requests by result
  • Stacked area chart for token exchanges by grant type and result
  • Line chart for token exchange p50/p95/p99 latency percentiles

Use cases:

  • Monitor OAuth authorization success rate
  • Track token exchange patterns by grant type
  • Measure IdP token endpoint performance
  • Alert on authorization failures or invalid client rates
  • Capacity planning for OAuth operations

Implementation date: 2026-01-07

Implementation Timeline ​

Phase 1: High-Priority Features (January 6, 2026) ​

All 7 high-priority production-readiness features implemented:

  1. ✅ Graceful Shutdown (6-8 hours) - Clean resource cleanup
  2. ✅ Configuration Validation (6-8 hours) - Startup validation
  3. ✅ Health Check Improvements (4-6 hours) - Kubernetes probes
  4. ✅ Redis Connection Failure (8 hours) - Circuit breaker pattern
  5. ✅ Token Refresh Race Condition (3-4 hours) - Distributed locking
  6. ✅ Token Update Notification (2-3 hours) - Response headers
  7. ✅ Token Revocation (4 hours) - RFC 7009 compliance

Phase 2: Medium-Priority Enhancements (January 6-7, 2026) ​

Additional security, authentication, and observability improvements:

  1. ✅ Session Expiration Notification (1-2 hours) - Response headers
  2. ✅ OAuth Authorize Rate Limiting (2-3 hours) - DoS prevention
  3. ✅ Permissions-Policy Header (30 minutes) - Defense-in-depth
  4. ✅ JWKS Key Rotation (3-4 hours) - Graceful key rotation
  5. ✅ PKCE Validation Timing (1-2 hours) - Early OAuth error detection
  6. ✅ JWKS Discovery Retry (2.5 hours) - Exponential backoff resilience
  7. ✅ Token Refresh Metrics (2-3 hours) - Prometheus observability
  8. ✅ OAuth Flow Metrics (2-3 hours) - OAuth operation observability

Total effort: 45.5-55.5 hours

Testing Coverage ​

All implemented features have comprehensive test coverage:

  • ✅ Configuration Validation: 42 tests, 96.26% coverage
  • ✅ Graceful Shutdown: Comprehensive signal handling tests
  • ✅ Health Checks: Liveness and readiness probe tests
  • ✅ Token Revocation: RFC 7009 compliance tests
  • ✅ Token Refresh: Race condition and notification tests
  • ✅ Redis Resilience: Circuit breaker pattern tests
  • ✅ JWKS Key Rotation: 4 new tests (23 total JWKS tests), key rotation scenarios
  • ✅ JWKS Discovery Retry: 6 new tests (29 total JWKS tests), exponential backoff and recovery scenarios
  • ✅ OAuth Rate Limiting: Authorization endpoint rate limiting tests
  • ✅ Security Headers: Permissions-Policy header validation tests
  • ✅ PKCE Validation Timing: 12 new tests (30 total OAuth authorize tests), comprehensive validation scenarios
  • ✅ Token Refresh Metrics: 6 new tests (34 total metrics tests), comprehensive metric tracking validation
  • ✅ OAuth Flow Metrics: 6 new tests (40 total metrics tests), comprehensive OAuth operation tracking validation

Overall Test Metrics:

  • 771 tests passing across 45 test files
  • 93.02% overall code coverage
  • 1 skipped test (OAuth authorize flow requiring real IdP)

Production Deployment ​

Seed is now production-ready with all high-priority features implemented. For deployment guidance:

← Back to Enhancements Overview

Released under the MIT License.

Copyright © 2025 Adam Cole