# Release v1.0.21 - Admin Tooling, Centralized Logging, and ARM64 Support

**April 2026**

---

## Upgrading from v1.0.20

This section covers everything you need to know to upgrade from v1.0.20 to v1.0.21.

### Breaking Changes

There are no breaking changes in this release. All new features use sensible defaults and existing deployments will continue to work without configuration changes.

### New Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `APP_LOG_MAX_BYTES` | `52428800` | Max size per log file in bytes before rotation (50 MB). |
| `APP_LOG_BACKUP_COUNT` | `5` | Number of rotated backup log files to keep. |
| `APP_LOG_CENTRALIZED_ENABLED` | `true` | Write application logs to MongoDB for centralized retrieval. Requires MongoDB/DocumentDB backend. |
| `APP_LOG_CENTRALIZED_TTL_DAYS` | `1` | Days to retain application logs in MongoDB before TTL auto-expiry. |
| `APP_LOG_MONGODB_BUFFER_SIZE` | `50` | Number of log records to buffer before flushing to MongoDB. |
| `APP_LOG_MONGODB_FLUSH_INTERVAL_SECONDS` | `5.0` | Seconds between periodic flushes to MongoDB. |
| `APP_LOG_LEVEL` | `INFO` | Application log level: DEBUG, INFO, WARNING, ERROR, CRITICAL. |
| `APP_LOG_EXCLUDED_LOGGERS` | `uvicorn.access,httpx,pymongo,motor` | Comma-separated logger names to exclude from MongoDB log writes. |
| `OIDC_ENABLED` | `false` | Enable OIDC/OAuth2 authentication for the MCPGW server. |
| `OIDC_CLIENT_ID` | - | OIDC client credentials for MCPGW (used when OIDC_ENABLED=true). |
| `OIDC_CLIENT_SECRET` | - | OIDC client secret for MCPGW. |
| `KEYCLOAK_INTERNAL_URL` | - | Keycloak internal URL for server-to-server OIDC communication. |
| `M2M_CLIENT_ID` | - | M2M client ID for MCPGW to call registry APIs. |
| `M2M_CLIENT_SECRET` | - | M2M client secret for MCPGW. |
| `MCPGW_BASE_URL` | - | Base URL where the MCPGW server is reachable (for OAuth redirect URIs). |

### Upgrade Instructions

#### Docker Compose

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

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

#### Kubernetes / Helm (EKS)

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

# Update values.yaml with any new app log variables, 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.21

