Skip to content

Commit c0c7051

Browse files
danbarrdanbarr
committed
Switch quickstarts to toolhive-doc-mcp server
Use toolhive-doc-mcp as the example server in the CLI, UI, and K8s quickstarts so new users discover the docs MCP server early. Each quickstart points readers at the hosted toolhive-doc-mcp-remote variant as an alternative to running the container locally. Other fixes captured along the way: - Refresh CLI sample output for thv v0.27 (TYPE column in registry list, qualified io.github.stacklok/<name> names, GROUP and CREATED columns in thv list, JSON log format in thv run). - Replace the K8s remote fetch YAML with an inline MCPServer manifest. - Correct the K8s cleanup selector from app.kubernetes.io/name to app.kubernetes.io/instance; the former never matched any pod. - Drop misleading provenance verification bullet; verification is opt-in via --image-verification. - Tighten future tense and passive voice in prose we touched.
1 parent 0437431 commit c0c7051

3 files changed

Lines changed: 147 additions & 100 deletions

File tree

‎docs/toolhive/guides-cli/quickstart.mdx‎

Lines changed: 58 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ schema_type: tutorial
77

88
In this tutorial, you'll install the ToolHive command-line application and run
99
your first MCP server. By the end, you'll have a working MCP server that can
10-
fetch content from websites and be used by AI applications like GitHub Copilot
11-
or Cursor.
10+
answer questions about ToolHive and be used by AI applications like GitHub
11+
Copilot or Cursor.
1212

1313
## What you'll learn
1414

@@ -104,14 +104,19 @@ thv registry list
104104
You'll see output similar to this:
105105

106106
```text
107-
NAME DESCRIPTION TIER STARS PULLS
108-
atlassian Model Context Protocol (MCP) server for Atlassian product... Community 2194 7789
109-
fetch A Model Context Protocol server that provides web content... Community 56714 9078
110-
github The GitHub MCP Server provides seamless integration with ... Official 16578 5000
111-
notion Official Notion MCP server. Official 2358 1109
107+
NAME TYPE DESCRIPTION TIER STARS PULLS
108+
io.github.stacklok/atlassian container Connect to Atlassian products like Confluence, ... Community 5002
109+
io.github.stacklok/fetch container A Model Context Protocol server that provides ... Community 56714
110+
io.github.stacklok/github container The GitHub MCP Server provides seamless integr... Official 16578
111+
io.github.stacklok/notion container Official Notion MCP server. Official 2358
112+
io.github.stacklok/toolhive-doc-mcp container Search ToolHive docs for help with using and c... Official 3
113+
io.github.stacklok/toolhive-doc-mcp-remote remote Search ToolHive docs for help with using and c... Official 3
112114
...
113115
```
114116

117+
The `TYPE` column shows whether the server runs as a local `container` or is a
118+
hosted `remote` endpoint that ToolHive proxies to.
119+
115120
This shows all the MCP servers available in the ToolHive registry.
116121

