Upgrading to MCP Hangar v1.0¶

This guide covers upgrading from v0.12.x (or earlier) to v1.0.0. If you are upgrading from a version older than v0.4.0, read every section. If you are already on v0.12.x, skip to the Pre-flight checklist and then review only the sections marked with your starting version.

Pre-flight checklist¶

Run through this list before you begin. Every item should be green before you upgrade production.

1. Back up your configuration. Copy config.yaml, .env, and any Kubernetes manifests (MCPProvider, MCPProviderGroup, MCPDiscoverySource CRs).
2. Back up your event store. If you use SQLite or Postgres event sourcing, take a snapshot or dump before upgrading.
3. Note your current version. Run mcp-hangar --version or check pyproject.toml.
4. Check Python version. v1.0 requires Python 3.11+. Run python3 --version to confirm.
5. Review deprecation warnings. Run your test suite and check logs for deprecation warnings introduced in v0.4.0 through v0.12.0.
6. Read the sections below that apply to your starting version.
7. Test in staging before promoting to production.

Version upgrade paths¶

Python version requirement¶

Applies to: all versions before v0.3.0

MCP Hangar v1.0 requires Python 3.11 or later. Earlier versions were compatible with Python 3.10. If you are running 3.10, upgrade Python first.

python3 --version
# Must be 3.11.x or later

Rebrand: "registry" to "hangar" (v0.4.0)¶

Applies to: upgrading from v0.3.x or earlier

v0.4.0 renamed the project from "MCP Registry" to "MCP Hangar". This is the single largest breaking change in the project's history. All backward compatibility aliases were removed in v0.4.0.

MCP tool renames¶

All 14 MCP tools changed prefix from registry_* to hangar_*:

Action: Update any AI assistant system prompts, scripts, or integrations that reference tool names.

Python API renames¶

Action: Search your code for Registry and with_registry and replace.

Removed factory functions¶

These convenience functions were removed in v0.4.0:

# Before (removed)
from mcp_hangar import setup_fastmcp_server
server = setup_fastmcp_server(config_path="config.yaml")

# After
from mcp_hangar.fastmcp_server import MCPServerFactory
factory = MCPServerFactory()
server = factory.create_server(config_path="config.yaml")

Prometheus metric renames¶

All metrics changed prefix from mcp_registry_* to mcp_hangar_*:

Action: Update Grafana dashboards, Prometheus recording rules, and alert rules. If you use the bundled dashboards from monitoring/, update them from the latest release.

Kubernetes operator API group (v0.2.0)¶

Applies to: upgrading from v0.1.x

The CRD API group changed from mcp.hangar.io to mcp-hangar.io in v0.2.0.

# Before (v0.1.x)
apiVersion: mcp.hangar.io/v1alpha1
kind: MCPProvider

# After (v0.2.0+)
apiVersion: mcp-hangar.io/v1alpha1
kind: MCPProvider

Action:

1. Update all MCPProvider, MCPProviderGroup, and MCPDiscoverySource manifests.
2. Delete old CRDs: kubectl delete crd mcpproviders.mcp.hangar.io
3. Install new CRDs from the updated Helm chart or make install in the operator directory.
4. Re-apply your custom resources with the new API group.

Environment variables¶

Applies to: all versions

Prefix migration: HANGAR_* to MCP_*¶

The canonical environment variable prefix is MCP_*. The old HANGAR_* prefix is not supported in v1.0.

Action: Search your shell profiles, .env files, Docker Compose files, Kubernetes ConfigMaps/Secrets, and CI pipelines for HANGAR_ and replace with MCP_.

Langfuse environment variables¶

The Langfuse integration variables also follow the MCP_* convention in v1.0:

Repository URL migration (v0.7.0)¶

Applies to: upgrading from v0.6.x or earlier

All repository URLs migrated from github.com/mapyr to github.com/mcp-hangar in v0.7.0. This affects:

• Git remote URLs
• Go module import paths
• Container image references (GHCR)
• Documentation links
• Helm chart source URLs

Action: Update any pinned references to the old GitHub organization.

# Check for old references
grep -r "mapyr" . --include="*.yaml" --include="*.yml" --include="*.toml"

