Skip to content

Update proxy port flag #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 10, 2025
Merged

Update proxy port flag #50

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/toolhive/guides-cli/run-mcp-servers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,10 +144,10 @@ Check the MCP server's documentation for the required arguments.

ToolHive creates a reverse proxy on a random port that forwards requests to the
container. This is the port that client applications connect to. To set a
specific proxy port instead, use the `--port` flag:
specific proxy port instead, use the `--proxy-port` flag:

```bash
thv run --port <port-number> <server-name>
thv run --proxy-port <port-number> <server-name>
```

## Run a custom MCP server
Expand Down Expand Up @@ -216,7 +216,7 @@ When you run an MCP server from a Docker image, ToolHive:
1. Pulls the image (`my-mcp-server-image:latest`) and launches a container with
the options and arguments you specified.
2. Launches an HTTP proxy on a random port (optionally, add
`--port <port-number>` to specify the port).
`--proxy-port <port-number>` to specify the port).
3. Labels the container so it can be tracked by ToolHive:
```yaml
toolhive: true
Expand Down
40 changes: 24 additions & 16 deletions docs/toolhive/tutorials/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,22 +183,30 @@ ToolHive will pull the container image and start the server. You'll see output
similar to this:

```text
Image [mcp/fetch:latest] has 'latest' tag, pulling to ensure we have the most recent version...
Pulling image: [mcp/fetch:latest]
...
Successfully pulled image: [mcp/fetch:latest]
Using host port: [49226]
Logging to: [~/Library/Application Support/toolhive/logs/fetch.log]
MCP server is running in the background (PID: [80087])
Use 'thv stop [fetch]' to stop the server
8:41AM INF MCP server ghcr.io/stackloklabs/gofetch/server:latest is verified successfully
8:41AM INF Image ghcr.io/stackloklabs/gofetch/server:latest has 'latest' tag, pulling to ensure we have the most recent version...
8:41AM INF Pulling image: ghcr.io/stackloklabs/gofetch/server:latest
Pulling from stackloklabs/gofetch/server: latest
Digest: sha256:b9cbe3a8367f39e584d3fdd96d9c5046643c5f4798c3372b0c9049ece202cdef
Status: Image is up to date for ghcr.io/stackloklabs/gofetch/server:latest
8:41AM INF Successfully pulled image: ghcr.io/stackloklabs/gofetch/server:latest
8:41AM INF Using target port: 15266
8:41AM INF Logging to: ~/Library/Application Support/toolhive/logs/fetch.log
8:41AM INF MCP server is running in the background (PID: 16834)
8:41AM INF Use 'thv stop fetch' to stop the server
```

:::info What's happening?

ToolHive downloads the container image for the fetch server (if you don't
already have it), creates a container with the appropriate security settings,
and starts the server. It also sets up a proxy that lets your AI agent
communicate with the server.
When you run an MCP server, ToolHive:

- Verifies the MCP server image provenance (if attestation information is
available in the registry)
- Downloads the container image
- Sets up the container with the necessary security settings and starts it in
the background
- Sets up a reverse proxy that lets your AI client applications communicate with
the server

:::

Expand All @@ -213,11 +221,11 @@ thv list
You should see output similar to this:

```text
NAME PACKAGE STATUS URL PORT TOOL TYPE CREATED AT
fetch mcp/fetch:latest running http://127.0.0.1:15266/sse#fetch 15266 mcp 2025-06-30 09:12:53 -0400 EDT
NAME PACKAGE STATUS URL PORT TOOL TYPE CREATED AT
fetch ghcr.io/stackloklabs/gofetch/server:latest running http://127.0.0.1:15266/sse#fetch 15266 mcp 2025-07-10 08:41:56 -0400 EDT
```

This confirms that the fetch server is running and available on port 15266.
This confirms that the fetch server is running and available on port 49226.

:::info What's happening?

Expand Down Expand Up @@ -304,7 +312,7 @@ If the server fails to start, check:
Try running with a specific port:

```bash
thv run --port 8081 fetch
thv run --proxy-port 8081 fetch
```

</details>
Expand Down
Loading