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..7b2d6e90 --- /dev/null +++ b/docs/toolhive/guides-ui/configure-mcp-servers.mdx @@ -0,0 +1,343 @@ +--- +title: Configure MCP servers +description: + 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 +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