# Go modules: update go.mod
# Old: github.com/mapyr/...
# New: github.com/mcp-hangar/...

Configuration changes (v0.6.0+)¶

Several new configuration sections were added between v0.6.0 and v0.8.0. These are all opt-in with sensible defaults, so existing config files continue to work. Review these if you want to take advantage of new capabilities.

Hot-reload configuration (v0.6.6)¶

# New section -- optional, enabled by default
config_reload:
  enabled: true
  use_watchdog: true
  interval_s: 5

Response truncation (v0.6.3)¶

# New section -- optional, disabled by default
truncation:
  enabled: false
  max_batch_size_bytes: 950000
  cache_driver: memory        # memory | redis
  cache_ttl_s: 300

Execution concurrency (v0.7.0)¶

# New section -- optional
execution:
  max_concurrency: 50              # global limit
  default_provider_concurrency: 10 # per-provider default

providers:
  my_provider:
    max_concurrency: 5  # per-provider override

Tool access filtering (v0.8.0)¶

# New per-provider section -- optional
providers:
  grafana:
    tools:
      deny_list:
        - "delete_*"
        - "create_alert_rule"
      allow_list:
        - "query_*"

bootstrap() API change (v0.3.0)¶

Applies to: upgrading from v0.2.x or earlier

The bootstrap() function now accepts an optional config_dict parameter for programmatic configuration. This is backward compatible -- existing calls without the parameter continue to work. If you were monkey-patching configuration, use this parameter instead:

# Before
import mcp_hangar.server.config as cfg
cfg._global_config = my_config
bootstrap()

# After
bootstrap(config_dict=my_config)

Enterprise module split¶

Applies to: v1.0 (new in this release)

Starting with v0.13.0, enterprise features (auth, RBAC, behavioral profiling, compliance export, Langfuse integration) moved from the core package to the enterprise/ directory. As of v1.3.0, the enterprise/ directory was absorbed back into src/mcp_hangar/ and the entire codebase is licensed under MIT.

What moved¶

Impact on deployments¶

• All users: No license key or tier distinction applies. All features (provider lifecycle, health checks, circuit breaker, groups, load balancing, failover, Prometheus metrics, OTEL export, CLI, hot-reload, batch invocations, auth, RBAC, behavioral profiling, compliance export, Langfuse integration) are unconditionally available under MIT.

Import boundary¶

Core code never imports from enterprise/. If you have custom code that imports from internal paths that moved to enterprise/, update your imports:

# Before (if you imported internal auth modules directly)
from mcp_hangar.infrastructure.auth.api_key_store import SQLiteApiKeyStore

# After -- use the contract interface from core
from mcp_hangar.domain.contracts import IApiKeyStore
# The concrete implementation is loaded by bootstrap when licensed

Deprecated patterns removed in v1.0¶

The following were deprecated in earlier versions and are removed in v1.0:

Action: Search your code for these names. If any are found, replace them before upgrading.

# Quick check for deprecated patterns
grep -rn "ProviderSpec\|ProviderConnection\|ProviderHealth\|provider_manager" \
  --include="*.py" your_project/

grep -rn "setup_fastmcp_server\|create_fastmcp_server\|run_fastmcp_server" \
  --include="*.py" your_project/

grep -rn "RegistryFunctions\|with_registry\|registry_list\|registry_invoke" \
  --include="*.py" your_project/

Kubernetes operator upgrade¶

Applies to: users running the MCP Hangar operator in Kubernetes

CRD updates¶

The operator CRDs remain at v1alpha1 in v1.0. A future release will introduce v1beta1 with conversion webhooks (tracked as task 11.10).

If upgrading from v0.1.x, you must update the API group as described in Kubernetes operator API group.

Helm chart upgrade¶

# 1. Back up current values
helm get values mcp-hangar -n mcp-hangar > values-backup.yaml

# 2. Update the chart repository
helm repo update mcp-hangar

# 3. Review changes
helm diff upgrade mcp-hangar mcp-hangar/mcp-hangar \
  -n mcp-hangar -f values-backup.yaml

# 4. Apply
helm upgrade mcp-hangar mcp-hangar/mcp-hangar \
  -n mcp-hangar -f values-backup.yaml

