Skip to content

Commit 30f9fc5

Browse files
committed
Document ChatGPT Desktop configuration via ngrok tunnel
1 parent 623893d commit 30f9fc5

1 file changed

Lines changed: 61 additions & 1 deletion

File tree

docs/toolhive/reference/client-compatibility.mdx

Lines changed: 61 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,14 @@ We've tested ToolHive with these clients:
4040
| Windsurf IDE |||| |
4141
| Windsurf (JetBrains) |||| |
4242
| Zed |||| v0.214.5+ |
43-
| ChatGPT Desktop |||| See [STDIO-only client configuration][4] |
43+
| ChatGPT Desktop |||| See [ChatGPT Desktop configuration][5] |
4444
| Claude Desktop |||| See [STDIO-only client configuration][4] |
4545
| GitHub Copilot (JetBrains) |||| v1.5.47+ |
4646
| PydanticAI |||| v0.2.18+ |
4747

4848
[3]: #vs-code-with-copilot
4949
[4]: #stdio-only-client-configuration
50+
[5]: #chatgpt-desktop-configuration
5051

5152
The minimum versions listed are the earliest versions that support the
5253
Streamable HTTP transport protocol.
@@ -373,6 +374,65 @@ even though it uses SSE transport.
373374
For more details, see the
374375
[`thv proxy stdio` CLI reference](../reference/cli/thv_proxy_stdio.md).
375376

377+
### ChatGPT Desktop configuration
378+
379+
ChatGPT Desktop only accepts MCP servers over HTTPS — it has no equivalent of
380+
Claude Desktop's command-based configuration. Use `thv proxy tunnel` to expose
381+
your local ToolHive server through an [ngrok](https://ngrok.com) tunnel.
382+
383+
**How it works:**
384+
385+
1. ToolHive runs the MCP server in its container with its default transport
386+
(SSE, HTTP, or other)
387+
2. The `thv proxy tunnel` command creates an ngrok HTTPS tunnel pointing to that
388+
server
389+
3. You configure ChatGPT Desktop with the resulting HTTPS URL
390+
391+
**Prerequisites:**
392+
393+
- An ngrok account and auth token
394+
- A static ngrok domain (recommended, so the connector URL stays stable across
395+
restarts)
396+
397+
**Example:**
398+
399+
First, run an MCP server:
400+
401+
```bash
402+
thv run osv --transport sse --name osv
403+
```
404+
405+
Then start the ngrok tunnel, using the workload name as the target:
406+
407+
```bash
408+
thv proxy tunnel osv osv \
409+
--tunnel-provider ngrok \
410+
--provider-args '{"auth-token": "<YOUR_NGROK_TOKEN>", "url": "https://<YOUR_NGROK_DOMAIN>", "pooling": true}'
411+
```
412+
413+
Then configure ChatGPT Desktop:
414+
415+
1. Navigate to **Settings → Connectors → Create**.
416+
2. Enter a **Connector name** and **Description**.
417+
3. Set the **Connector URL** to your ngrok domain plus the `/mcp` path, for
418+
example `https://<YOUR_NGROK_DOMAIN>/mcp`.
419+
4. Click **Create**.
420+
421+
After a successful connection, ChatGPT Desktop lists the tools your MCP server
422+
exposes. You can add them to a conversation by clicking **+** near the message
423+
composer and selecting your connector.
424+
425+
:::tip
426+
427+
The `url` field in `--provider-args` sets a static ngrok domain. If you omit it,
428+
ngrok assigns a temporary random URL each time, which means updating the
429+
connector in ChatGPT Desktop on every restart.
430+
431+
:::
432+
433+
For more details, see the
434+
[`thv proxy tunnel` CLI reference](../reference/cli/thv_proxy_tunnel.md).
435+
376436
## Related information
377437

378438
- [Client configuration](../guides-cli/client-configuration.mdx)

0 commit comments

Comments
 (0)