stacklok · danbarr · Jun 24, 2025 · Jun 24, 2025 · Jun 24, 2025 · Jun 24, 2025
diff --git a/docs/toolhive/guides-cli/install.mdx b/docs/toolhive/guides-cli/install.mdx
@@ -161,7 +161,7 @@ On Windows, you must stop all running MCP servers before upgrading ToolHive,
 otherwise the upgrade will fail because Windows locks the executable while it
 runs.
 
-Run `thv stop <server-name>` to stop each server. After you complete the
+Run `thv stop --all` to stop all running servers. After you complete the
 upgrade, restart them using `thv restart <server-name>`.
 
 :::
@@ -247,7 +247,7 @@ To uninstall ToolHive:
    # List running servers
    thv list
    # Stop and remove each server
-   thv stop <server-name>
+   thv stop --all
    thv rm <server-name>
    ```
 
@@ -262,39 +262,49 @@ To uninstall ToolHive:
    rm -rf ~/Library/Application\ Support/toolhive/
    # Linux:
    rm -rf ~/.config/toolhive/
+   # Windows:
+   Remove-Item "$env:LOCALAPPDATA\toolhive" -Recurse -Force
    ```
 
 3. Remove the ToolHive CLI:
 
 {/* prettier-ignore */}
    <Tabs groupId='installer' queryString='installer'>
      <TabItem value='homebrew' label='Homebrew (macOS)' default>
+
        If you installed ToolHive via Homebrew, uninstall it with:
 
        ```bash
        brew uninstall thv
        ```
+
      </TabItem>
      <TabItem value='winget' label='WinGet (Windows)'>
+
        If you installed ToolHive via WinGet, uninstall it with:
 
        ```bash
        winget uninstall stacklok.thv
        ```
+
      </TabItem>
      <TabItem value='binary' label='Pre-compiled binaries'>
+
        Delete the binary from your PATH:
 
        ```bash
        sudo rm /usr/local/bin/thv
        ```
+
      </TabItem>
      <TabItem value='source' label='Build from source'>
+
        Remove the binary from your `$GOPATH`:
 
        ```bash
        rm $(go env GOPATH)/bin/thv
        ```
+
      </TabItem>
 
    </Tabs>
@@ -353,9 +363,7 @@ To resolve this:
 1. Stop all running MCP servers:
 
    ```powershell
-   thv list
-   thv stop <server-name>
-   # repeat for each server
+   thv stop --all
    ```
 
 2. After stopping all servers, run the upgrade command again:
@@ -371,6 +379,7 @@ To resolve this:
 4. Restart your MCP servers:
 
    ```powershell
+   thv list --all
    thv restart <server-name>
    # repeat for each server
    ```

diff --git a/docs/toolhive/guides-cli/manage-mcp-servers.md b/docs/toolhive/guides-cli/manage-mcp-servers.md
@@ -60,12 +60,14 @@ To stop a running MCP server:
 thv stop <server-name>
 ```
 
-This stops the server and the associated proxy process but keeps the container
-for future use.
+This stops the server and the associated proxy process, removes the MCP server's
+entry from your configured clients, but keeps the container for future use.
+
+Add the `--all` flag to stop all running servers.
 
 ### Restart a server
 
-To restart a stopped MCP server:
+To restart a stopped MCP server and add it back to your configured clients:
 
 ```bash
 thv restart <server-name>

diff --git a/docs/toolhive/guides-cli/secrets-management.mdx b/docs/toolhive/guides-cli/secrets-management.mdx
@@ -15,84 +15,82 @@ configuration files.
 
 ## Secrets providers
 
-ToolHive supports multiple secret providers:
+ToolHive supports multiple secret providers to fit different security and
+workflow requirements:
 
-- `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.
+- `encrypted` - ToolHive encrypts secrets using a password stored in your
+  operating system's keyring
+- `1password` - ToolHive retrieves secrets from a 1Password vault
 
-<Tabs groupId='secrets-provider' queryString='secrets-provider'>
-  <TabItem value='encrypted' label='Encrypted (default)' default>
+You can use only one provider at a time. To select your preferred provider, run:
 
-The `encrypted` provider is the default secrets provider. When you use a
-[`thv secret`](../reference/cli/thv_secret.md) command for the first time,
-ToolHive prompts you for a password to encrypt and decrypt your secrets.
+```bash
+thv secret setup
+```
 
-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`](../reference/cli/thv_secret.md) command.
+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.
 
