Skip to main content
The database stores encrypted credentials, not their encryption key. Preserve the original key during upgrades; if it is permanently lost, users must bind again. This guide covers personal credentials and personal upstream OAuth. Database mode no longer generates a local key automatically. Without MCPHUB_CREDENTIAL_ENCRYPTION_KEY or an existing valid .credentials.key file, binding saves fail, but the service can still start. Environment keys take precedence over files. Existing files remain supported; JSON mode still supports automatic key generation.

​
Choose your path

​
Working deployment: preserve the key

  1. Back up the database and key separately. Keep the old container until verification is complete.
  2. Preserve the existing environment key. If using a file, copy it from the old container and configure its Base64 value as MCPHUB_CREDENTIAL_ENCRYPTION_KEY. Do not generate a replacement key.
  3. Upgrade the image, retaining other deployment settings. All instances sharing the database must use the same key.
  4. Verify MCP calls with existing bindings, personal OAuth connections, and new binding saves.
Copy the key from the current Docker default path:
The filename is the effective settings path plus .credentials.key. Legacy deployments may use /app/mcp_settings.json.credentials.key; custom deployments follow MCPHUB_SETTING_PATH. Adjust the container name and path. Stopped containers can also be copied from until removed. Adding a directory mount does not migrate the existing file. Add this entry to the existing Compose service’s environment mapping:
Supply the original value through your deployment platform or an access-restricted, untracked Compose .env file. For docker run, use --env-file with MCPHUB_CREDENTIAL_ENCRYPTION_KEY=<original-base64-value>. Keep the key outside the container for future deployments.

​
Upgrade failed: original key is available

Pause binding changes and recover the key from the previous environment configuration, old container, mounted directory, or backup. Restore its value as MCPHUB_CREDENTIAL_ENCRYPTION_KEY on every instance, restart, and verify MCP calls. Alternatively, restore the original key file with mode 0600 and persist its directory; remove any incorrect environment override. The original key restores bindings encrypted with it. Any bindings saved with another key during recovery must be replaced or reauthorized.

​
Original key lost: reset bindings

A new key cannot decrypt old data. Rolling back the image or restoring only the database will not help. Back up the database, then choose one of the following options. Generate a new key once, save it in deployment secrets, and configure the same MCPHUB_CREDENTIAL_ENCRYPTION_KEY on every instance. If a new persistent key is already configured, retain it:

​
Option 1: users replace their own bindings

Configure the new key and restart all instances. Users must submit all personal credential values again, or delete the old binding first. Personal OAuth users must disconnect and authorize again. Verify tool calls afterward. If the dashboard cannot load the old binding, use these APIs to delete the current user’s binding, then bind again: Use dashboard authentication and URL-encode the server name. MCP bearer keys cannot manage bindings. An administrator’s session also acts only on that administrator’s own bindings.

​
Option 2: administrator clears all bindings

Use this when all users will bind again. This deletes every user’s personal credentials, personal OAuth tokens, client registration data, and pending flows in the table, including any bindings already restored. User accounts and server definitions are unaffected.
  1. Stop all MCPHub instances sharing the database to prevent concurrent writes and clear cached runtimes. Direct SQL does not emit application invalidation events.
  2. Back up the database, confirm the target database and schema, and inspect SELECT COUNT(*) FROM credential_bindings;.
  3. Run the following SQL and check that no rows remain:
    Execute COMMIT; separately after checking, or ROLLBACK; if anything is unexpected. Keep the table structure. After commit, restoring rows requires a backup; decrypting them still requires the original key.
  4. Confirm every instance has the same persistent key, then start the service. An empty table does not re-enable automatic key generation.
  5. All users must enter personal credentials or authorize OAuth again, then verify tool calls.
Neither reset option can revoke old OAuth tokens that cannot be read. Users should revoke obsolete grants through the upstream service when needed.

​
Future backups

Back up the database and key separately. Preserve the key during upgrades, scaling, and migration. Normal configuration exports exclude personal bindings and the key. In JSON mode, persist the settings file and its .credentials.json and .credentials.key files, or use a persistent environment key. See Docker Setup and Per-user Credentials.