Upgrade

Take a backup before every upgrade. A rollback across a database migration is possible only by restoring it.

Current versions: gateway 2.0.1, portal 2.0.1, credential broker 2.0.0, MCP servers and the adapter 2.0.0.

From 2.0.0 to 2.0.1

2.0.1 changes the gateway and the portal. The gateway fixes the tool list for clients on MCP 2026-07-28: with 2.0.0, Claude Code showed the server with no tools. The portal gets a new browser icon. The broker stays at 2.0.0. The changelogs list no change to policies or tool definitions, so there is nothing to approve again.

1. Update the bundle files (compose.yaml and the directories next to it) to the new version. Keep .env, certs/ and servers.yaml.

2. If .env sets MCP_GATEWAY_VERSION or MCP_PORTAL_VERSION, change them to 2.0.1. If it does not, the defaults of the new compose.yaml apply.

3. Pull and start:

   docker compose pull
   docker compose up -d

   With the offline packages, load the images of the new platform zip instead of docker compose pull (and keep PULL_POLICY=never).

Generated keys and passwords stay. openbao-unseal rewrites the OpenBao policy.

Order of components

When you change several components, deploy the broker and the gateway before the portal. The portal 2.x works only with gateway 2.x and broker 2.x. Then update the servers. In the bundle, one docker compose up -d recreates the changed services.

The realm is imported only when it does not exist. Later changes of keycloak/realm-mcp.json do not reach an existing realm: make them in the Keycloak console.

From 1.x to 2.0

2.0 is a breaking release. The gateway no longer reads servers, policy bundles or MCP_SERVER_* settings. Servers and systems are runtime data, added in the portal. There is no mutual TLS between gateway and server and no registration from a pipeline.

1. Back up the PostgreSQL databases of the gateway and the broker.

2. Broker. Give its AppRole the policy lines of secret/data/mcp/system-clients/* described in the broker README, step 1. Keep the BROKER_SYSTEMS_* settings of 1.x for the first start of 2.0.0. On that start the broker imports those systems into its database once, copies the OAuth client secrets to the new OpenBao path, and adopts the existing connections. After the first start, remove the settings. Without them nothing is imported: add the systems in the portal (Systems).

3. Gateway. Delete MCP_POLICY_*, MCP_REGISTRY_MODE, MCP_SERVER_* and certs/policies-main.public.pem from the configuration, and the volume that held /app/state. Stop the policy server for the gateway. Set MCP_ALLOWED_CLIENTS only if your AI clients are not claude-code and claude-ai. Every instance needs the same value.

4. Portal. 2.0 needs gateway 2.0.0 and broker 2.0.0 or newer. Deploy it after them. The identity provider must put auth_time, acr and amr into the tokens, because administration needs a fresh sign-in with a second factor.

5. MCP servers. Remove MCP_GATEWAY_POLICY_DATA_URL, MCP_GATEWAY_TLS_NAME, MCP_INTERNAL_URL, MCP_TLS_TRUSTSTORE and the Redis service of the old compose file. Set MCP_GATEWAY_JWKS_URI. The server refuses to start while an old setting is left. Servers that you built yourself need the starter 4.0.0.

6. Add each server again in the portal by its address (Servers). Manifests and approvals stored under the same server id are taken again, but a 1.x manifest has no policies. Approve the connection, then the policies, then every tool.

7. Recreate the scope mapping. Group names are derived from the risk (mcp-<system>-read, -write, -destructive), and resource grants are scope mapping entries, not group names inside a bundle.

What you approve again

Upgrade	Approve again
2.0.0 to 2.0.1	Nothing.
1.x to 2.0	For every server: the connection (fingerprint), the policies and the tools. Every tool waits, read-only ones too.
A server image that changed its policies or tools	The changed policies or tools. The server stays pending_approval and its tools are hidden until you approve.
A server that got a new certificate	The new fingerprint (certificate_changed), unless the certificate chains to a trusted CA.

Check after the upgrade

1. Run docker compose ps. Every service is healthy.
2. Open the portal, Administration, Servers. No server is waiting for approval unless you expect it.
3. Call one tool from an AI client.