-To explicitly use the `encrypted` provider (or switch back to it from another
-provider), run:
+<Tabs groupId='secrets-provider'>
+  <TabItem value='encrypted' label='Encrypted' default>
 
-```bash
-thv config secrets-provider encrypted
-```
+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`](../reference/cli/thv_secret.md) command.
 
   </TabItem>
   <TabItem value='1password' label='1Password'>
 
 :::note
 
-The `list`, `set`, and `delete` operations aren't currently supported with
-1Password.
-
-You can retrieve secrets using the
-[`thv secret get`](../reference/cli/thv_secret_get.md) command and the
-`--secret` parameter for [`thv run`](../reference/cli/thv_run.md), but the
-secret must already exist in 1Password.
+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 more functionality, please
+If you'd like to see write operations added, please
 [open an issue](https://github.com/stacklok/toolhive/issues) or join the
 `#toolhive-developers` channel in [Discord](https://discord.gg/stacklok).
-Contributions are also welcome!
+Contributions are welcome!
 
 :::
 
 To use 1Password as your secrets provider, set up a 1Password service account.
 For detailed instructions, see the
 [1Password documentation](https://developer.1password.com/docs/service-accounts/get-started#create-a-service-account).
 
-Next, set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable to the 1Password
-service account's API token, which is displayed during the service account
-creation process. This token is required for all
-[`thv secret`](../reference/cli/thv_secret.md) commands.
+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`](../reference/cli/thv_secret.md)
+commands:
 
 ```bash
 export OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token>
 ```
 
-Then, set 1Password as your ToolHive secrets provider:
+Then, run `thv secret setup` and select `1password` when prompted.
 
-```bash
-thv config secrets-provider 1password
-```
-
-To reference a secret, use the
+To reference a secret from 1Password, use the
 [1Password secret reference](https://developer.1password.com/docs/cli/secret-reference-syntax)
 URI format:
 
 ```text
 op://<vault-name>/<item-name>/[section-name/]<field-name>
 ```
 
-For example, to retrieve a secret named `github` from the `MCPVault` vault:
+For example, to retrieve the `password` field from the `github` item in the
+`MCPVault` vault:
 
 ```bash
 thv secret get op://MCPVault/github/password
 ```
 
+Run [`thv secret list`](../reference/cli/thv_secret_list.md) to see all secrets
+accessible to your service account, along with their URIs.
+
   </TabItem>
 </Tabs>
 
@@ -172,17 +170,32 @@ thv secret reset-keyring
 
 Then, delete the encrypted secrets file:
 
-On macOS:
+<Tabs groupId='os'>
+  <TabItem value='macos' label='macOS' default>
+
+    ```bash
+    rm ~/Library/Application\ Support/toolhive/secrets_encrypted
+    ```
 
-```bash
-rm ~/Library/Application\ Support/toolhive/secrets_encrypted
-```
+  </TabItem>
+  <TabItem value='linux' label='Linux'>
 
-On Linux:
+    ```bash
+    rm ~/.config/toolhive/secrets_encrypted
+    ```
 
-```bash
-rm ~/.config/toolhive/secrets_encrypted
-```
+  </TabItem>
+  <TabItem value='windows' label='Windows'>
+
+    ```powershell
+    Remove-Item "$env:LOCALAPPDATA\toolhive\secrets_encrypted"
+    ```
+
+  </TabItem>
+</Tabs>
+
+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
 
@@ -328,7 +341,15 @@ If you can't access 1Password secrets:
    ```
 
 2. Check that the token is valid and has the necessary permissions to access the
-   vault and item.
+   vault and item:
+
+   ```bash
+   thv secret list
+   ```
 
 3. Make sure the secret reference URI is correct and matches the vault, item,
-   and field names in 1Password.
+   and field names in 1Password:
+
+   ```bash
+   thv secret get op://<vault-name>/<item-name>/[section-name/]<field-name>
+   ```
diff --git a/docs/toolhive/reference/cli/thv_config.md b/docs/toolhive/reference/cli/thv_config.md
@@ -27,7 +27,6 @@ The config command provides subcommands to manage application configuration sett
 * [thv config list-registered-clients](thv_config_list-registered-clients.md)	 - List all registered MCP clients
 * [thv config register-client](thv_config_register-client.md)	 - Register a client for MCP server configuration
 * [thv config remove-client](thv_config_remove-client.md)	 - Remove a client from MCP server configuration
-* [thv config secrets-provider](thv_config_secrets-provider.md)	 - Set the secrets provider type
 * [thv config set-ca-cert](thv_config_set-ca-cert.md)	 - Set the default CA certificate for container builds
 * [thv config set-registry-url](thv_config_set-registry-url.md)	 - Set the MCP server registry URL
 * [thv config unset-ca-cert](thv_config_unset-ca-cert.md)	 - Remove the configured CA certificate

diff --git a/docs/toolhive/reference/cli/thv_config_secrets-provider.md b/docs/toolhive/reference/cli/thv_config_secrets-provider.md
diff --git a/docs/toolhive/reference/cli/thv_run.md b/docs/toolhive/reference/cli/thv_run.md
@@ -46,6 +46,7 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...]
   -h, --help                                  help for run
       --host string                           Host for the HTTP proxy to listen on (IP or hostname) (default "127.0.0.1")
       --image-verification string             Set image verification mode (warn, enabled, disabled) (default "warn")
