ToolHive Tutorial: Securely Deploy and Manage MCP Servers

Pawan Jaiswal

Pawan Jaiswal

— 3 min read
ToolHive Tutorial: Securely Deploy and Manage MCP Servers
ToolHive Tutorial: Securely Deploy and Manage MCP Servers

In this blog, we're delving into ToolHive, a small tool that makes managing and deploying MCP servers remarkably simple and safe. ToolHive transforms your development process by integrating container security and configuration automation, regardless of whether you're using Cursor, GitHub Copilot, or other tools. Let's install and run it on a brand-new Ubuntu virtual machine. Now let's begin!

Prefer watching instead of reading? Here’s a quick video guide

Requirements

ToolHive uses containerization, so make sure you have Docker or Podman installed. Here I'll use Docker. Run the following commands to install Docker if you haven't already:

sudo apt update
sudo apt install -y docker.io
sudo systemctl enable docker
sudo systemctl start docker

"Let's make sure Docker is operating."

docker --version

Setting Up ToolHive

"ToolHive is a CLI tool that runs on Go. Downloading the binary or building from source will allow you to install it. We will build it from source for this demonstration.

sudo apt install -y golang git make
git clone https://github.com/stacklok/toolhive.git
cd toolhive
go build ./cmd/thv
sudo cp thv /usr/local/bin/

"Let's make sure it was installed correctly."

thv version

Configuring Your Initial MCP Server

Let's now use ToolHive to launch our first MCP server. In order for it to connect to clients that are compatible, first enable auto-discovery.

thv config auto-discovery true

"Now launch the Fetch MCP server—this tool enables LLMs to retrieve content from websites."

thv run fetch

You'll observe the server booting up and the container being pulled. You can use this to check servers that are currently in use:

thv list

Use Case: GitHub Token with Encrypted Secrets

"As an example, let's try configuring a GitHub MCP server that needs an authentication token. We will use ToolHive's encrypted provider to safely handle secrets.

thv config secrets-provider encrypted
thv secret set github

You will be asked to enter your GitHub token. Let's launch the GitHub MCP server after it is finished:

thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github

Examine the Registry

ToolHive has an integrated MCP registry. You can look through and find information about the servers that are available here:

thv registry list
thv search github
thv registry info github

Configuring a Custom MCP Server

Now let's use an image to run a custom MCP server. As an illustration:

thv run --transport sse --name myserver --port 8080 my-mcp-image:latest -- some-args

"ToolHive adds labels, builds a proxy on a random port, and securely wraps your container."

Utilising Package Managers to Run MCP

Protocol schemes such as uvx://, npx://, and go:// are supported by ToolHive. Let's launch a Python-based MCP straight from uvx:

thv run uvx://awslabs.core-mcp-server@latest

"Or a server built with Node.js:"

thv run npx://@pulumi/mcp-server@latest

"Or even local Go projects:"

cd my-go-mcp-project
thv run go://.

Personalize Permissions

Using JSON profiles, ToolHive enables permission customisation. Example:

{
  "read": ["/var/run/mcp.sock"],
  "network": {
    "outbound": {
      "allow_host": ["localhost", "google.com"],
      "allow_port": [80, 443]
    }
  }
}

"Save it as profile.json, then use it as follows:"

thv run --permission-profile profile.json fetch

Deployment of Kubernetes (Preview)

ToolHive now allows you to use an Operator to run MCP servers in Kubernetes. Create a Kind cluster and follow the instructions in the repository if you want to test this out locally.

Bonus: Manual Client Enrollment

"You can manually register a client if auto-discovery isn't functioning:"

thv config register-client copilot
thv config list-registered-clients

Final Remarks

This is a comprehensive tutorial on using ToolHive! As you can see, it's an effective tool for deploying MCP servers in a safe and repeatable manner. ToolHive can help you with running custom tools or integrating with GitHub Copilot.

Read more