Skip to main content

Secrets management

MCP servers often need secrets like API tokens, connection strings, and other sensitive parameters. ToolHive provides built-in secrets management features, letting you manage these values securely without exposing them in plaintext configuration files.

Secrets providers​

ToolHive supports multiple secret providers:

  • encrypted (default) - ToolHive encrypts secrets using a password that it stores in your operating system's keyring.
  • 1password - ToolHive retrieves secrets from a 1Password vault.

The encrypted provider is the default secrets provider. When you use a thv secret command for the first time, ToolHive prompts you for a password to encrypt and decrypt your secrets.

ToolHive stores the encryption password in your operating system's keyring (Keychain Access on macOS, dbus/Gnome Keyring on Linux). This means you don't need to enter it every time you use a thv secret command.

To explicitly use the encrypted provider (or switch back to it from another provider), run:

thv config secrets-provider encrypted

Manage secrets​

Create or update a secret​

The thv secret set command lets you create or update a secret in your secret store. You can set a secret interactively by running:

thv secret set <secret-name>

ToolHive prompts you to enter the secret value, and the input remains hidden for security.

Example:

thv secret set github
# Enter your GitHub personal access token when prompted

Alternatively, you can set a secret using standard input:

echo "MY_SECRET_VALUE" | thv secret set <secret-name>
Example

Create a secret named github and set its value to your GitHub authentication token using the GitHub CLI:

gh auth token | thv secret set github

List and view secrets​

To list the names of all secrets in your secret store without revealing their values:

thv secret list

To decrypt and view a secret's value:

thv secret get <secret-name>

Remove a secret​

To delete a secret when it's no longer needed:

thv secret delete <secret-name>

Reset your secret store​

ToolHive doesn't currently support changing the encryption password. If you need to reset your secret store, delete the encrypted secrets file and recreate your secrets.

First, remove the encryption password from the keyring:

thv secret reset-keyring

Then, delete the encrypted secrets file:

On macOS:

rm ~/Library/Application\ Support/toolhive/secrets_encrypted

On Linux:

rm ~/.config/toolhive/secrets_encrypted

Use secrets with MCP servers​

ToolHive can securely pass secrets to an MCP server when you run it. This lets the server access sensitive information without exposing it in plaintext.

To do this, use the --secret flag with the thv run command. The secret value is injected into the container as an environment variable.

thv run --secret <secret-name>,target=<ENV_VAR_NAME> <server-name>

Check the MCP server's documentation to find the expected environment variable names. For example, the GitHub MCP server expects the GitHub token to be passed as GITHUB_PERSONAL_ACCESS_TOKEN.

For MCP servers in the ToolHive registry, you can find the expected environment variable names in the server's registry entry:

thv registry info <server-name>

Example: GitHub API token​

This example shows how to set up a GitHub authentication token and use it with the GitHub MCP server:

  1. Set the secret:

    thv secret set github
    # Enter your GitHub personal access token when prompted

  2. Run the GitHub MCP server with the token:

    thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github

The GitHub MCP server now has access to your GitHub token and can make authenticated API requests.

Example: Multiple secrets​

You can provide multiple secrets to a server by using the --secret flag multiple times:

thv run \
  --secret github,target=GITHUB_TOKEN \
  --secret openai,target=OPENAI_API_KEY \
  multi-api-server

Example: 1Password secret​

To use a secret from 1Password with an MCP server, set the OP_SERVICE_ACCOUNT_TOKEN environment variable with your 1Password service account API token and reference the secret using the op:// URI format.

OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token> thv run \
  --secret op://MCPVault/slackbot/token,target=SLACK_BOT_TOKEN \
  --secret op://MCPVault/slackbot/team_id,target=SLACK_TEAM_ID \
  slack

This command retrieves the token and team_id fields from the slackbot item in the MCPVault vault and passes them to the slack MCP server as the SLACK_BOT_TOKEN and SLACK_TEAM_ID environment variables.

Troubleshooting​

Keyring access issues​

If you run into errors related to the system keyring:

  1. Make sure your system's keyring service is running

  2. Check that you have the necessary permissions

  3. On some Linux systems, you might need to install additional packages:

    # For Debian/Ubuntu
    sudo apt-get install gnome-keyring

    # For Fedora/RHEL
    sudo dnf install gnome-keyring

Secret not available to MCP server​

If your MCP server can't access a secret:

  1. Verify the secret exists:

    thv secret list

  2. Verify the secret value:

    thv secret get <secret-name>

  3. Check that you're using the correct secret name and target environment variable. Inspect the MCP server's expected environment variables in the registry:

    thv registry info <server-name>

  4. Inspect the server logs for any errors:

    thv logs <server-name>

Forgot encryption password​

If the keyring entry is lost or corrupted and you forget your encryption password, you won't be able to access your secrets. In this case, delete the encrypted secrets file and recreate your secrets.

Issues accessing 1Password secrets​

If you can't access 1Password secrets:

  1. Verify the OP_SERVICE_ACCOUNT_TOKEN environment variable is set:

    echo $OP_SERVICE_ACCOUNT_TOKEN

  2. Check that the token is valid and has the necessary permissions to access the vault and item.

  3. Make sure the secret reference URI is correct and matches the vault, item, and field names in 1Password.