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
+40-19Lines changed: 40 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,26 +32,35 @@ thv run fetch
32
32
33
33
### Remote MCP servers
34
34
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:
35
+
Remote MCP servers in the registry don't run as local containers but instead use
36
+
ToolHive's transparent http proxy to forward requests to remote servers. For
37
+
example:
36
38
37
39
```bash
38
40
thv run neon
39
41
thv run stripe
40
42
```
41
43
42
-
When you run a remote server from the registry, ToolHive uses the pre-configured remote URL and authentication settings.
44
+
When you run a remote server from the registry, ToolHive uses the pre-configured
45
+
remote URL and authentication settings.
43
46
44
47
:::note[Naming convention]
45
48
46
-
Remote MCP servers use the `-remote` suffix **when they have a local containerized counterpart** to distinguish between the two versions. For example:
47
-
-`github-remote` indicates this is the remote version of a server that also has a local `github` version
48
-
-`neon` and `stripe` don't have local counterparts, so they don't use the `-remote` suffix
49
+
Remote MCP servers use the `-remote` suffix **when they have a local
50
+
containerized counterpart** to distinguish between the two versions. For
51
+
example:
52
+
53
+
-`github-remote` indicates this is the remote version of a server that also has
54
+
a local `github` version
55
+
-`neon` and `stripe` don't have local counterparts, so they don't use the
56
+
`-remote` suffix
49
57
50
58
To run a remote github mcp server, you should use the `github-remote` name.
51
59
52
60
```bash
53
61
thv run github-remote
54
62
```
63
+
55
64
:::
56
65
57
66
:::info[What's happening?]
@@ -60,6 +69,7 @@ When you run an MCP server from the registry, ToolHive handles different server
60
69
types automatically:
61
70
62
71
**For local containerized servers:**
72
+
63
73
1. Pulls the image and launches a container using the configuration from the
64
74
registry.
65
75
2. Starts an HTTP proxy process on a random port to forward client requests to
@@ -71,12 +81,14 @@ types automatically:
71
81
```
72
82
73
83
**For remote MCP servers:**
84
+
74
85
1. Uses the pre-configured remote URL from the registry.
75
86
2. Automatically detects if the remote server requires authentication.
76
87
3. Handles OAuth/OIDC authentication flows if needed.
77
88
4. Starts an HTTP proxy process on a random port to forward client requests to
78
89
the remote server.
79
-
5. Manages the server like any other ToolHive workload. No container is created for remote MCP servers.
90
+
5. Manages the server like any other ToolHive workload. No container is created
91
+
for remote MCP servers.
80
92
81
93
:::
82
94
@@ -581,10 +593,10 @@ thv run --ca-cert /path/to/special-ca.crt uvx://other-package
581
593
582
594
## Run a remote MCP server
583
595
584
-
You can run remote MCP servers directly by providing their URL. This allows you to
585
-
connect to MCP servers hosted elsewhere without needing to manage containers locally.
586
-
ToolHive creates a transparent proxy that handles authentication and forwards requests
587
-
to the remote server.
596
+
You can run remote MCP servers directly by providing their URL. This allows you
597
+
to connect to MCP servers hosted elsewhere without needing to manage containers
598
+
locally. ToolHive creates a transparent proxy that handles authentication and
599
+
forwards requests to the remote server.
588
600
589
601
### Basic remote server setup
590
602
@@ -600,9 +612,12 @@ For example:
600
612
thv run https://api.example.com/mcp
601
613
```
602
614
603
-
If you don't specify a name with `--name`, ToolHive will automatically derive a name from the URL by extracting the main domain name (e.g., `notion` from `https://api.notion.com/mcp`).
615
+
If you don't specify a name with `--name`, ToolHive will automatically derive a
616
+
name from the URL by extracting the main domain name (e.g., `notion` from
617
+
`https://api.notion.com/mcp`).
604
618
605
-
By default, remote servers use the `streamable-http` transport. If the server uses Server-Sent Events (SSE), specify the transport flag:
619
+
By default, remote servers use the `streamable-http` transport. If the server
620
+
uses Server-Sent Events (SSE), specify the transport flag:
606
621
607
622
```bash
608
623
thv run https://api.example.com/sse --transport sse
@@ -616,7 +631,8 @@ When you run a remote MCP server, ToolHive:
616
631
2. Handles OAuth/OIDC authentication flows if needed.
617
632
3. Starts an HTTP proxy process on a random port to forward client requests to
618
633
the remote server.
619
-
4. Manages the server like any other ToolHive workload. No container is created for remote MCP servers.
634
+
4. Manages the server like any other ToolHive workload. No container is created
635
+
for remote MCP servers.
620
636
621
637
:::
622
638
@@ -634,7 +650,10 @@ examining the server's response headers and status codes:
634
650
thv run https://protected-api.com/mcp --name my-server
635
651
```
636
652
637
-
If authentication is required, ToolHive will prompt you to complete the OAuth flow. When no client credentials are provided, ToolHive automatically registers an OAuth client with the authorization server using RFC 7591 dynamic client registration, eliminating the need to pre-configure client ID and secret.
653
+
If authentication is required, ToolHive will prompt you to complete the OAuth
654
+
flow. When no client credentials are provided, ToolHive automatically registers
655
+
an OAuth client with the authorization server using RFC 7591 dynamic client
656
+
registration, eliminating the need to pre-configure client ID and secret.
638
657
639
658
#### OIDC authentication
640
659
@@ -649,7 +668,8 @@ thv run https://api.example.com/mcp \
649
668
650
669
#### OAuth2 authentication
651
670
652
-
For servers using OAuth2, you can specify the authorization and token URLs manually:
671
+
For servers using OAuth2, you can specify the authorization and token URLs
672
+
manually:
653
673
654
674
```bash
655
675
thv run https://api.example.com/mcp \
@@ -662,10 +682,11 @@ thv run https://api.example.com/mcp \
662
682
663
683
#### Automatic token refresh
664
684
665
-
ToolHive automatically handles OAuth token refresh for remote MCP servers. When you
666
-
authenticate with a remote server, ToolHive stores both the access token and refresh
667
-
token securely. The refresh token is used to automatically obtain new access tokens
668
-
when they expire, ensuring uninterrupted service without requiring manual re-authentication.
685
+
ToolHive automatically handles OAuth token refresh for remote MCP servers. When
686
+
you authenticate with a remote server, ToolHive stores both the access token and
687
+
refresh token securely. The refresh token is used to automatically obtain new
688
+
access tokens when they expire, ensuring uninterrupted service without requiring
0 commit comments