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 secrets providers to fit different security and workflow requirements:

encrypted - ToolHive encrypts secrets using a password stored in your operating system's keyring
1password - ToolHive retrieves secrets from a 1Password vault

You can use only one provider at a time. To select your preferred provider, run:

thv secret setup

If you plan to use 1Password, first set up a 1Password service account and obtain an API token. See the 1Password tab below for details.

Encrypted
1Password

When you select the encrypted provider, ToolHive prompts you to create an encryption password that protects your secrets.

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

note

The 1Password provider is read-only. You can list and view secrets, but you can't create or delete them through ToolHive. Secrets must already exist in your 1Password vault.

If you'd like to see write operations added, please open an issue or join the #toolhive-developers channel in Discord. Contributions are welcome!

To use 1Password as your secrets provider, set up a 1Password service account. For detailed instructions, see the 1Password documentation.

Next, set the OP_SERVICE_ACCOUNT_TOKEN environment variable to your service account's API token (displayed during the service account creation process). This token is required for all thv secret commands:

export OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token>

Then, run thv secret setup and select 1password when prompted.

To reference a secret from 1Password, use the 1Password secret reference URI format:

op://<vault-name>/<item-name>/[section-name/]<field-name>

For example, to retrieve the password field from the github item in the MCPVault vault:

thv secret get op://MCPVault/github/password

Run thv secret list to see all secrets accessible to your service account, along with their URIs.

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:

macOS
Linux
Windows

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

rm ~/.config/toolhive/secrets_encrypted

Remove-Item "$env:LOCALAPPDATA\toolhive\secrets_encrypted"

The next time you run a thv secret command, ToolHive prompts you to create a new encryption password and starts with a fresh secret store.

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:

Set the secret:

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

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:

Make sure your system's keyring service is running
Check that you have the necessary permissions

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:

Verify the secret exists:
```
thv secret list
```
Verify the secret value:
```
thv secret get <secret-name>
```
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>
```
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:

Verify the OP_SERVICE_ACCOUNT_TOKEN environment variable is set:
```
echo $OP_SERVICE_ACCOUNT_TOKEN
```
Check that the token is valid and has the necessary permissions to access the vault and item:
```
thv secret list
```
Make sure the secret reference URI is correct and matches the vault, item, and field names in 1Password:
```
thv secret get op://<vault-name>/<item-name>/[section-name/]<field-name>
```

Secrets providers​

Manage secrets​

Create or update a secret​

List and view secrets​

Remove a secret​

Reset your secret store​

Use secrets with MCP servers​

Example: GitHub API token​

Example: Multiple secrets​

Example: 1Password secret​

Related information​

Troubleshooting​

Keyring access issues​

Secret not available to MCP server​

Forgot encryption password​

Issues accessing 1Password secrets​