diff --git a/docs/toolhive/_partials/_remote-mcp-auth-examples.md b/docs/toolhive/_partials/_remote-mcp-auth-examples.md new file mode 100644 index 00000000..f818a661 --- /dev/null +++ b/docs/toolhive/_partials/_remote-mcp-auth-examples.md @@ -0,0 +1,82 @@ +#### Remote MCP server with dynamic client registration + +Dynamic client registration is the preferred approach for any MCP server that +supports it, as ToolHive handles all authentication setup automatically with +minimal configuration required. Notion's remote MCP server is one example that +supports this feature: + +1. Configuration settings: + - **Server name**: `notion-remote` + - **Server URL**: `https://mcp.notion.com/mcp` + - **Transport**: Streamable HTTP + - **Authorization method**: Dynamic Client Registration + - **Callback port**: `45673` (or any available port on your system) +1. When you install the server, ToolHive discovers the OAuth endpoints, + registers a new client, and handles the authentication process. +1. Your browser opens for authentication. After you authorize access, the remote + MCP server appears in your server list with a "Running" status. + +#### Remote MCP server with OAuth2 authentication + +GitHub's remote MCP server requires manual OAuth configuration. You'll need to +create a GitHub OAuth app and provide the details in ToolHive. + +First, create a GitHub OAuth app: + +1. Go to [GitHub Developer Settings](https://github.com/settings/developers) +1. Click **New OAuth App** +1. Fill in the application details: + - **Application name**: Choose a descriptive name (e.g., "ToolHive GitHub + MCP") + - **Homepage URL**: Your application's homepage or `http://localhost` + - **Authorization callback URL**: `http://localhost:45673/callback` (the port + number must match the **Callback port** you will enter in ToolHive) +1. Click **Register application** +1. Copy the **Client ID** and generate a **Client secret** for use in ToolHive + +Configure the remote MCP server in ToolHive: + +1. Configuration settings: + - **Server name**: `github-remote` + - **Server URL**: `https://api.githubcopilot.com/mcp/` + - **Transport**: Streamable HTTP + - **Authorization method**: OAuth 2.0 + - **Callback port**: `45673` (or any available port on your system) + - **Authorize URL**: `https://github.com/login/oauth/authorize` + - **Token URL**: `https://github.com/login/oauth/access_token` + - **Client ID**: Your GitHub OAuth app client ID (e.g., + `Og44jirLIaUgSiTDNGA3`) + - **Client secret**: Your GitHub OAuth app client secret (optional if PKCE is + enabled) + - **Scopes**: `repo,user:email` (comma-separated list of required + permissions) + - **PKCE**: Enable this option for enhanced security without requiring a + client secret +1. When you install the server, ToolHive opens your browser to authenticate with + GitHub and authorize the application. +1. After you authenticate successfully, the remote MCP server appears in your + server list with a "Running" status. + +#### Remote MCP server with OIDC authentication + +GitHub's remote MCP server also supports OIDC authentication, which provides +additional security features and standardized token handling. Use the same +GitHub OAuth app from the previous example. + +1. Fill in the configuration form: + - **Server name**: `github-remote` + - **Server URL**: `https://api.githubcopilot.com/mcp/` + - **Transport**: Streamable HTTP + - **Authorization method**: OIDC + - **Callback port**: `45673` (or any available port on your system) + - **Issuer URL**: `https://github.com/login/oauth` + - **Client ID**: Your GitHub OAuth app client ID (e.g., + `Og44jirLIaUgSiTDNGA3`) + - **Client secret**: Your GitHub OAuth app client secret (optional if PKCE is + enabled) + - **PKCE**: Enable this option for enhanced security without requiring a + client secret +1. When you install the server, ToolHive opens your browser to authenticate with + GitHub using OIDC. +1. After you authenticate successfully, the remote MCP server appears in your + server list with a "Running" status. diff --git a/docs/toolhive/guides-cli/manage-mcp-servers.md b/docs/toolhive/guides-cli/manage-mcp-servers.md index 2237d3a8..10a4e538 100644 --- a/docs/toolhive/guides-cli/manage-mcp-servers.md +++ b/docs/toolhive/guides-cli/manage-mcp-servers.md @@ -17,10 +17,9 @@ To see all currently running MCP servers: thv list ``` -This shows the server name, package, status, url, port, tool type, group, and -created at. Remote servers display their target URL in the URL column. The word -'remote' is indicated in both the package and tool type columns, making it easy -to identify remote servers. +This shows details about each running server, including its name, package +(container image), status, URL for connecting clients, group, and when it was +created. To include stopped servers in the list: diff --git a/docs/toolhive/guides-ui/network-isolation.mdx b/docs/toolhive/guides-ui/network-isolation.mdx index 029f24b0..d517aefb 100644 --- a/docs/toolhive/guides-ui/network-isolation.mdx +++ b/docs/toolhive/guides-ui/network-isolation.mdx @@ -24,8 +24,9 @@ protocols are not supported. ## Enabling network isolation -Currently, network isolation is available for MCP servers installed from the -ToolHive registry. +Network isolation is available for local MCP servers installed from the registry +or custom servers. It is not available for remote MCP servers, which are hosted +and outside of ToolHive. During the MCP server installation, select the **Network isolation** tab in the configuration form. Click the toggle to enable it. diff --git a/docs/toolhive/guides-ui/run-mcp-servers.mdx b/docs/toolhive/guides-ui/run-mcp-servers.mdx index 7ac70337..efdd5898 100644 --- a/docs/toolhive/guides-ui/run-mcp-servers.mdx +++ b/docs/toolhive/guides-ui/run-mcp-servers.mdx @@ -3,6 +3,8 @@ title: Run MCP servers description: How to install and run MCP servers in the ToolHive UI. --- +import RemoteAuthExamples from '../_partials/_remote-mcp-auth-examples.md'; + ToolHive makes it easy to run and manage Model Context Protocol (MCP) servers. This guide walks you through installing MCP servers from the registry, using Docker images, or from source packages. @@ -26,15 +28,15 @@ or remote {/* prettier-ignore */} ) from the registry: 1. Open the **Registry** page from the menu bar. -2. Browse or search for the MCP server you want to install. -3. Click on the desired MCP server to open its details page. Here you can review +1. Browse or search for the MCP server you want to install. +1. Click on the desired MCP server to open its details page. Here you can review more information about the server like its: - Description - Available tools - Tier (community or official) - Popularity (GitHub stars) - A link to the GitHub repository for more details and usage documentation -4. Click the **Install server** button to start the installation process. +1. Click the **Install server** button to start the installation process. ### Configure the server @@ -48,7 +50,8 @@ or remote {/* prettier-ignore */} } default> - **Local MCP servers** run directly on your machine using your container runtime. + +**Local MCP servers** run directly on your machine using your container runtime. The configuration form is pre-filled with defaults from the registry. Enter the remaining required information and adjust any optional settings as needed: @@ -57,7 +60,7 @@ remaining required information and adjust any optional settings as needed: This defaults to the MCP server's name in the registry. If you want to run multiple instances of the same MCP server, give each instance a unique name. -2. **Command arguments** (optional):\ +1. **Command arguments** (optional):\ Enter any command-line arguments needed to run the MCP server. These might be needed to pass application-specific parameters to the MCP server. Refer to the MCP server's documentation for details. @@ -70,10 +73,11 @@ remaining required information and adjust any optional settings as needed: ::: -3. To give the MCP server **access to the file system**, use the - [Volume mount](#volumes) feature. [Optional] +1. **Storage volumes** [Optional]:\ + Map files or folders from your local host to the MCP server. See + [Mount host files and folders](#volumes). [Optional] -4. **Secrets** and **environment variables** expected by the server are +1. **Secrets** and **environment variables** expected by the server are populated from the registry automatically. Required values are marked with an asterisk (\*). 1. **Secrets**: Enter a value to create a new secret or select an existing @@ -83,11 +87,17 @@ remaining required information and adjust any optional settings as needed: the variable name. These are typically used for configuration options that do not require sensitive data. +1. **Network isolation** [Optional]:\ + Enable network isolation to restrict the MCP server's network access. This + enhances security by limiting the server's ability to communicate with + external networks. See the [Network isolation](./network-isolation.mdx) guide + for details. + :::note Refer to the MCP server's documentation for the required configuration -information, required permissions, and authentication details. A link to the -GitHub repository is provided on each server's details page. +information, permissions, and authentication details. A link to the GitHub +repository is provided on each server's details page. ::: @@ -100,18 +110,19 @@ GitHub repository is provided on each server's details page. {' '}Remote MCP }> - **Remote MCP servers** are hosted services that you connect to. + +**Remote MCP servers** are hosted services that you connect to. The configuration form is pre-filled with defaults from the registry. Enter the remaining required information and adjust any optional settings as needed: 1. A unique **name** for the MCP server. [Required] -2. The **URL** of the remote MCP server. [Required] -3. The **transport protocol** that the MCP server uses. [Required]\ +1. The **URL** of the remote MCP server. [Required] +1. The **transport protocol** that the MCP server uses. [Required]\ ToolHive supports server-sent events (SSE) and Streamable HTTP (default) for real-time communication. The protocol must match what the MCP server supports. -4. **Authorization method**: Choose how ToolHive should authenticate with the +1. **Authorization method**: Choose how ToolHive should authenticate with the remote server.\ The default is **Dynamic Client Registration**. For MCP servers that fully implement the MCP authorization spec including dynamic client registration @@ -135,10 +146,11 @@ remaining required information and adjust any optional settings as needed: - **Client secret**: The secret key that proves your application's identity. Enter a value to create a new secret or select an existing secret from the provider. Secrets are stored securely and can be used by the MCP server - without exposing them in plaintext. Refer to the - [Secrets Management](https://docs.stacklok.com/toolhive/guides-ui/secrets-management) - section for detail. [Optional] + without exposing them in plaintext. See + [Secrets management](./secrets-management.md) for details. [Optional] - **Scopes**: List of permissions your application is requesting. [Optional] + - **PKCE**: Enable Proof Key for Code Exchange (RFC 7636) for enhanced + security without requiring a client secret. [Optional] **OIDC authentication options:** - **Issuer URL**: The base URL of the OIDC provider. [Required] @@ -147,38 +159,24 @@ remaining required information and adjust any optional settings as needed: - **Client secret**: The secret key that proves your application's identity. Enter a value to create a new secret or select an existing secret from the provider. Secrets are stored securely and can be used by the MCP server - without exposing them in plaintext. Refer to the - [Secrets Management](https://docs.stacklok.com/toolhive/guides-ui/secrets-management) - section for detail. [Optional] + without exposing them in plaintext. See + [Secrets management](./secrets-management.md) for details. [Optional] - **PKCE**: Enable Proof Key for Code Exchange (RFC 7636) for enhanced security without requiring a client secret. [Optional] -5. The **callback port** for the authentication redirect. [Required] +1. The **callback port** for the authentication redirect. [Required] Click **Install server** to connect to the remote MCP server. -Refer to -[examples of remote MCP authentication configuration](?server-type=remote&custom-type=custom_remote#remote-mcp-examples) -for detailed setup guides. - - - - -### Network isolation - -You can optionally enable network isolation for local MCP servers. This allows -you to control the MCP server's network access, restricting it to only the -necessary resources and preventing it from accessing the internet or other -external networks. - -:::info +
+View examples of remote MCP authentication configuration -Network isolation is only available for local MCP servers. + -::: +
-See the [Network isolation](./network-isolation.mdx) guide for details on how to -configure network isolation for MCP servers in ToolHive. + + ### Start the MCP server @@ -206,7 +204,7 @@ You're not limited to the MCP servers in the registry. You can run remote MCP servers by providing a URL, or your own local custom MCP servers using Docker images or source packages. -## Install a custom MCP server +### Configure the server Local MCP icon - {' '}Custom Local MCP + {' '}Custom local MCP } default> @@ -226,7 +224,7 @@ server, on the introductory screen. In the **Custom MCP server** dialog, choose [Docker image](#from-a-docker-image) or [Package manager](#from-a-source-package). -### From a Docker image +

