You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/toolhive/guides-cli/run-mcp-servers.mdx
+25-5Lines changed: 25 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,13 +32,32 @@ thv run fetch
32
32
33
33
### Remote MCP servers
34
34
35
-
For remote MCP servers in the registry, such as the Neon or Stripe servers:
35
+
Remote MCP servers in the registry don't run as local containers but instead use ToolHive's transparent http proxy to forward requests to remote servers. For example:
36
36
37
37
```bash
38
38
thv run neon
39
39
thv run stripe
40
40
```
41
41
42
+
When you run a remote server from the registry, ToolHive uses the pre-configured remote URL and authentication settings. By default, remote servers use the `streamable-http` transport. If the server uses Server-Sent Events (SSE), specify the transport flag:
43
+
44
+
```bash
45
+
thv run <SERVER_NAME> --transport sse
46
+
```
47
+
48
+
:::note[Naming convention]
49
+
50
+
Remote MCP servers use the `-remote` suffix **when they have a local containerized counterpart** to distinguish between the two versions. For example:
51
+
-`github-remote` indicates this is the remote version of a server that also has a local `github` version
52
+
-`neon` and `stripe` don't have local counterparts, so they don't use the `-remote` suffix
53
+
54
+
To run a remote github mcp server, you should use the `github-remote` name.
55
+
56
+
```bash
57
+
thv run github-remote
58
+
```
59
+
:::
60
+
42
61
:::info[What's happening?]
43
62
44
63
When you run an MCP server from the registry, ToolHive handles different server
@@ -56,11 +75,12 @@ types automatically:
56
75
```
57
76
58
77
**For remote MCP servers:**
59
-
1. Automatically detects if the remote server requires authentication.
60
-
2. Handles OAuth/OIDC authentication flows if needed.
61
-
3. Starts an HTTP proxy process on a random port to forward client requests to
78
+
1. Uses the pre-configured remote URL from the registry.
79
+
2. Automatically detects if the remote server requires authentication.
80
+
3. Handles OAuth/OIDC authentication flows if needed.
81
+
4. Starts an HTTP proxy process on a random port to forward client requests to
62
82
the remote server.
63
-
4. Manages the server like any other ToolHive workload. No conatainer is created for remote MCP servers.
83
+
5. Manages the server like any other ToolHive workload. No container is created for remote MCP servers.
0 commit comments