+      --isolate-network                       Isolate the container network from the host (default: false)
       --name string                           Name of the MCP server (auto-generated from image if not provided)
       --oidc-audience string                  Expected audience for the token
       --oidc-client-id string                 OIDC client ID
@@ -60,9 +61,9 @@ thv run [flags] SERVER_OR_IMAGE_OR_PROTOCOL [-- ARGS...]
       --permission-profile string             Permission profile to use (none, network, or path to JSON file) (default "network")
       --port int                              Port for the HTTP proxy to listen on (host port)
       --secret stringArray                    Specify a secret to be fetched from the secrets manager and set as an environment variable (format: NAME,target=TARGET)
-      --target-host string                    Host to forward traffic to (only applicable to SSE transport) (default "127.0.0.1")
-      --target-port int                       Port for the container to expose (only applicable to SSE transport)
-      --transport string                      Transport mode (sse or stdio) (default "stdio")
+      --target-host string                    Host to forward traffic to (only applicable to SSE or Streamable HTTP transport) (default "127.0.0.1")
+      --target-port int                       Port for the container to expose (only applicable to SSE or Streamable HTTP transport)
+      --transport string                      Transport mode (sse, streamable-http or stdio) (default "stdio")
   -v, --volume stringArray                    Mount a volume into the container (format: host-path:container-path[:ro])
 ```
 

diff --git a/docs/toolhive/reference/cli/thv_secret.md b/docs/toolhive/reference/cli/thv_secret.md
@@ -24,7 +24,8 @@ The secret command provides subcommands to set, get, delete, and list secrets.
 * [thv secret delete](thv_secret_delete.md)	 - Delete a secret
 * [thv secret get](thv_secret_get.md)	 - Get a secret
 * [thv secret list](thv_secret_list.md)	 - List all available secrets
-* [thv secret provider](thv_secret_provider.md)	 - Configure the secrets provider
+* [thv secret provider](thv_secret_provider.md)	 - Configure the secrets provider directly
 * [thv secret reset-keyring](thv_secret_reset-keyring.md)	 - Reset the keyring secret
 * [thv secret set](thv_secret_set.md)	 - Set a secret
+* [thv secret setup](thv_secret_setup.md)	 - Set up secrets provider
 
diff --git a/docs/toolhive/reference/cli/thv_secret_provider.md b/docs/toolhive/reference/cli/thv_secret_provider.md
@@ -1,9 +1,10 @@
 ## thv secret provider
 
-Configure the secrets provider
+Configure the secrets provider directly
 
 ### Synopsis
 
+For most users, it is recommended to use "thv secret setup" instead.
 Configure the secrets provider.
 Valid secrets providers are:
   - encrypted: Full read-write secrets provider