117122
:::info[What's happening?]
@@ -122,48 +127,38 @@ to help you find and launch servers.
122127

123128
:::
124129

125-
For this tutorial, you'll use the "fetch" server, which is a simple MCP server
126-
that lets AI agents get the contents of a website. To learn more about the
127-
server before running it, run:
130+
For this tutorial, you'll use the `toolhive-doc-mcp` server, which lets AI
131+
agents search the ToolHive documentation. To learn more about the server before
132+
running it, run:
128133

129134
```bash
130-
thv registry info fetch
135+
thv registry info toolhive-doc-mcp
131136
```
132137

133138
This shows you detailed information about the server, including what tools it
134139
provides and any configuration options.
135140

136-
## Step 3: Run the Fetch MCP server
141+
## Step 3: Run the toolhive-doc-mcp server
137142

138-
Now, run the Fetch server:
143+
Now, run the server:
139144

140145
```bash
141-
thv run fetch
146+
thv run toolhive-doc-mcp
142147
```
143148

144-
ToolHive will pull the container image and start the server. You'll see output
145-
similar to this:
149+
ToolHive pulls the container image and starts the server in the background.
150+
You'll see a log line similar to this:
146151

147152
```text
148-
8:41AM INF MCP server ghcr.io/stackloklabs/gofetch/server:latest is verified successfully
149-
8:41AM INF Image ghcr.io/stackloklabs/gofetch/server:latest has 'latest' tag, pulling to ensure we have the most recent version...
150-
8:41AM INF Pulling image: ghcr.io/stackloklabs/gofetch/server:latest
151-
Pulling from stackloklabs/gofetch/server: latest
152-
Digest: sha256:b9cbe3a8367f39e584d3fdd96d9c5046643c5f4798c3372b0c9049ece202cdef
153-
Status: Image is up to date for ghcr.io/stackloklabs/gofetch/server:latest
154-
8:41AM INF Successfully pulled image: ghcr.io/stackloklabs/gofetch/server:latest
155-
8:41AM INF Using target port: 15266
156-
8:41AM INF Logging to: ~/Library/Application Support/toolhive/logs/fetch.log
157-
8:41AM INF MCP server is running in the background (PID: 16834)
158-
8:41AM INF Use 'thv stop fetch' to stop the server
153+
{"time":"2026-05-18T09:49:14-04:00","level":"INFO","msg":"logging to","path":"~/Library/Application Support/toolhive/logs/toolhive-doc-mcp.log"}
159154
```
160155

156+
The full server logs are written to the file shown in the `logging to` line.
157+
161158
:::info[What's happening?]
162159

163160
When you run an MCP server, ToolHive:
164161

165-
- Verifies the MCP server image provenance (if attestation information is
166-
available in the registry)
167162
- Downloads the container image
168163
- Sets up the container with the necessary security settings and starts it in
169164
the background
@@ -172,6 +167,17 @@ When you run an MCP server, ToolHive:
172167

173168
:::
174169

170+
:::tip[Prefer not to run a container?]
171+
172+
ToolHive also ships a hosted version of the docs server. Run
173+
`thv run toolhive-doc-mcp-remote` instead to connect to the hosted endpoint at
174+
`https://toolhive-doc-mcp.stacklok.com/mcp` without pulling an image. ToolHive
175+
sets up the same kind of proxy, so the rest of this tutorial works the same way,
176+
but commands that reference the workload name should use
177+
`toolhive-doc-mcp-remote`.
178+
179+
:::
180+
175181
## Step 4: Verify the server is running
176182

177183
Check that the server is running:
@@ -183,11 +189,12 @@ thv list
183189
You should see output similar to this:
184190

185191
```text
186-
NAME PACKAGE STATUS URL PORT TOOL TYPE CREATED AT
187-
fetch ghcr.io/stackloklabs/gofetch/server:latest running http://127.0.0.1:15266/mcp 15266 mcp 2025-07-10 08:41:56 -0400 EDT
192+
NAME PACKAGE STATUS URL PORT GROUP CREATED
193+
toolhive-doc-mcp ghcr.io/stackloklabs/toolhive-doc-mcp:v0.0.14-20260518 running http://127.0.0.1:19767/mcp 19767 default 2026-05-18 09:49:14 -0400 EDT
188194
```
189195

190-
This confirms that the fetch server is running and available on port 15266.
196+
This confirms that the server is running. ToolHive picks a free local port at
197+
startup, so your port number will be different.
191198

192199
:::info[What's happening?]
193200

@@ -237,22 +244,22 @@ that you run.
237244
## Step 6: Use the MCP server with your AI client
238245

239246
If you completed Step 5, you can now use the MCP server with your AI client
240-
application. Open your supported client (VS Code, Cursor, etc.) and ask the AI
241-
to fetch content from a website. Note that you might need to restart your client
242-
for the changes to take effect.
247+
application. Open your supported client (VS Code, Cursor, etc.) and ask the AI a
248+
question about ToolHive. Note that you might need to restart your client for the
249+
changes to take effect.
243250

244-
For example, try asking: "Can you fetch the content from https://toolhive.dev
245-
and summarize it for me?"
251+
For example, try asking: "What is a Virtual MCP Server and how do I use it with
252+
ToolHive?"
246253

247-
The AI should be able to use the Fetch MCP server to retrieve the content and
248-
provide a summary.
254+
The AI calls the `query_docs` tool to search the ToolHive documentation and uses
255+
the results to compose an answer.
249256

250257
:::info[What's happening?]
251258

252-
When you ask the AI to fetch content, it detects that it needs external data. It
253-
discovers the fetch tool provided by your MCP server, calls the tool with the
254-
URL you specified, receives the webpage content, and then processes that content
255-
to create a summary.
259+
When you ask a question about ToolHive, the AI client discovers the `query_docs`
260+
and `get_chunk` tools your MCP server exposes, calls them to search the official
261+
ToolHive documentation, then uses the returned passages to construct a grounded
262+
answer instead of relying on its training data alone.
256263

257264
:::
258265

@@ -261,13 +268,13 @@ to create a summary.
261268
When you're finished using the server, you can stop it:
262269

263270
```bash
264-
thv stop fetch
271+
thv stop toolhive-doc-mcp
265272
```
266273

267274
If you want to remove it completely:
268275

269276
```bash
270-
thv rm fetch
277+
thv rm toolhive-doc-mcp
271278
```
272279

273280
:::info[What's happening?]
@@ -324,9 +331,12 @@ the client, port conflicts, etc.).
324331

325332
A few quick checks specific to this tutorial:
326333

327-
- Confirm Docker, Podman, or Colima is running before `thv run fetch`.
328-
- If port 15266 is already in use, pass a specific port with `--proxy-port`, for
329-
example `thv run --proxy-port 8081 fetch`.
334+
- Confirm Docker, Podman, or Colima is running before `thv run toolhive-doc-mcp`
335+
(or use the `toolhive-doc-mcp-remote` variant, which doesn't need a container
336+
runtime).
337+
- ToolHive picks a free local port for the proxy at startup. If you need a
338+
specific port, pass `--proxy-port`, for example
339+
`thv run --proxy-port 8081 toolhive-doc-mcp`.
330340
- After running `thv client setup`, restart your AI client so it picks up the
331341
new configuration.
332342

0 commit comments

Comments
 (0)