Skip to main content

Manage servers

Monitoring​

ToolHive provides visibility into the status of your MCP servers. You can check the status of running servers and view their logs using the ToolHive CLI.

Interactive dashboard

To monitor and operate servers from a single live view instead of chaining together thv list, thv logs, and other subcommands, run thv tui to launch the experimental terminal dashboard. It shows a real-time server list, streaming logs, a tool inspector, and a registry browser. Press ? for the full key map.

List running servers​

To see all currently running MCP servers:

thv list

This shows details about each running server, including its name, package (container image), status, URL for connecting clients, group, and when it was created.

To include stopped servers in the list:

thv list --all

View server logs​

To view logs for an MCP server, use the thv logs command. You can optionally follow the logs with the --follow option, which shows the most recent log entries and updates in real time.

Container logs​

For local servers, view the container logs:

thv logs <SERVER_NAME> [--follow]

Proxy logs​

All servers (both local and remote) run through a proxy process managed by ToolHive. To view the proxy logs instead of the container logs, use the --proxy flag:

thv logs <SERVER_NAME> --proxy [--follow]

For remote servers, the --proxy flag is required since there is no container to read logs from.

Alternatively, you can check the log files directly in the ToolHive application directory. The path depends on your platform:

  • macOS: ~/Library/Application Support/toolhive/logs/<SERVER_NAME>.log
  • Linux: ~/.local/share/toolhive/logs/<SERVER_NAME>.log
  • Windows: %LOCALAPPDATA%\toolhive\logs\<SERVER_NAME>.log

The specific log file path is displayed when you start a server with thv run.

Lifecycle management​

MCP servers can be started, stopped, restarted, and removed using the ToolHive CLI. The commands are similar to Docker commands, but they're designed to work with the ToolHive CLI and MCP servers.

Stop a server​

To stop a running MCP server:

thv stop <SERVER_NAME>

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. For remote servers, this terminates the proxy process but preserves the configuration.

Add the --group flag to stop all servers in a specific group:

thv stop --group <GROUP_NAME>

Add the --all flag to stop all running servers.

Restart a server​

To start a stopped MCP server and add it back to your configured clients:

thv start <SERVER_NAME>

For remote servers, restarting will:

  1. Recreate the proxy process
  2. Re-establish connection to the remote server
  3. Re-authenticate with the remote server (triggers new OAuth flow)

Add the --group flag to start all servers in a specific group:

thv start --group <GROUP_NAME>

Remove a server​

To remove an MCP server:

thv rm <SERVER_NAME>

This removes the container and cleans up the MCP server's entry in your configured clients. If the server is still running, it will be stopped as part of the removal. For remote servers, this removes the proxy process, configuration, and stored authentication tokens.

Add the --group flag to remove all servers in a specific group:

thv rm --group <GROUP_NAME>
note

If you use docker rm to remove an MCP container that ToolHive created, it won't clean up the MCP server's entry in your configured clients. Use thv rm to make sure the entry is removed.

Remote server authentication​

Remote servers with OAuth authentication will automatically refresh tokens when they expire during normal operation. However, starting a remote server always triggers a new OAuth authentication flow:

thv start <REMOTE_SERVER_NAME>

This will always prompt for re-authentication, even if valid tokens exist.

Check for and apply upgrades​

For MCP servers you ran from a registry entry (thv run <SERVER_NAME>), ToolHive can compare each workload's image and configuration against the registry's current entry and report when a newer version is available. This only works for registry-sourced workloads on the local runtime; remote servers and workloads run directly from an image reference report as not-registry-sourced.

note

Upgrade detection is not yet available for the Kubernetes operator.

Check for available upgrades​

The thv upgrade check command is an offline metadata comparison: it inspects each workload's image tag and configuration against the registry and never pulls images.

To see a summary table for every workload (including stopped ones):

thv upgrade check

Each row shows the workload's current image, the candidate image the registry reports, the count of new environment variables the candidate declares, and a posture marker if the candidate's transport or permission profile differs from the workload's current configuration. Possible statuses are up-to-date, upgrade-available, not-registry-sourced, server-not-found, and unknown.

For a detailed report on a single workload, pass its name:

thv upgrade check <SERVER_NAME>

The detailed report adds the registry server name, any new environment variables (with their descriptions and whether they're required), and the specific transport or permission profile changes between the running workload and the candidate.

You can also surface an upgrade column alongside thv list with an opt-in flag:

thv list --check-upgrades

The default thv list output is unchanged and performs no registry lookup, so it stays offline-friendly.

Apply an upgrade​

To upgrade a workload to the candidate image while preserving its configuration (environment variables, secrets, permission profile, transport, volumes, middleware), use thv upgrade apply:

thv upgrade apply <SERVER_NAME>

ToolHive resolves, verifies, and pulls the candidate image before touching the running workload, then stops the existing workload and starts a new one on the candidate image. There is no automatic rollback: if recreation fails after the existing workload is stopped, recovery is a forward operation. For an interactive session, the command prints what would change and prompts for confirmation before applying.

If the candidate declares new environment variables or secrets that the workload does not yet supply, pass them with --env or --secret:

thv upgrade apply <SERVER_NAME> --env NEW_FLAG=true --secret api-key,target=API_KEY

To preview the planned changes without applying them:

thv upgrade apply <SERVER_NAME> --dry-run

To skip the confirmation prompt (for example, in a script), pass --yes. In non-interactive shells the command runs non-interactively automatically and fails if any required value is missing.

Next steps​