# Update your .tfvars with any new variables
cd terraform/aws-ecs
terraform plan
terraform apply
```

#### DockerHub Images

Pre-built images are available:

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

---

## Major Features

### Admin Data Export

A new Data Export section in the admin Settings page allows downloading registry data as JSON files for debugging, auditing, and backup. Supports 11 collections: Servers, Agents, Skills, Virtual Servers, Federation Peers, Federation Configs, Registry Card, IAM Users, IAM Groups, IAM M2M Clients, and Scopes. Download individual collections or use the Download All as ZIP button (powered by JSZip) with per-collection progress indicators. Includes a sensitive data warning banner and a dedicated scopes export endpoint that dumps full server_access rules. Admin-only access, not visible to non-admin users.

[PR #908](https://github.com/agentic-community/mcp-gateway-registry/pull/908)

### Centralized Log Rotation, Storage, and Retrieval

Production-grade application logging with RotatingFileHandler (50 MB, 5 backups) for both the registry and auth-server. Optional MongoDB storage via a non-blocking MongoDBLogHandler with buffered background writes and TTL-based auto-expiry. Admin REST API endpoints (`GET /api/admin/logs` for querying with filters, `GET /api/admin/logs/export` for JSONL download, `GET /api/admin/logs/metadata` for available services and levels) and a Settings UI Log Viewer with filtering by service, level, hostname, search text, and time range. Security includes MongoDB regex injection prevention via `re.escape()`, rate limiting (10 requests per 60 seconds per user), and max search length validation. MongoDB logging is ON by default; disable with `APP_LOG_CENTRALIZED_ENABLED=false`. File-based rotation is always active.

[PR #888](https://github.com/agentic-community/mcp-gateway-registry/pull/888), [PR #900](https://github.com/agentic-community/mcp-gateway-registry/pull/900), [PR #905](https://github.com/agentic-community/mcp-gateway-registry/pull/905)

### Multi-Architecture Docker Images (ARM64)

Docker images are now built for both amd64 and arm64 architectures using Docker Buildx multi-platform builds. ARM64 users (Apple Silicon Macs, AWS Graviton instances) can now pull and run images natively without emulation overhead.

[PR #865](https://github.com/agentic-community/mcp-gateway-registry/pull/865)

### Per-Skill Auth Credentials and Content Drift Detection

Skills now support per-skill authentication credentials (API keys, Bearer tokens) stored with the skill card. Multi-file skill support allows skills to reference multiple source files. Content drift detection compares the current skill content against the registered version and flags changes, helping operators detect when upstream skill definitions have been modified.

[PR #849](https://github.com/agentic-community/mcp-gateway-registry/pull/849), [PR #898](https://github.com/agentic-community/mcp-gateway-registry/pull/898)

---

## What's New

### Admin Tooling
- Admin Data Export page with 11 collection types and ZIP download (#908)
- Dedicated scopes export endpoint for full server_access rule dumps (#908)

### Observability
- Centralized log rotation with RotatingFileHandler for registry and auth-server (#888)
- MongoDB log storage with non-blocking buffered writes and TTL auto-expiry (#888)
- Admin log retrieval API with filtering, export, and metadata endpoints (#888)
- Settings UI Log Viewer with service, level, hostname, and time range filters (#888)
- Post-merge fixes for log handler naming, defaults, and linting (#900)
- Graceful PermissionError handling in RotatingFileHandler (#905)

### Skills
- Per-skill auth credentials for API key and Bearer token authentication (#849)
- Multi-file skill support for referencing multiple source files (#849)
- Content drift detection for upstream skill definition changes (#849)
- Post-merge fixes for auth, service layering, and env docs (#898)

### Infrastructure
- Multi-arch Docker images for amd64 and arm64 (#865)
- Helm chart configmaps for application log settings (registry and auth-server) (#888)
- YAML anchor pattern for shared app log config in stack chart (#888)
- MCPGW OIDC/OAuth2 environment variable documentation in .env.example

### Performance
- Remove in-memory agent registry and state cache in favor of direct repository queries (#907)
- Bulk `get_all_states()` method to eliminate N+1 queries in agent state lookups (#910)
- Aligned `get_state()` interface signatures across repository implementations (#910)

### Security
- Scoped `add_server_scope` and `remove_server_scope` IAM actions to target group only (#909)
- Skip CSRF validation for Bearer token clients on toggle endpoints (#894)

### Documentation
- README roadmap updated with release-based milestones (v1.0.20, v1.0.21, v1.0.22)
- What's New entries for Admin Data Export and Centralized Logging

---

## Bug Fixes

- Fix CSRF validation blocking programmatic agent/skill toggle for Bearer token clients (#894)
- Fix `add_server_scope` and `remove_server_scope` applying to all groups instead of target group (#909)
- Fix PermissionError crash in RotatingFileHandler when log directory has restricted permissions (#905)
- Fix log handler naming conventions and default values after initial logging PR merge (#900)
- Fix N+1 query pattern in agent state lookups by adding bulk `get_all_states()` (#910)
- Fix `get_state()` signature divergence between file and DocumentDB repository implementations (#910)

---

## Pull Requests Included

| PR | Title |
|----|-------|
| #910 | fix(agents): add bulk get_all_states() and align get_state() signatures |
| #909 | fix(scopes): scope add_server_scope and remove_server_scope to target group only |
| #908 | feat(settings): add admin Data Export page for downloading registry collections |
| #907 | remove in-memory agent registry and state cache |
| #905 | fix(logging): handle PermissionError in RotatingFileHandler gracefully |
| #900 | fix(logging): post-PR-888 follow-ups for naming, defaults, linting, and docs |
| #899 | chore(skill): add internal instance identification and stickiness metrics to usage-report |
| #898 | fix(skills): post-PR-849 follow-ups for auth, service layering, and env docs |
| #894 | fix: skip CSRF validation for Bearer token clients on toggle endpoints |
| #892 | chore(deps): bump gitpython from 3.1.45 to 3.1.47 |
| #890 | chore(deps): bump postcss from 8.5.6 to 8.5.10 |
| #888 | feat(logging): centralized log rotation, MongoDB storage, and retrieval API |
| #887 | chore(deps): bump postcss from 8.5.6 to 8.5.12 in /frontend |
| #865 | feat: build multi-arch Docker images (amd64 + arm64) |
| #849 | feat(skills): add auth credentials, multi-file support, and content drift detection |

---

## Security Dependency Updates

| Package | Previous | Updated | Scope |
|---------|----------|---------|-------|
| gitpython | 3.1.45 | 3.1.47 | root |
| postcss | 8.5.6 | 8.5.12 | frontend |

---

## Contributors

Thank you to all contributors for this release:

- **Amit Arora** ([@amitarora](https://github.com/amitarora))
- **Daniel Y** ([@daniely](https://github.com/daniely))
- **Prateek Sinha** ([@prateeksinha](https://github.com/prateeksinha))
- **Omri Shiv** ([@omrishiv](https://github.com/omrishiv))
- **Madhu C** ([@madhuc-ghub](https://github.com/madhuc-ghub))

---

## 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.20...v1.0.21](https://github.com/agentic-community/mcp-gateway-registry/compare/v1.0.20...v1.0.21)
