Summary

Improve security posture for multi-environment deployments by adding startup warnings when default JWT configuration is detected in non-development environments, and optionally embedding an environment claim in tokens.

Motivation

When deploying MCP Gateway across multiple environments (DEV, UAT, PROD), administrators must configure unique JWT signing keys and issuer/audience values per environment. If these values are left at defaults or shared, tokens from one environment will be accepted in another.

The gateway already warns about default JWT signing keys, but there is no runtime feedback when default issuer/audience values are used in production-like environments.

Proposed Changes

1. Startup warnings for default JWT values

When ENVIRONMENT is set to staging or production, log warnings if:

• JWT_ISSUER is the default value (mcpgateway)
• JWT_AUDIENCE is the default value (mcpgateway-api)

This helps operators catch misconfiguration during deployment.

2. Optional environment claim in tokens

Add a new configuration option EMBED_ENVIRONMENT_IN_TOKENS (default: false). When enabled:

• Include "env": settings.environment in gateway-issued JWTs (login, SSO, API tokens)
• Add VALIDATE_TOKEN_ENVIRONMENT option to reject tokens with mismatched environment claims

Scope: Only gateway-issued tokens are modified. External tokens from IdPs or proxy authentication are unaffected.

Backward compatibility: When VALIDATE_TOKEN_ENVIRONMENT=true, tokens without an env claim are allowed (to support existing tokens and external JWTs). Only tokens with a present but mismatched env claim are rejected.

This provides defense-in-depth for deployments where issuer/audience may not be unique.

3. Documentation updates

• Add explicit guidance to docs/docs/manage/securing.md about per-environment JWT configuration
• Update Helm chart comments in charts/mcp-stack/values.yaml with examples

Acceptance Criteria

• Startup warning logged when default JWT_ISSUER used in non-development environment
• Startup warning logged when default JWT_AUDIENCE used in non-development environment
• EMBED_ENVIRONMENT_IN_TOKENS config option added (default: false)
• VALIDATE_TOKEN_ENVIRONMENT config option added (default: false)
• Environment claim added to JWTs when EMBED_ENVIRONMENT_IN_TOKENS=true
• Environment claim validated when VALIDATE_TOKEN_ENVIRONMENT=true (reject mismatched, allow missing)
• Documentation updated with per-environment configuration guidance

Implementation Notes

Files to modify:

• mcpgateway/config.py - Add new config options
• mcpgateway/main.py - Add startup warnings
• mcpgateway/utils/create_jwt_token.py - Embed environment claim
• mcpgateway/utils/verify_credentials.py - Validate environment claim
• docs/docs/manage/securing.md - Add environment isolation section
• docs/docs/manage/configuration.md - Document new config options
• charts/mcp-stack/values.yaml - Update comments
• README.md - Add new environment variables to config table