Skip to content

Commit ba2d281

Browse files
committed
added naming convention and default transport
1 parent 96306a7 commit ba2d281

File tree

1 file changed

+25
-5
lines changed

1 file changed

+25
-5
lines changed

docs/toolhive/guides-cli/run-mcp-servers.mdx

Lines changed: 25 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -32,13 +32,32 @@ thv run fetch
3232

3333
### Remote MCP servers
3434

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:
3636

3737
```bash
3838
thv run neon
3939
thv run stripe
4040
```
4141

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+
4261
:::info[What's happening?]
4362

4463
When you run an MCP server from the registry, ToolHive handles different server
@@ -56,11 +75,12 @@ types automatically:
5675
```
5776
5877
**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
6282
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.
6484
6585
:::
6686

0 commit comments

Comments
 (0)