From a Docker image

Select the **Docker image** option. This allows you to run any MCP server that is available as a Docker image in a remote registry or locally on your system. @@ -235,29 +233,26 @@ On the configuration form, enter: 1. A unique **name** for the MCP server. [Required] -2. The **transport protocol** that the MCP server uses. [Required]\ +1. The **transport protocol** that the MCP server uses. [Required]\ ToolHive supports standard input/output (`stdio`), server-sent events (SSE), and Streamable HTTP. The protocol must match what the MCP server supports. -3. The **target port** to expose from the container (SSE or Streamable HTTP +1. The **target port** to expose from the container (SSE or Streamable HTTP transports only). [Optional]\ If the MCP server uses a specific port, enter it here. If not specified, ToolHive will use a random port that is exposed to the container with the `MCP_PORT` and `FASTMCP_PORT` environment variables. -4. The Docker **image name** and tag (e.g., `my-mcp-server:latest`). [Required]\ +1. The Docker **image name** and tag (e.g., `my-mcp-server:latest`). [Required]\ You can use any valid Docker image, including those hosted on Docker Hub or other registries. -5. **Command-line arguments** needed to run the MCP server. [Optional]\ +1. **Command-line arguments** needed to run the MCP server. [Optional]\ These are specific to the MCP server and might include transport options or application-specific parameters. Refer to the MCP server's documentation for details. -6. To give the MCP server **access to the file system**, use the - [Volume mount](#volumes) feature. [Optional] - -7. Any **secrets** or **environment variables** required by the MCP server. +1. Any **secrets** or **environment variables** required by the MCP server. [Optional]\ These might include API tokens, configuration options, or other sensitive data. @@ -265,9 +260,19 @@ On the configuration form, enter: select an existing secret or enter a value to create a new one. - For non-sensitive environment variables, enter the name and value directly. +1. **Storage volumes** [Optional]:\ + Map files or folders from your local host to the MCP server. See + [Mount host files and folders](#volumes). [Optional] + +1. **Network isolation** [Optional]:\ + Enable network isolation to restrict the MCP server's network access. This + enhances security by limiting the server's ability to communicate with + external networks. See the [Network isolation](./network-isolation.mdx) guide + for details. + Click **Install server** to create and start the MCP server container. -### From a source package +

From a source package

Select the **Package manager** option. This allows you to run an MCP server from a source package. @@ -283,19 +288,19 @@ On the configuration form, enter: 1. A unique **name** for the MCP server. [Required] -2. The **transport protocol** that the MCP server uses. [Required]\ +1. The **transport protocol** that the MCP server uses. [Required]\ ToolHive supports standard input/output (`stdio`), server-sent events (SSE), and Streamable HTTP. The protocol must match what the MCP server supports. -3. The **target port** to expose from the container (SSE or Streamable HTTP +1. The **target port** to expose from the container (SSE or Streamable HTTP transports only). [Optional]\ If the MCP server uses a specific port, enter it here. If not specified, ToolHive will use a random port that is exposed to the container with the `MCP_PORT` and `FASTMCP_PORT` environment variables. -4. The package **protocol** (`npx`, `uvx`, or `go`). [Required] +1. The package **protocol** (`npx`, `uvx`, or `go`). [Required] -5. The **name** of the package to run. [Required] +1. The **name** of the package to run. [Required] 1. For `npx`, use the [npm](https://www.npmjs.com/) package name and version, e.g. `my-mcp-package@latest` 2. For `uvx`, use the [PyPI](https://pypi.org/) package name and version, @@ -304,15 +309,12 @@ On the configuration form, enter: package and version, e.g. `go://github.com/orgname/my-mcp-server/cmd/server@latest` -6. **Command-line arguments** needed to run the MCP server. [Optional]\ +1. **Command-line arguments** needed to run the MCP server. [Optional]\ These are specific to the MCP server and might include transport options or application-specific parameters. Refer to the MCP server's documentation for details. -7. To give the MCP server **access to the file system**, use the - [Volume mount](#volumes) feature. [Optional] - -8. Any **secrets** or **environment variables** required by the MCP server. +1. Any **secrets** or **environment variables** required by the MCP server. [Optional]\ These might include API tokens, configuration options, or other sensitive data. @@ -320,6 +322,16 @@ On the configuration form, enter: select an existing secret or enter a value to create a new one. - For non-sensitive environment variables, enter the name and value directly. +1. **Storage volumes** [Optional]:\ + Map files or folders from your local host to the MCP server. See + [Mount host files and folders](#volumes). [Optional] + +1. **Network isolation** [Optional]:\ + Enable network isolation to restrict the MCP server's network access. This + enhances security by limiting the server's ability to communicate with + external networks. See the [Network isolation](./network-isolation.mdx) guide + for details. + Click **Install server** to create and start the MCP server container. @@ -328,7 +340,7 @@ Click **Install server** to create and start the MCP server container. label={ <> Remote MCP icon - {' '}Custom Remote MCP + {' '}Custom remote MCP }> @@ -367,9 +379,8 @@ On the configuration form, enter: - **Client secret**: The secret key that proves your application's identity. Enter a value to create a new secret or select an existing secret from the provider. Secrets are stored securely and can be used by the MCP server - without exposing them in plaintext. Refer to the - [Secrets Management](https://docs.stacklok.com/toolhive/guides-ui/secrets-management) - section for detail. [Optional] + without exposing them in plaintext. See + [Secrets management](./secrets-management.md) for details. [Optional] - **Scopes**: List of permissions your application is requesting. [Optional] **OIDC authentication options:** @@ -379,9 +390,8 @@ On the configuration form, enter: - **Client secret**: The secret key that proves your application's identity. Enter a value to create a new secret or select an existing secret from the provider. Secrets are stored securely and can be used by the MCP server - without exposing them in plaintext. Refer to the - [Secrets Management](https://docs.stacklok.com/toolhive/guides-ui/secrets-management) - section for detail. [Optional] + without exposing them in plaintext. See + [Secrets management](./secrets-management.md) for details. [Optional] - **PKCE**: Enable Proof Key for Code Exchange (RFC 7636) for enhanced security without requiring a client secret. [Optional] @@ -392,98 +402,14 @@ Click **Install server** to connect to the remote MCP server.
View examples of remote MCP authentication configuration -#### Remote MCP server with dynamic client registration - -Dynamic client registration is the preferred approach for any MCP server that -supports it, as ToolHive handles all authentication setup automatically with -minimal configuration required. Notion's remote MCP server is one example that -supports this feature: - -1. On the **MCP Servers** page, click **Add an MCP server**. -2. Select **Add a remote MCP server** from the drop-down menu. -3. Fill in the configuration form: - - **Server name**: `notion-mcp-server` - - **URL**: `https://mcp.notion.com/mcp` - - **Transport protocol**: Select **Streamable HTTP** - - **Authorization method**: Select **Dynamic Client Registration** - - **Callback port**: `45673` (or any available port on your system) -4. Click **Install server** to start the automatic registration flow. -5. ToolHive discovers the OAuth endpoints, registers a new client, and handles - the authentication process. -6. Your browser opens for authentication. After you authorize access, the remote - MCP server appears in your server list with a "Running" status. - -#### Remote MCP server with OAuth2 authentication - -GitHub's remote MCP server requires manual OAuth configuration. You'll need to -create a GitHub OAuth app and provide the details in ToolHive. - -First, create a GitHub OAuth app: - -1. Go to [GitHub Developer Settings](https://github.com/settings/developers) -2. Click **New OAuth App** -3. Fill in the application details: - - **Application name**: Choose a descriptive name (e.g., "ToolHive GitHub - MCP") - - **Homepage URL**: Your application's homepage or `http://localhost` - - **Authorization callback URL**: `http://localhost:45673/callback` (the port - number must match the **Callback port** you will enter in ToolHive) -4. Click **Register application** -5. Copy the **Client ID** and generate a **Client secret** for use in ToolHive - -Configure the remote MCP server in ToolHive: - -1. On the **MCP Servers** page, click **Add an MCP server**. -2. Select **Add a remote MCP server** from the drop-down menu. -3. Fill in the configuration form: - - **Server name**: `github-remote-oauth` - - **URL**: `https://api.githubcopilot.com/mcp/` - - **Transport protocol**: Select **Streamable HTTP** - - **Authorization method**: Select **OAuth2** - - **Authorize URL**: `https://github.com/login/oauth/authorize` - - **Token URL**: `https://github.com/login/oauth/access_token` - - **Client ID**: Your GitHub OAuth app client ID (e.g., - `Og44jirLIaUgSiTDNGA3`) - - **Client secret**: Your GitHub OAuth app client secret - - **Scopes**: `public_repo` (comma-separated list of required permissions) - - **Callback port**: `45673` (or any available port on your system) -4. Click **Install server** to start the authentication flow. -5. ToolHive opens your browser to authenticate with GitHub and authorize the - application. -6. After you authenticate successfully, the remote MCP server appears in your - server list with a "Running" status. - -#### Remote MCP server with OIDC authentication - -GitHub's remote MCP server also supports OIDC authentication, which provides -additional security features and standardized token handling. Use the same -GitHub OAuth app from the previous example. - -1. On the **MCP Servers** page, click **Add an MCP server**. -2. Select **Add a remote MCP server** from the drop-down menu. -3. Fill in the configuration form: - - **Server name**: `github-remote-oidc` - - **URL**: `https://api.githubcopilot.com/mcp/` - - **Transport protocol**: Select **Streamable HTTP** - - **Authorization method**: Select **OIDC** - - **Issuer URL**: `https://github.com/login/oauth` - - **Client ID**: Your GitHub OAuth app client ID (e.g., - `Og44jirLIaUgSiTDNGA3`) - - **Client secret**: Your GitHub OAuth app client secret (optional for PKCE) - - **PKCE**: Enable this option for enhanced security without requiring a - client secret - - **Callback port**: `45673` (or any available port on your system) -4. Click **Install server** to start the authentication flow. -5. ToolHive opens your browser to authenticate with GitHub using OIDC. -6. After you authenticate successfully, the remote MCP server appears in your - server list with a "Running" status. +
-## Mount host files and folders (Volumes) \{#volumes} +## Mount host files and folders \{#volumes} Some MCP servers need access to files on your machine. You can mount host paths directly in the UI.