From 4a2ffa680be8a96e64c32e56bd696b561ab2660f Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 26 Jun 2026 11:32:21 -0400 Subject: [PATCH 1/2] Split UI Run MCP servers guide into two pages Extract the per-field configuration reference out of the UI Run MCP servers guide into a new Configure MCP servers page, mirroring the CLI split in PR 981. The run page becomes a linear how-to (registry, custom local, custom remote) with no tabs, ending each flow at the configuration form. The new configure page documents every setting once, organized by options for all servers, local servers, and remote servers. This removes the 2x2 tab matrix and the duplicated remote authentication block. Update the sidebar and fix inbound anchor links in connect-clients and the filesystem guide. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../_partials/_remote-mcp-auth-examples.mdx | 98 ---- docs/toolhive/guides-k8s/connect-clients.mdx | 2 +- docs/toolhive/guides-mcp/filesystem.mdx | 6 +- .../guides-ui/configure-mcp-servers.mdx | 343 +++++++++++ docs/toolhive/guides-ui/run-mcp-servers.mdx | 555 +++--------------- sidebars.ts | 1 + static/img/mcp-servers/local-mcp.svg | 1 - static/img/mcp-servers/remote-mcp.svg | 1 - 8 files changed, 416 insertions(+), 591 deletions(-) delete mode 100644 docs/toolhive/_partials/_remote-mcp-auth-examples.mdx create mode 100644 docs/toolhive/guides-ui/configure-mcp-servers.mdx delete mode 100644 static/img/mcp-servers/local-mcp.svg delete mode 100644 static/img/mcp-servers/remote-mcp.svg diff --git a/docs/toolhive/_partials/_remote-mcp-auth-examples.mdx b/docs/toolhive/_partials/_remote-mcp-auth-examples.mdx deleted file mode 100644 index af0ff48e..00000000 --- a/docs/toolhive/_partials/_remote-mcp-auth-examples.mdx +++ /dev/null @@ -1,98 +0,0 @@ -#### Remote MCP server with Auto-Discovered authentication - -**Auto-Discovered** authentication 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**: Auto-Discovered - - **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 Bearer Token authentication - -Bearer Token authentication is the simplest option for MCP servers that accept a -bearer token in the `Authorization` header. Brave Search's remote MCP server is -one example: - -1. Configuration settings: - - **Server name**: `brave-search` - - **Server URL**: `https://mcp.bravesearch.com/sse` - - **Transport**: SSE - - **Authorization method**: Bearer Token - - **Bearer token**: Your Brave Search API key -1. When you install the server, ToolHive stores the token securely and injects - it as an `Authorization: Bearer ` header on every request. -1. 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-k8s/connect-clients.mdx b/docs/toolhive/guides-k8s/connect-clients.mdx index acf173a6..3166ac40 100644 --- a/docs/toolhive/guides-k8s/connect-clients.mdx +++ b/docs/toolhive/guides-k8s/connect-clients.mdx @@ -746,7 +746,7 @@ The MCP server is now available to your configured MCP clients. For more details on using remote MCP servers, see: -- [Run remote MCP servers (UI)](../guides-ui/run-mcp-servers.mdx?custom-type=custom_remote#install-a-custom-mcp-server) +- [Run remote MCP servers (UI)](../guides-ui/run-mcp-servers.mdx#custom-remote-servers) - [Run remote MCP servers (CLI)](../guides-cli/run-mcp-servers.mdx#run-a-remote-mcp-server) ## Connect from within the cluster diff --git a/docs/toolhive/guides-mcp/filesystem.mdx b/docs/toolhive/guides-mcp/filesystem.mdx index 9722ad1c..08245f28 100644 --- a/docs/toolhive/guides-mcp/filesystem.mdx +++ b/docs/toolhive/guides-mcp/filesystem.mdx @@ -35,9 +35,9 @@ does not provide filesystem access, or for demonstrating MCP capabilities. Select the `filesystem` MCP server in the ToolHive registry. In the **Storage volumes** section, -[add local files or folders](../guides-ui/run-mcp-servers.mdx#volumes) to expose -to the MCP server. In the drop-down, choose whether to mount the volume as -read-only or read-write. +[add local files or folders](../guides-ui/configure-mcp-servers.mdx#storage-volumes) +to expose to the MCP server. In the drop-down, choose whether to mount the +volume as read-only or read-write. :::note diff --git a/docs/toolhive/guides-ui/configure-mcp-servers.mdx b/docs/toolhive/guides-ui/configure-mcp-servers.mdx new file mode 100644 index 00000000..00b08f3d --- /dev/null +++ b/docs/toolhive/guides-ui/configure-mcp-servers.mdx @@ -0,0 +1,343 @@ +--- +title: Configure MCP servers +description: + MCP server settings in the ToolHive UI - names, groups, ports, secrets, + storage volumes, network isolation, and remote authentication. +--- + +When you install an MCP server in the ToolHive UI, the configuration form +collects the settings ToolHive needs to run it. When you install from the +[registry](./registry.mdx), the form is pre-filled with sensible defaults, so +you often only need to supply the required values and adjust a few options. + +Not every setting applies to every server. The settings fall into three groups: + +- [**Options for all servers**](#options-for-all-servers) apply to local and + remote servers alike. +- [**Options for local servers**](#options-for-local-servers) configure the + container ToolHive runs on your machine. They don't apply to remote servers, + which connect to a hosted URL instead of running a local container. +- [**Options for remote servers**](#options-for-remote-servers) control how + ToolHive connects to and authenticates with a hosted MCP server. + +Required fields are marked with an asterisk (\*) in the form. For the steps to +open this form, see [Run MCP servers](./run-mcp-servers.mdx). + +## Options for all servers + +These settings apply to every server, whether it's local or remote and whether +you install it from the registry or add it as a custom server. + +### Server name + +A unique name for the MCP server. 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. + +### Group + +The group where this server is added. Select an existing group or keep the +default. Groups help you organize servers and control client access. See +[Organize servers into groups](./group-management.mdx) for details. + +### Proxy port + +Port for the HTTP proxy to listen on. If not specified, ToolHive automatically +assigns a random port. This is the port that AI clients connect to, which is +distinct from the [target port](#target-port) that a local MCP server listens on +inside its container. + +## Options for local servers + +These settings configure the container that ToolHive launches on your machine. +They have no effect on remote servers, which proxy to a URL instead of running a +local container. + +### Transport protocol + +The transport protocol that the MCP server uses. ToolHive supports standard +input/output (`stdio`), server-sent events (SSE), and Streamable HTTP. The +protocol must match what the MCP server supports. + +For registry servers, this is pre-filled from the registry. For custom servers, +set it to match the server you're running. + +### Target port + +The port to expose from the container, for SSE or Streamable HTTP transports +only. If the MCP server uses a specific port, enter it here. If not specified, +ToolHive uses a random port that is exposed to the container with the `MCP_PORT` +and `FASTMCP_PORT` environment variables. + +### Proxy mode + +The proxy transport mode that clients use to connect to this server. Choose +**SSE** (`sse`) or **Streamable HTTP** (`streamable-http`). **Streamable HTTP** +is the default. + +This option appears only when the **transport protocol** is `stdio` and the +server is not configured for bearer token authentication. For `sse` and +`streamable-http` transports, the MCP server already speaks HTTP, so no proxy +mode selection is needed. Proxy mode doesn't apply to remote servers, whose +transports are always HTTP-based. + +### Command arguments + +Any command-line arguments needed to run the MCP server. These might be needed +to pass application-specific parameters to the server. Refer to the MCP server's +documentation for details. + +:::info + +We've made every effort to include sensible defaults in the registry for a +one-click experience, but some servers may require additional command-line +arguments to function correctly. + +::: + +### Secrets and environment variables + +The secrets and environment variables expected by the server. For registry +servers, these are populated automatically. + +- **Secrets**: Enter a value to create a new secret, or select an existing + secret to map to the environment variable. Secrets are stored securely and can + be used by the MCP server without exposing them in plaintext. See + [Secrets management](./secrets-management.mdx) for details. +- **Environment variables**: Enter the value in the input field alongside the + variable name. These are typically used for configuration options that do not + require sensitive data. + +### Storage volumes + +Map files or folders from your local host to the MCP server. Some MCP servers +need access to files on your machine; you can mount host paths directly in the +form. + +1. In the server configuration form, scroll to **Storage volumes**. +2. Use the **first row** to create your mount: + - **Host path**: choose a file or folder on your computer. + - **Container path**: where it should appear inside the server (for example, + `/data`). + - By default, mounts are read-write. To make a mount **read-only**, select + the "Read-only access" option from the drop-down. +3. If you need additional mounts, click **Add a volume** and repeat. + +This applies to both registry-installed servers and custom servers (Docker image +or source package). + +### Network isolation + +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. + +## Options for remote servers + +These settings control how ToolHive connects to and authenticates with a hosted +MCP server. They apply to both registry remote servers and custom remote +servers. + +### URL and transport protocol + +- **URL**: The URL of the remote MCP server. [Required] +- **Transport protocol**: ToolHive supports server-sent events (SSE) and + Streamable HTTP (default). The protocol must match what the MCP server + supports. [Required] + +### Authorization method + +Choose how ToolHive should authenticate with the remote server. + +The default is **Auto-Discovered**. Use this option for MCP servers that +implement the MCP authorization spec or for servers that do not require +authentication. ToolHive automatically discovers OAuth/OIDC endpoints and +identifies itself using whichever mechanism the server supports: + +- **Client ID Metadata Document (CIMD):** If the server's discovery document + sets `client_id_metadata_document_supported: true`, ToolHive presents + [`https://toolhive.dev/oauth/client-metadata.json`](https://toolhive.dev/oauth/client-metadata.json) + as the `client_id`. No registration round-trip is needed. +- **Dynamic Client Registration (DCR, RFC 7591):** When CIMD is unavailable or + rejected, ToolHive registers an OAuth client dynamically. + +Either path handles token acquisition and lifecycle automatically. + +For MCP servers that accept a bearer token in the `Authorization` header, select +**Bearer Token**. ToolHive stores the token securely and sends it as an +`Authorization: Bearer ` header on every request. For servers that expect +a different header (such as `X-API-Key`), use +[**Custom headers**](#custom-headers) instead. + +**Bearer Token authentication options:** + +- **Bearer token**: The token value. Enter a value to create a new secret or + select an existing secret from the provider. Secrets are stored securely and + are not exposed in plaintext in configuration files. See + [Secrets management](./secrets-management.mdx) for details. [Required] + +For MCP servers that require OAuth2 or OIDC authentication, obtain the necessary +information from the MCP server's documentation or administrator. + +**OAuth2 authentication options:** + +- **Authorize URL**: The URL where users are redirected to authenticate and + authorize access to the MCP server. [Required] +- **Token URL**: The URL where your application exchanges the authorization code + for access tokens. [Required] +- **Client ID**: Your application's identifier registered with the OAuth + provider. [Required] +- **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 are not exposed in plaintext in + configuration files. See [Secrets management](./secrets-management.mdx) for + details. [Optional] +- **Scopes**: List of permissions your application is requesting. [Optional] +- **PKCE**: Enable Proof Key for Code Exchange (RFC 7636) for enhanced security. + Some providers let PKCE replace the client secret; others (such as GitHub) + still require it. [Optional] + +**OIDC authentication options:** + +- **Issuer URL**: The base URL of the OIDC provider. [Required] +- **Client ID**: Your application's identifier registered with the OIDC + provider. [Required] +- **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 are not exposed in plaintext in + configuration files. See [Secrets management](./secrets-management.mdx) for + details. [Optional] +- **PKCE**: Enable Proof Key for Code Exchange (RFC 7636) for enhanced security. + Some providers let PKCE replace the client secret; others (such as GitHub) + still require it. [Optional] + +### Callback port + +The callback port for the authentication redirect. [Optional] + +### Custom headers + +Add custom HTTP headers to inject into requests to the remote MCP server. + +- **Plaintext headers**: Add static key-value pairs for headers like + `X-Tenant-ID` or correlation IDs. These values are stored and transmitted in + plaintext. +- **Headers from secrets**: For sensitive data like API keys, add headers whose + values are retrieved from ToolHive's secrets manager. Enter a header name and + either select an existing secret or enter a new value to create one. + +## Authentication examples + +These examples show how to configure each authorization method for a remote MCP +server, using real services as illustrations. + +### Auto-Discovered authentication + +**Auto-Discovered** authentication 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**: Auto-Discovered + - **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. + +### Bearer Token authentication + +Bearer Token authentication is the simplest option for MCP servers that accept a +static bearer token in the `Authorization` header: + +1. Configuration settings: + - **Server name**: `my-remote-server` + - **Server URL**: `https://api.example.com/mcp` + - **Transport**: Streamable HTTP + - **Authorization method**: Bearer Token + - **Bearer token**: The token issued by the remote MCP server +1. When you install the server, ToolHive stores the token securely and injects + it as an `Authorization: Bearer ` header on every request. +1. The remote MCP server appears in your server list with a "Running" status. + +### 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. GitHub requires the + client secret even when PKCE is enabled. + - **Scopes**: `repo,user:email` (comma-separated list of required + permissions) + - **PKCE**: Enable this option for additional security +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. + +### 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. GitHub requires the + client secret even when PKCE is enabled. + - **PKCE**: Enable this option for additional security +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. + +## Next steps + +- [Run MCP servers](./run-mcp-servers.mdx) from the registry or as custom + servers. +- Connect ToolHive to AI clients like GitHub Copilot or Cursor using the + [client configuration guide](./client-configuration.mdx). +- Customize which tools are available from registry servers using the + [customize tools guide](./customize-tools.mdx). + +## Related information + +- [Secrets management](./secrets-management.mdx) +- [Organize servers into groups](./group-management.mdx) +- [Network isolation](./network-isolation.mdx) diff --git a/docs/toolhive/guides-ui/run-mcp-servers.mdx b/docs/toolhive/guides-ui/run-mcp-servers.mdx index c224384d..aaf27872 100644 --- a/docs/toolhive/guides-ui/run-mcp-servers.mdx +++ b/docs/toolhive/guides-ui/run-mcp-servers.mdx @@ -1,34 +1,29 @@ --- title: Run MCP servers description: - Install and run MCP servers from the registry or custom images using the + Install and run MCP servers from the registry or as custom servers using the ToolHive desktop app. --- -import RemoteAuthExamples from '../_partials/_remote-mcp-auth-examples.mdx'; -import Heading from '@theme/Heading'; - 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. +This guide walks you through installing MCP servers from the registry and adding +your own custom servers from Docker images, source packages, or remote URLs. + +Each install flow ends at a configuration form. For a description of every +setting on that form, see [Configure MCP servers](./configure-mcp-servers.mdx). ## Install from the registry ToolHive includes a built-in registry of MCP servers that meet a [minimum quality standard](../concepts/registry-criteria.mdx), allowing you to -discover and deploy high-quality tools effortlessly. Simply select one from the -list to run it securely with just a few clicks. +discover and deploy high-quality tools effortlessly. Select one from the list to +run it securely with just a few clicks. -### Select an MCP server +The registry includes both local servers, which run as containers on your +machine, and remote servers, which connect to a hosted service. Each server's +entry in the registry is labeled with a local or remote icon. -{/* prettier-ignore */} -To install an MCP server (local Local MCP icon -or remote {/* prettier-ignore */} Remote MCP icon ) from the registry: +### Select an MCP server 1. Open the **Registry** page from the menu bar. 1. Browse or search for the MCP server you want to install. @@ -41,79 +36,18 @@ or remote {/* prettier-ignore */} - - Local MCP icon - {' '}Local MCP - - } - default> - -**Local MCP servers** run directly on your machine using your container runtime. +### Configure and start the server The configuration form is pre-filled with defaults from the registry. Enter the remaining required information and adjust any optional settings as needed: -1. **Server name**: A unique name for the MCP server.\ - 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. - -1. **Group**: The group where this server will be added. [Optional]\ - Select an existing group or keep the default. Groups help you organize - servers and control client access. See - [Organize servers into groups](./group-management.mdx) for details. - -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. - - :::info - - We've made every effort to include sensible defaults in the registry for a - one-click experience, but some servers may require additional command-line - arguments to function correctly. - - ::: - -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. **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 - secret to map to the environment variable. Secrets are stored securely and - can be used by the MCP server without exposing them in plaintext. - 2. **Environment variables**: Enter the value in the input field alongside - 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. - -1. **Proxy mode** [Conditional]:\ - The proxy transport mode that clients should use to connect to this server. - Choose **SSE** (`sse`) or **Streamable HTTP** (`streamable-http`). - **Streamable HTTP** is the default. This option appears only when the - **transport protocol** is `stdio` and the server is not configured for bearer - token authentication. For `sse` and `streamable-http` transports, the MCP - server already speaks HTTP, so no proxy mode selection is needed. - -1. **Proxy port** [Optional]:\ - Port for the HTTP proxy to listen on. If not specified, ToolHive - automatically assigns a random port. This is the port that AI clients connect - to, which is distinct from the **target port** that the MCP server itself - listens on inside the container. +- For a **local** server, review the name, group, command arguments, secrets and + environment variables, storage volumes, and network isolation. +- For a **remote** server, review the URL, transport protocol, and authorization + method. + +For a description of each setting, see +[Configure MCP servers](./configure-mcp-servers.mdx). :::note @@ -123,239 +57,50 @@ repository is provided on each server's details page. ::: - - - Remote MCP icon - {' '}Remote MCP - - }> - -**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] -1. **Group**: The group where this server will be added. [Optional]\ - Select an existing group or keep the default. Groups help you organize - servers and control client access. See - [Organize servers into groups](./group-management.mdx) for details. -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. -1. **Authorization method**: Choose how ToolHive should authenticate with the - remote server.\ - The default is **Auto-Discovered**. Use this option for MCP servers that - implement the MCP authorization spec or for servers that do not require - authentication. ToolHive automatically discovers OAuth/OIDC endpoints and - identifies itself using whichever mechanism the server supports: - - **Client ID Metadata Document (CIMD):** If the server's discovery document - sets `client_id_metadata_document_supported: true`, ToolHive presents - [`https://toolhive.dev/oauth/client-metadata.json`](https://toolhive.dev/oauth/client-metadata.json) - as the `client_id`. No registration round-trip is needed. - - **Dynamic Client Registration (DCR, RFC 7591):** When CIMD is unavailable - or rejected, ToolHive registers an OAuth client dynamically. - - Either path handles token acquisition and lifecycle automatically. - - For MCP servers that accept a bearer token in the `Authorization` header, - select **Bearer Token**. ToolHive stores the token securely and sends it as - an `Authorization: Bearer ` header on every request. For servers that - expect a different header (such as `X-API-Key`), use **Custom headers** - instead. - - **Bearer Token authentication options:** - - **Bearer token**: The token value. Enter a value to create a new secret or - select an existing secret from the provider. Secrets are stored securely - and are not exposed in plaintext in configuration files. See - [Secrets management](./secrets-management.mdx) for details. [Required] - - For MCP servers that require OAuth2 or OIDC authentication, obtain the - necessary information from the MCP server's documentation or administrator. - - **OAuth2 authentication options:** - - **Authorize URL**: The URL where users are redirected to authenticate and - authorize access to the MCP server. [Required] - - **Token URL**: The URL where your application exchanges the authorization - code for access tokens. [Required] - - **Client ID**: Your application's identifier registered with the OAuth - provider. [Required] - - **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 are not exposed in plaintext in - configuration files. See [Secrets management](./secrets-management.mdx) 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] - - **Client ID**: Your application's identifier registered with the OIDC - provider. [Required] - - **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 are not exposed in plaintext in - configuration files. See [Secrets management](./secrets-management.mdx) for - details. [Optional] - - **PKCE**: Enable Proof Key for Code Exchange (RFC 7636) for enhanced - security without requiring a client secret. [Optional] - -1. The **callback port** for the authentication redirect. [Optional] - -1. **Custom headers** [Optional]:\ - Add custom HTTP headers to inject into requests to the remote MCP server. - - **Plaintext headers**: Add static key-value pairs for headers like - `X-Tenant-ID` or correlation IDs. These values are stored and transmitted - in plaintext. - - **Headers from secrets**: For sensitive data like API keys, add headers - whose values are retrieved from ToolHive's secrets manager. Enter a header - name and either select an existing secret or enter a new value to create - one. - -1. **Proxy port** [Optional]:\ - Port for the HTTP proxy to listen on. If not specified, ToolHive - automatically assigns a random port. **Proxy mode** is not shown for remote - MCP servers because remote transports are always HTTP-based (SSE or - Streamable HTTP). - -Click **Install server** to connect to the remote MCP server. - -
-View examples of remote MCP authentication configuration - - - -
- - - - -### Start the MCP server - -Click **Install server** to install and start the MCP server. ToolHive downloads -the Docker image, creates a container, and starts it with the specified -configuration. +Click **Install server** to install and start the MCP server. For local servers, +ToolHive downloads the Docker image, creates a container, and starts it with the +specified configuration. For remote servers, ToolHive connects to the hosted +service. Once the server is running, you can see its status on the **MCP Servers** page. -Each server's card includes: - -- The server name -- Its status (Running or Stopped) with a toggle button to start or stop it -- A menu (︙) that includes the server's URL for AI clients that need manual - configuration, and options to: - - Open the server's GitHub repository - - View the server's logs - - Remove the server - -See [Manage MCP servers](#manage-mcp-servers) below for more details on server +See [Manage MCP servers](#manage-mcp-servers) below for details on server states. ## Install a custom MCP server -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. +You're not limited to the MCP servers in the registry. You can run your own +local custom MCP servers using Docker images or source packages, or connect to +remote MCP servers by providing a URL. -### Configure the server +For a description of every setting referenced below, see +[Configure MCP servers](./configure-mcp-servers.mdx). - - - Local MCP icon - {' '}Custom local MCP - - } - default> +### Custom local servers On the **MCP Servers** page, click **Add an MCP server**, then choose **Add -custom local server** in the drop-down menu. Or if this is your first MCP -server, on the introductory screen. +custom local server** in the drop-down menu (or, if this is your first MCP +server, use the option on the introductory screen). In the **Custom MCP server** dialog, choose [Docker image](#from-a-docker-image) or [Package manager](#from-a-source-package). -{/* prettier-ignore */} -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. -On the configuration form, enter: - -1. A unique **name** for the MCP server. [Required] - -1. **Group**: The group where this server will be added. [Optional]\ - Select an existing group or keep the default. Groups help you organize - servers and control client access. See - [Organize servers into groups](./group-management.mdx) for details. - -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. - -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. - -1. **Proxy mode** [Conditional]:\ - The proxy transport mode that clients should use to connect to this server. - Choose **SSE** (`sse`) or **Streamable HTTP** (`streamable-http`). - **Streamable HTTP** is the default. This option appears only when the - **transport protocol** is `stdio` and the server is not configured for bearer - token authentication. - -1. **Proxy port** [Optional]:\ - Port for the HTTP proxy to listen on. If not specified, ToolHive - automatically assigns a random port. This is the port that AI clients connect - to, which is distinct from the **target port** that the MCP server itself - listens on inside the container. - -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. - -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. - -1. Any **secrets** or **environment variables** required by the MCP server. - [Optional]\ - These might include API tokens, configuration options, or other sensitive - data. - - Secrets are mapped to an environment variable. Enter the variable name and - 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. +On the configuration form, enter the Docker **image name** and tag (for example, +`my-mcp-server:latest`), then set the +[transport protocol](./configure-mcp-servers.mdx#transport-protocol) and any +other settings the server needs. You can use any valid Docker image, including +those hosted on Docker Hub or other registries. Click **Install server** to create and start the MCP server container. -{/* prettier-ignore */} -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. - -ToolHive downloads the MCP server's source package and builds a Docker image +a source package. ToolHive downloads the package and builds a Docker image on-the-fly. The following package formats are supported: - Node.js-based MCP servers using npm @@ -364,209 +109,43 @@ on-the-fly. The following package formats are supported: On the configuration form, enter: -1. A unique **name** for the MCP server. [Required] - -1. **Group**: The group where this server will be added. [Optional]\ - Select an existing group or keep the default. Groups help you organize - servers and control client access. See - [Organize servers into groups](./group-management.mdx) for details. - -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. - -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. - -1. **Proxy mode** [Conditional]:\ - The proxy transport mode that clients should use to connect to this server. - Choose **SSE** (`sse`) or **Streamable HTTP** (`streamable-http`). - **Streamable HTTP** is the default. This option appears only when the - **transport protocol** is `stdio` and the server is not configured for bearer - token authentication. - -1. **Proxy port** [Optional]:\ - Port for the HTTP proxy to listen on. If not specified, ToolHive - automatically assigns a random port. This is the port that AI clients connect - to, which is distinct from the **target port** that the MCP server itself - listens on inside the container. - 1. The package **protocol** (`npx`, `uvx`, or `go`). [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, - e.g. `my-mcp-package@latest` - 3. For `go`, use the GitHub repository URL with full path to the `main` - package and version, e.g. - `go://github.com/orgname/my-mcp-server/cmd/server@latest` - -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. - -1. Any **secrets** or **environment variables** required by the MCP server. - [Optional]\ - These might include API tokens, configuration options, or other sensitive - data. - - Secrets are mapped to an environment variable. Enter the variable name and - 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. + - For `npx`, use the [npm](https://www.npmjs.com/) package name and version, + for example `my-mcp-package@latest`. + - For `uvx`, use the [PyPI](https://pypi.org/) package name and version, for + example `my-mcp-package@latest`. + - For `go`, use the GitHub repository URL with the full path to the `main` + package and version, for example + `go://github.com/orgname/my-mcp-server/cmd/server@latest`. -Click **Install server** to create and start the MCP server container. +Set the [transport protocol](./configure-mcp-servers.mdx#transport-protocol) and +any other settings the server needs, then click **Install server** to build and +start the MCP server container. - - - Remote MCP icon - {' '}Custom remote MCP - - }> +### Custom remote servers On the **MCP Servers** page, click **Add an MCP server**, then choose **Add a remote MCP server** in the drop-down menu. -On the configuration form, enter: - -1. A unique **name** for the MCP server. [Required] -2. **Group**: The group where this server will be added. [Optional]\ - Select an existing group or keep the default. Groups help you organize - servers and control client access. See - [Organize servers into groups](./group-management.mdx) for details. -3. The **URL** of the remote MCP server. [Required] -4. 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. -5. **Proxy port** [Optional]:\ - Port for the HTTP proxy to listen on. If not specified, ToolHive - automatically assigns a random port. **Proxy mode** is not shown for remote - MCP servers because remote transports are always HTTP-based (SSE or - Streamable HTTP). -6. **Authorization method**: Choose how ToolHive should authenticate with the - remote server.\ - The default is **Auto-Discovered**. Use this option for MCP servers that - implement the MCP authorization spec or for servers that do not require - authentication. ToolHive automatically discovers OAuth/OIDC endpoints and - identifies itself using whichever mechanism the server supports: - - **Client ID Metadata Document (CIMD):** If the server's discovery document - sets `client_id_metadata_document_supported: true`, ToolHive presents - [`https://toolhive.dev/oauth/client-metadata.json`](https://toolhive.dev/oauth/client-metadata.json) - as the `client_id`. No registration round-trip is needed. - - **Dynamic Client Registration (DCR, RFC 7591):** When CIMD is unavailable - or rejected, ToolHive registers an OAuth client dynamically. - - Either path handles token acquisition and lifecycle automatically. - - For MCP servers that accept a bearer token in the `Authorization` header, - select **Bearer Token**. ToolHive stores the token securely and sends it as - an `Authorization: Bearer ` header on every request. For servers that - expect a different header (such as `X-API-Key`), use **Custom headers** - instead. - - **Bearer Token authentication options:** - - **Bearer token**: The token value. Enter a value to create a new secret or - select an existing secret from the provider. Secrets are stored securely - and are not exposed in plaintext in configuration files. See - [Secrets management](./secrets-management.mdx) for details. [Required] - - For MCP servers that require OAuth2 or OIDC authentication, obtain the - necessary information from the MCP server's documentation or administrator. - - **OAuth2 authentication options:** - - **Authorize URL**: The URL where users are redirected to authenticate and - authorize access to the MCP server. [Required] - - **Token URL**: The URL where your application exchanges the authorization - code for access tokens. [Required] - - **Client ID**: Your application's identifier registered with the OAuth - provider. [Required] - - **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 are not exposed in plaintext in - configuration files. See [Secrets management](./secrets-management.mdx) 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] - - **Client ID**: Your application's identifier registered with the OIDC - provider. [Required] - - **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 are not exposed in plaintext in - configuration files. See [Secrets management](./secrets-management.mdx) for - details. [Optional] - - **PKCE**: Enable Proof Key for Code Exchange (RFC 7636) for enhanced - security without requiring a client secret. [Optional] - -7. The **callback port** for the authentication redirect. [Optional] - -8. **Custom headers** [Optional]:\ - Add custom HTTP headers to inject into requests to the remote MCP server. - - **Plaintext headers**: Add static key-value pairs for headers like - `X-Tenant-ID` or correlation IDs. These values are stored and transmitted - in plaintext. - - **Headers from secrets**: For sensitive data like API keys, add headers - whose values are retrieved from ToolHive's secrets manager. Enter a header - name and either select an existing secret or enter a new value to create - one. - -Click **Install server** to connect to the remote MCP server. - -
-View examples of remote MCP authentication configuration - - - -
- - - - -## 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. - -1. In the server **Install / Configure** dialog, scroll to **Storage volumes**. -2. Use the **first row** to create your mount: - - **Host path**: choose a file or folder on your computer. - - **Container path**: where it should appear inside the server (for example, - `/data`). - - By default, mounts are in read-write mode. If you want your volume mount to - be **Read-only**, select the "Read-only access" option from the drop-down. -3. If you need additional mounts, click **Add a volume** and repeat. -4. Click **Install server** to start the server with your volume(s). - -This applies to both registry-installed servers and custom servers (Docker image -or source package). +On the configuration form, enter the +[URL](./configure-mcp-servers.mdx#url-and-transport-protocol) of the remote +server and choose an +[authorization method](./configure-mcp-servers.mdx#authorization-method). Click +**Install server** to connect to the remote MCP server. ## Manage MCP servers -On the **MCP Servers** page, you can manage your installed MCP servers: +On the **MCP Servers** page, you can manage your installed MCP servers. Each +server's card includes: + +- The server name +- Its status (Running or Stopped) with a toggle button to start or stop it +- A menu (︙) with additional options -- **Start/Stop**: Use the toggle button to start or stop the MCP server. When - you stop a server, it remains in the list but is no longer running. ToolHive - removes the server from connected AI clients while stopped. +Use the **Start/Stop** toggle to start or stop the MCP server. When you stop a +server, it remains in the list but is no longer running. ToolHive removes the +server from connected AI clients while stopped. Click the menu (︙) on the server card to access these options: @@ -648,6 +227,8 @@ for details. ## Next steps +- [Configure MCP servers](./configure-mcp-servers.mdx) for a full reference of + every setting on the configuration form. - Connect ToolHive to AI clients like GitHub Copilot or Cursor using the [client configuration guide](./client-configuration.mdx). - Customize which tools are available from registry servers using the diff --git a/sidebars.ts b/sidebars.ts index 1c8f9a4d..992cb179 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -44,6 +44,7 @@ const mcpSidebar: SidebarsConfig[string] = [ id: 'toolhive/guides-ui/run-mcp-servers', }, items: [ + 'toolhive/guides-ui/configure-mcp-servers', 'toolhive/guides-ui/group-management', 'toolhive/guides-ui/secrets-management', 'toolhive/guides-ui/network-isolation', diff --git a/static/img/mcp-servers/local-mcp.svg b/static/img/mcp-servers/local-mcp.svg deleted file mode 100644 index 544fe5b3..00000000 --- a/static/img/mcp-servers/local-mcp.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/static/img/mcp-servers/remote-mcp.svg b/static/img/mcp-servers/remote-mcp.svg deleted file mode 100644 index b581becd..00000000 --- a/static/img/mcp-servers/remote-mcp.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file From 4dc6d1bb87174646df3befe9c6b1ca8738055911 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 26 Jun 2026 11:58:51 -0400 Subject: [PATCH 2/2] Rephrase configure page description to drop hyphen Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/toolhive/guides-ui/configure-mcp-servers.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/toolhive/guides-ui/configure-mcp-servers.mdx b/docs/toolhive/guides-ui/configure-mcp-servers.mdx index 00b08f3d..7b2d6e90 100644 --- a/docs/toolhive/guides-ui/configure-mcp-servers.mdx +++ b/docs/toolhive/guides-ui/configure-mcp-servers.mdx @@ -1,8 +1,8 @@ --- title: Configure MCP servers description: - MCP server settings in the ToolHive UI - names, groups, ports, secrets, - storage volumes, network isolation, and remote authentication. + Configure MCP server settings in the ToolHive UI, including names, groups, + ports, secrets, storage volumes, network isolation, and remote authentication. --- When you install an MCP server in the ToolHive UI, the configuration form