# Release v1.0.16 - mcpgw Rewrite, macOS Setup Skill, Security Hardening & Observability

**March 2026**

---

## Upgrading from v1.0.15

This section covers everything you need to know to upgrade from v1.0.15 to v1.0.16.

### Breaking Changes

**Helm Chart Dependencies Added (EKS/Helm users only)**

New `mcpgw` and `mcpgw-configure` sub-chart dependencies have been added to the `mcp-gateway-registry-stack` chart. If you are upgrading Helm charts from v1.0.15, you **must** rebuild dependencies before upgrading:

```bash
# Required before helm upgrade
cd charts/mcp-gateway-registry-stack
helm dependency build
helm dependency update
```

Without this step, `helm upgrade` will fail because the new dependencies are not available locally.

**SECRET_KEY Now Used for Credential Encryption (#562)**

The `SECRET_KEY` environment variable is now used for encrypting backend MCP server credentials (Bearer tokens, API keys) in addition to JWT token signing and session security. **Changing this key will invalidate all existing encrypted credentials stored in the database.**

If you need to rotate the secret key:
1. Export all server configurations
2. Update SECRET_KEY
3. Re-register servers with authentication credentials

### New Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `GRAFANA_ADMIN_PASSWORD` | (required) | Grafana admin password for metrics dashboard. Generate with: `python3 -c "import secrets; print(secrets.token_urlsafe(24))"` |
| `WORKDAY_TOKEN_URL` | (optional) | Workday ASOR federation token endpoint (required only for Workday ASOR integration) |

**Note**: The `SECRET_KEY` variable documentation has been updated to include its new role in encrypting backend server credentials. This is not a new variable but its usage has expanded.

### Upgrade Instructions

#### Docker Compose

```bash
cd mcp-gateway-registry
git pull origin main
git checkout v1.0.16

# Review new env vars in .env.example and update your .env
# Set GRAFANA_ADMIN_PASSWORD if using observability
# Then rebuild and restart:
./build_and_run.sh
```

#### Kubernetes / Helm (EKS)

```bash
cd mcp-gateway-registry
git pull origin main
git checkout v1.0.16

# REQUIRED: Rebuild dependencies (mcpgw sub-charts added)
cd charts/mcp-gateway-registry-stack
helm dependency build
helm dependency update

# Update values.yaml for new mcpgw charts if needed, then upgrade:
helm upgrade mcp-gateway . -f your-values.yaml
```

#### Terraform / ECS

```bash
cd mcp-gateway-registry
git pull origin main
git checkout v1.0.16

# Update your .tfvars with GRAFANA_ADMIN_PASSWORD if using observability
cd terraform/aws-ecs
terraform plan
terraform apply
```

#### DockerHub Images

Pre-built images are available:

```bash
docker pull mcpgateway/registry:v1.0.16
docker pull mcpgateway/auth-server:v1.0.16
docker pull mcpgateway/currenttime-server:v1.0.16
docker pull mcpgateway/realserverfaketools-server:v1.0.16
docker pull mcpgateway/mcpgw-server:v1.0.16
docker pull mcpgateway/fininfo-server:v1.0.16
docker pull mcpgateway/metrics-service:v1.0.16
```

---

## Major Features

### mcpgw MCP Server Rewrite

Complete architectural rewrite of the AI Registry Tools (mcpgw) MCP server to eliminate technical debt and modernize the implementation:

- **Registry HTTP API Integration**: Replaces direct DocumentDB/MongoDB access with calls to Registry HTTP APIs for improved security and maintainability
- **FastMCP 2.0 Upgrade**: Migrates from MCP 1.x to FastMCP 2.0 for better protocol compliance and performance
- **Secure Host Binding**: Implements environment-based host binding (defaults to 127.0.0.1, uses 0.0.0.0 only when explicitly configured)
- **Auto-Registration**: Server automatically registers itself on registry startup with immediate health checks and security scans
- **Helm Chart Support**: New mcpgw sub-chart with configuration management (mcpgw-configure)
- **Containerization**: Dedicated Dockerfile.mcp-server with registry module support

[PR #584](https://github.com/agentic-community/mcp-gateway-registry/pull/584) | [PR #586](https://github.com/agentic-community/mcp-gateway-registry/pull/586) | [Issue #583](https://github.com/agentic-community/mcp-gateway-registry/issues/583)

### macOS Setup and Teardown Claude Skill

Automated macOS installation and teardown via Claude Code skill:

- **One-Command Setup**: Complete MCP Gateway & Registry installation on macOS with single skill invocation
- **Interactive Configuration**: Choose between default values or interactive prompts for all settings
- **Full Stack Deployment**: Installs all services (registry, auth, Keycloak, MongoDB) with proper configuration
- **Verification Steps**: Automated health checks and Cloudflare docs server registration
- **Complete Teardown**: Clean removal of all containers, volumes, and cloned repository
- **GitHub Integration**: Can be run directly from GitHub URL without pre-cloning repository

[PR #585](https://github.com/agentic-community/mcp-gateway-registry/pull/585) | [Issue #581](https://github.com/agentic-community/mcp-gateway-registry/issues/581)

### Observability Pipeline with Grafana

Production-ready metrics pipeline for AWS ECS deployments:

- **Amazon Managed Prometheus (AMP)**: Native integration with AWS managed Prometheus service
- **Grafana Dashboards**: Pre-configured dashboards for MCP data-plane metrics
- **Metrics Service**: FastAPI-based collector with OpenTelemetry export support
- **Tool Execution Metrics**: Counters and duration histograms for MCP tool invocations
- **System Stats**: Memory, CPU, and connection pool monitoring
- **ECS Native**: Fully integrated with ECS Fargate service discovery

[PR #544](https://github.com/agentic-community/mcp-gateway-registry/pull/544) | [Issue #489](https://github.com/agentic-community/mcp-gateway-registry/issues/489)

### Encrypted Backend Server Credentials

Secure credential storage for backend MCP server authentication:

- **auth_scheme Field**: Replaces `auth_type` with more descriptive `auth_scheme` (bearer, basic, api-key, oauth, custom)
- **Encrypted Storage**: Backend server credentials (Bearer tokens, API keys) encrypted using SECRET_KEY with Fernet encryption
- **Health Check Support**: Encrypted credentials automatically used for health check authentication
- **Migration Path**: Old `auth_type` values still supported for backward compatibility
- **UI Integration**: Auth scheme configuration in server registration forms

[PR #562](https://github.com/agentic-community/mcp-gateway-registry/pull/562) | [Issue #542](https://github.com/agentic-community/mcp-gateway-registry/issues/542)

### Federation Server Reconciliation

Improved federation with server reconciliation and bug fixes:

- **Sync Existing Servers**: Federation now syncs servers that already exist in the database but are missing from the peer registry
- **DELETE Endpoint Fix**: Corrected federation DELETE endpoint to properly remove servers
- **Reconciliation Logic**: Compares local DB state with peer registry and syncs missing entries
- **Generation Tracking**: Uses generation numbers to detect and handle orphaned servers

[PR #576](https://github.com/agentic-community/mcp-gateway-registry/pull/576) | [Issue #539](https://github.com/agentic-community/mcp-gateway-registry/issues/539)

### Audit Log Enhancements

Searchable audit logs with advanced filtering and statistics:

- **Searchable Filters**: Search by username, HTTP method, status code, or audit stream
- **Date Range Filtering**: Filter audit events by date range with calendar picker
- **Statistics Dashboard**: View audit event counts, unique users, and timeline distributions
- **Export Support**: Export filtered results to CSV/JSONL
- **Performance Optimized**: Efficient queries with pagination and proper indexing

[PR #575](https://github.com/agentic-community/mcp-gateway-registry/pull/575) | [Issue #572](https://github.com/agentic-community/mcp-gateway-registry/issues/572)

### System Uptime Display

Registry uptime tracking with detailed system statistics:

- **Uptime Display**: Shows registry uptime below version number in UI
- **System Stats Tooltip**: Hover for detailed stats including memory usage, CPU, active connections
- **Human-Readable Format**: Displays uptime in days, hours, minutes format
- **Real-Time Updates**: Stats update on page load to show current system state

[PR #567](https://github.com/agentic-community/mcp-gateway-registry/pull/567) | [Issue #566](https://github.com/agentic-community/mcp-gateway-registry/issues/566)

### OIDC SSO Logout with id_token_hint

Fixed Keycloak and Entra ID SSO logout to properly terminate SSO sessions:

- **Proper OIDC Logout**: Implements OIDC logout flow with `id_token_hint` parameter
- **SSO Session Termination**: Clicking logout now terminates the session at the identity provider, not just locally
- **id_token Storage**: Always stores id_token in session for logout (removes unused access_token/refresh_token for improved security)
- **CORS Fix**: Changed frontend logout from XHR to full-page redirect to avoid cross-origin errors
- **Styled Logout Page**: Professional logout success page with auto-redirect to login
- **Multi-Provider Support**: Works with both Keycloak and Entra ID (Microsoft) identity providers
- **Observability**: Added 4 Prometheus metrics for monitoring logout flow

[PR #592](https://github.com/agentic-community/mcp-gateway-registry/pull/592) | [Issue #490](https://github.com/agentic-community/mcp-gateway-registry/issues/490)

---

## What's New

### Security Hardening

- SQL injection fixes in metrics-service (#579, issue #522)
- Fixed subprocess security findings (B603/B607) with hardcoded command validation (#577, issue #523)
- Resolved hardcoded password findings (B105) (#571, issue #525)
- Fixed import and pattern security findings (B404/B307/B310) (#568, issue #526)
- Configured Bandit B101 skip for test files (#565, issue #524)
- Added missing request timeouts (B113) to prevent DoS (#535, issue #518)
- Suppressed B104 findings with nosec comments and env var configurability (#534, issue #520)
- Replaced try-except-pass with proper error handling (B110) (#538, issue #521)
- Stripped newlines from X-Body header to prevent scope validation bypass (#529)

### IAM and Authentication

- Rebrand to AI Gateway & Registry with hidden local admin login (#555, issue #554)
- Fixed IAM Groups tool selector empty state, path normalization, and UI permission sync (#570, issue #569)
- Auth scheme screenshot added to authentication guide documentation
- OIDC SSO logout with id_token_hint for Keycloak and Entra ID (#592, issue #490)

### Federation

- Preserved encrypted federation tokens during peer updates (#564, issue #561)
- Federation server reconciliation to sync existing DB configuration (#576, issue #539)

### Infrastructure

- Resolved ECS Service Connect dual-stack DNS failures in registry entrypoint (#548, issue #547)
- Fixed ROOT_PATH missing in generated nginx config (#532)
- Updated CodeBuild source to point to upstream repo and main branch (#552, issue #491)
- Ruff code formatting applied across codebase (#541)
- mcpgw API compatibility fixes: corrected response parsing for list_services and intelligent_tool_finder (#588)
- mcpgw security improvements: removed debug logging exposure of bearer tokens and eliminated SSRF vulnerability (#588)
- mcpgw ECS Service Connect integration with least-privilege security group rules (#588, #590)

### Audit Logging

- Fixed audit events composite key to allow both MCPServerAccessRecord and RegistryApiAccessRecord per request (#530, issue #527)
- Ensured audit log timestamps include UTC timezone in API responses
- Handled TTL index options conflict in mongodb-init

### Documentation

- Added modern type hints (PEP 604/585) and pre-commit hook guidance to CLAUDE.md (#582)
- Added comprehensive subprocess and SQL security guidelines to CLAUDE.md (#580)
- More precise language in documentation (#504)

### Agent Discovery

- Simplified A2A agent discovery configuration (#550)
- Added discovery integration test

---

## Bug Fixes

- IAM Groups: tool selector empty, UI permissions not synced, server paths inconsistently normalized (#570, issue #569)
- Federation: update_peer() silently drops encrypted token on config update (#564, issue #561)
- ECS Service Connect dual-stack DNS breaks Lua metrics flush and Python health checker (#548, issue #547)
- Audit events composite key allowing only one event type per request (#530, issue #527)
- Registry missing ROOT_PATH in generated nginx config (#532)
- Handled TTL index options conflict in mongodb-init
- Ensured audit log timestamps include UTC timezone in API responses
- Keycloak and Entra ID SSO logout not terminating identity provider session (#592, issue #490)
- mcpgw list_services returning 0 servers due to API response key mismatch (#588)
- mcpgw intelligent_tool_finder returning empty results due to incorrect parsing (#588)
- mcpgw Pydantic validation failing on registry API responses (#588)
- mcpgw debug logging exposing bearer tokens and sensitive headers (#588)

---

## Pull Requests Included

| PR | Title |
|----|-------|
| #592 | Fix Keycloak SSO logout with id_token_hint (issue #490) |
| #590 | update mcpgw deployment and dockerfile |
| #589 | chore(deps): bump fast-xml-parser and @aws-sdk/xml-builder in /cli |
| #588 | fix: mcpgw API compatibility, security hardening, and Service Connect |
| #586 | add mcpgw build and charts |
| #585 | feat: add macOS setup and teardown Claude skill |
| #584 | Rewrite mcpgw MCP server to use registry HTTP APIs (issue #583) |
| #582 | docs: add modern type hints (PEP 604/585) and pre-commit hook guidance |
| #580 | docs: add comprehensive subprocess and SQL security guidelines to CLAUDE.md |
| #579 | 522 address sql injection in metrics |
| #578 | more ruff fixes |
| #577 | 523 address bandit finding subprocess |
| #576 | feat: add federation server reconciliation and fix DELETE endpoint (issue #539) |
| #575 | feat: searchable audit log filters and statistics dashboard (#572) |
| #571 | fix: resolve Bandit B105 findings (issue #525) |
| #570 | fix(iam): tool selector, path normalization, and UI permission sync in IAM Groups |
| #568 | fix: resolve Bandit B404/B307/B310 findings (issue #526) |
| #567 | feat: add uptime display with system stats tooltip (#566) |
| #565 | fix(security): configure Bandit B101 skip for test files |
| #564 | fix: preserve encrypted federation tokens during peer updates (#561) |
| #563 | chore(deps): bump awscli from 1.44.4 to 1.44.38 |
| #562 | feat: Replace auth_type with auth_scheme and add encrypted credential storage for backend server authentication |
| #555 | feat: hide local admin login and rebrand to AI Gateway & Registry |
| #552 | fix: point CodeBuild source to upstream repo and main branch |
| #551 | chore(deps): bump rollup from 2.79.2 to 2.80.0 in /frontend |
| #550 | fix: simplify A2A agent discovery configuration |
| #549 | chore(deps): bump langgraph-checkpoint from 3.0.1 to 4.0.0 |
| #548 | fix: resolve ECS Service Connect dual-stack DNS failures in registry entrypoint |
| #546 | chore(deps): bump minimatch in /frontend |
| #544 | feat: observability pipeline with AMP, Grafana, and metrics-service for ECS |
| #541 | ruff format code |
| #538 | fix: Replace try-except-pass with proper error handling (Bandit B110) (#521) |
| #535 | fix(security): add missing request timeouts (Bandit B113) |
| #534 | fix: Bandit B104 findings across 11 files (#520) |
| #532 | Bug: Registry - missing ROOT_PATH in generated nginx config |

---

## Security Dependency Updates

| Package | Previous | Updated | Scope |
|---------|----------|---------|-------|
| fast-xml-parser | 5.3.6 | 5.4.1 | CLI |
| @aws-sdk/xml-builder | 3.972.5 | 3.972.9 | CLI |
| awscli | 1.44.4 | 1.44.38 | CLI tools |
| rollup | 2.79.2 | 2.80.0 | frontend |
| langgraph-checkpoint | 3.0.1 | 4.0.0 | registry |
| minimatch | (various) | latest | frontend |

---

## Contributors

Thank you to all contributors for this release:

- **Amit Arora** ([@aarora79](https://github.com/aarora79))
- **Omri Shiv** ([@omrishiv](https://github.com/omrishiv))
- **Geoffrey Norman** ([@gknorman](https://github.com/gknorman))
- **Abhishek Singh** ([@abkrsinh](https://github.com/abkrsinh))
- **Wallace Printz** ([@printw](https://github.com/printw))
- **sazandkhalid** ([@sazandkhalid](https://github.com/sazandkhalid))
- **snorlaX-sleeps** ([@snorlaX-sleeps](https://github.com/snorlaX-sleeps))
- **dependabot[bot]** ([@dependabot](https://github.com/apps/dependabot))

---

## Support

- [GitHub Issues](https://github.com/agentic-community/mcp-gateway-registry/issues)
- [GitHub Discussions](https://github.com/agentic-community/mcp-gateway-registry/discussions)
- [Documentation](https://github.com/agentic-community/mcp-gateway-registry/tree/main/docs)

---

**Full Changelog:** [v1.0.15...v1.0.16](https://github.com/agentic-community/mcp-gateway-registry/compare/v1.0.15...v1.0.16)
