From 83e20b98bda02cef31f4bc3a2df249c0f8ebaa0f Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Thu, 14 Aug 2025 17:05:08 +0000 Subject: [PATCH 1/3] docs: add runconfig import/export documentation Add comprehensive documentation for the runconfig import/export functionality introduced in ToolHive v0.2.1: - Add 'Share and reuse server configurations' section to run-mcp-servers.mdx - Explain export/import workflow with practical examples - Document configuration override capabilities - Reference new section in quickstart tutorial Co-authored-by: Chris Burns --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 60 ++++++++++++++++++++ docs/toolhive/tutorials/quickstart-cli.mdx | 2 + 2 files changed, 62 insertions(+) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index e4ee541a..05a4eeae 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -447,6 +447,66 @@ thv run uvx://some-package thv run --ca-cert /path/to/special-ca.crt uvx://other-package ``` +## Share and reuse server configurations + +ToolHive allows you to export a server's configuration and run servers using +previously exported configurations. This is useful for: + +- Sharing server setups with team members +- Creating backups of complex configurations +- Running identical server instances across different environments + +### Export a server configuration + +To export a running server's configuration to a file, use the +[`thv export`](../reference/cli/thv_export.md) command: + +```bash +thv export +``` + +For example, to export the configuration of a running server named "fetch": + +```bash +thv export fetch ./fetch-config.json +``` + +This creates a JSON file containing all the server's configuration, including: +- Container image and version +- Environment variables and secrets +- Volume mounts and permissions +- Network settings +- Transport configuration + +### Run a server from an exported configuration + +To run a server using a previously exported configuration, use the +[`thv run`](../reference/cli/thv_run.md) command with the `--from-config` flag: + +```bash +thv run --from-config +``` + +For example, to run a server using the exported configuration: + +```bash +thv run --from-config ./fetch-config.json +``` + +This creates a new server instance with identical settings to the original. + +:::info +When running from a configuration file, you can still override specific +settings using command-line flags. For example: + +```bash +thv run --from-config ./fetch-config.json --name custom-fetch --proxy-port 8080 +``` + +This runs the server with the exported configuration but uses a custom name and +port. +::: + ## Next steps See [Monitor and manage MCP servers](./manage-mcp-servers.md) to monitor and diff --git a/docs/toolhive/tutorials/quickstart-cli.mdx b/docs/toolhive/tutorials/quickstart-cli.mdx index 5747451b..36f2cf7b 100644 --- a/docs/toolhive/tutorials/quickstart-cli.mdx +++ b/docs/toolhive/tutorials/quickstart-cli.mdx @@ -293,6 +293,8 @@ server. Here are some next steps to explore: servers that require authentication - Explore [custom permissions](../guides-cli/custom-permissions.mdx) for MCP servers +- Learn how to [share and reuse server configurations](../guides-cli/run-mcp-servers.mdx#share-and-reuse-server-configurations) + using the export and import functionality - Set up [shell completion](../guides-cli/install.mdx#enable-shell-completion) to make ToolHive commands easier to use - Learn how to [upgrade ToolHive](../guides-cli/install.mdx#upgrade-toolhive) From 9fd3b9988f0b73ef6f0fc96fb142f4159772aee0 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Tue, 26 Aug 2025 09:30:02 -0400 Subject: [PATCH 2/3] Add note about secrets references, fix formatting Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 15 ++++++++++----- docs/toolhive/tutorials/quickstart-cli.mdx | 3 ++- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 05a4eeae..85cb7e5c 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -458,7 +458,7 @@ previously exported configurations. This is useful for: ### Export a server configuration -To export a running server's configuration to a file, use the +To export a running server's configuration to a file, use the [`thv export`](../reference/cli/thv_export.md) command: ```bash @@ -472,8 +472,9 @@ thv export fetch ./fetch-config.json ``` This creates a JSON file containing all the server's configuration, including: + - Container image and version -- Environment variables and secrets +- Environment variables and secrets references - Volume mounts and permissions - Network settings - Transport configuration @@ -493,11 +494,14 @@ For example, to run a server using the exported configuration: thv run --from-config ./fetch-config.json ``` -This creates a new server instance with identical settings to the original. +This creates a new server instance with identical settings to the original. If +the original server used secrets, you must have the same secrets available in +your ToolHive secrets store. :::info -When running from a configuration file, you can still override specific -settings using command-line flags. For example: + +When running from a configuration file, you can still override specific settings +using command-line flags. For example: ```bash thv run --from-config ./fetch-config.json --name custom-fetch --proxy-port 8080 @@ -505,6 +509,7 @@ thv run --from-config ./fetch-config.json --name custom-fetch --proxy-port 8080 This runs the server with the exported configuration but uses a custom name and port. + ::: ## Next steps diff --git a/docs/toolhive/tutorials/quickstart-cli.mdx b/docs/toolhive/tutorials/quickstart-cli.mdx index 36f2cf7b..b98fce95 100644 --- a/docs/toolhive/tutorials/quickstart-cli.mdx +++ b/docs/toolhive/tutorials/quickstart-cli.mdx @@ -293,7 +293,8 @@ server. Here are some next steps to explore: servers that require authentication - Explore [custom permissions](../guides-cli/custom-permissions.mdx) for MCP servers -- Learn how to [share and reuse server configurations](../guides-cli/run-mcp-servers.mdx#share-and-reuse-server-configurations) +- Learn how to + [share and reuse server configurations](../guides-cli/run-mcp-servers.mdx#share-and-reuse-server-configurations) using the export and import functionality - Set up [shell completion](../guides-cli/install.mdx#enable-shell-completion) to make ToolHive commands easier to use From 0d5acd77f19fcdb4a017ca4efa8fcb9ae8dbec44 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Tue, 26 Aug 2025 10:13:57 -0400 Subject: [PATCH 3/3] Remove incorrect note about overriding settings Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- docs/toolhive/guides-cli/run-mcp-servers.mdx | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 85cb7e5c..27d3b9d4 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -498,20 +498,6 @@ This creates a new server instance with identical settings to the original. If the original server used secrets, you must have the same secrets available in your ToolHive secrets store. -:::info - -When running from a configuration file, you can still override specific settings -using command-line flags. For example: - -```bash -thv run --from-config ./fetch-config.json --name custom-fetch --proxy-port 8080 -``` - -This runs the server with the exported configuration but uses a custom name and -port. - -::: - ## Next steps See [Monitor and manage MCP servers](./manage-mcp-servers.md) to monitor and