Helm values changes¶

Review your values.yaml for these additions in the hangar-cloud chart:

# Authentication (required for enterprise features)
config:
  auth:
    jwtSecret: ""  # Set via secret reference, not plaintext

# Database (if using Postgres event store)
postgresql:
  enabled: true

# Autoscaling (new)
autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10

Observability upgrade¶

Grafana dashboards¶

If you use the bundled Grafana dashboards from monitoring/, replace them with the versions from v1.0. Key changes since v0.4.0:

• All metric names use mcp_hangar_* prefix (not mcp_registry_*).
• New dashboards: alerts.json, provider-details.json (added v0.6.4).
• Alert count reduced from 28 to 19 in v0.6.4 (removed alerts for not-yet-populated metrics).
• Updated thresholds: P95 latency 5s to 3s, P99 10s to 5s, batch slow 60s to 30s.

Prometheus alert rules¶

Replace monitoring/alerts.yaml with the v1.0 version. If you have custom rules, update metric names:

# Before
- alert: MCPRegistryToolCallSlow
  expr: mcp_registry_tool_call_duration_seconds > 5

# After
- alert: MCPHangarToolCallSlow
  expr: mcp_hangar_tool_call_duration_seconds > 5

New metrics (v0.5.0 - v0.12.0)¶

These metrics were added after v0.4.0. They are available automatically -- no configuration change needed, but you may want to add dashboard panels:

Step-by-step upgrade procedure¶

PyPI package users¶

# 1. Check current version
pip show mcp-hangar

# 2. Upgrade
pip install --upgrade mcp-hangar==1.0.0
# or with uv:
uv pip install mcp-hangar==1.0.0

# 3. Verify
mcp-hangar --version

# 4. Test configuration
mcp-hangar serve --dry-run  # if available, or start and check logs

# 5. Update environment variables (see sections above)
# 6. Update any custom code imports (see sections above)
# 7. Restart
mcp-hangar serve

Docker users¶

# 1. Pull new image
docker pull ghcr.io/mcp-hangar/mcp-hangar:1.0.0

# 2. Update docker-compose.yml image tag
# image: ghcr.io/mcp-hangar/mcp-hangar:1.0.0

# 3. Update environment variables in docker-compose.yml
# Replace HANGAR_* with MCP_*

# 4. Restart
docker compose up -d

Kubernetes users¶

# 1. Back up CRDs and custom resources
kubectl get mcpproviders -A -o yaml > mcpproviders-backup.yaml
kubectl get mcpprovidergroups -A -o yaml > mcpprovidergroups-backup.yaml
kubectl get mcpdiscoverysources -A -o yaml > mcpdiscoverysources-backup.yaml

# 2. Update Helm chart
helm repo update
helm upgrade mcp-hangar mcp-hangar/mcp-hangar -n mcp-hangar -f values.yaml

# 3. Verify operator is running
kubectl get pods -n mcp-hangar
kubectl logs -n mcp-hangar deploy/mcp-hangar-operator

# 4. Verify CRDs
kubectl get crd | grep mcp-hangar

# 5. Check provider status
kubectl get mcpproviders -A

Troubleshooting¶

"ModuleNotFoundError: No module named 'mcp_hangar.provider_manager'"¶

The provider_manager module was removed. See Deprecated patterns removed in v1.0.

"NameError: name 'RegistryFunctions' is not defined"¶

The old registry names were removed in v0.4.0. See Rebrand: registry to hangar.

"Unknown environment variable HANGAR_*"¶

v1.0 only reads MCP_* variables. See Environment variables.

CRD conflicts after operator upgrade¶

If old CRDs from the mcp.hangar.io API group remain, delete them manually:

kubectl delete crd mcpproviders.mcp.hangar.io
kubectl delete crd mcpprovidergroups.mcp.hangar.io
kubectl delete crd mcpdiscoverysources.mcp.hangar.io

Then reinstall CRDs from the updated chart.

Getting help¶

• GitHub Issues: https://github.com/mcp-hangar/mcp-hangar/issues
• Changelog: See CHANGELOG.md for the complete version history.
• Architecture: See ARCHITECTURE.md for system design documentation.