From a3c15c321b9a608bcfaaf85c7a1019069ac1b666 Mon Sep 17 00:00:00 2001 From: Giuseppe Scuglia Date: Tue, 5 May 2026 19:19:26 +0200 Subject: [PATCH 1/5] Document Bearer Token auth for remote MCP servers Closes #767 Co-Authored-By: Claude Opus 4.6 (1M context) --- .../_partials/_remote-mcp-auth-examples.mdx | 15 ++++++++++ docs/toolhive/guides-ui/run-mcp-servers.mdx | 30 +++++++++++++++---- 2 files changed, 39 insertions(+), 6 deletions(-) diff --git a/docs/toolhive/_partials/_remote-mcp-auth-examples.mdx b/docs/toolhive/_partials/_remote-mcp-auth-examples.mdx index af1b84c6..4dc36c1d 100644 --- a/docs/toolhive/_partials/_remote-mcp-auth-examples.mdx +++ b/docs/toolhive/_partials/_remote-mcp-auth-examples.mdx @@ -16,6 +16,21 @@ that supports this feature: 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 +static API key or token. 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` 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 diff --git a/docs/toolhive/guides-ui/run-mcp-servers.mdx b/docs/toolhive/guides-ui/run-mcp-servers.mdx index 969fc549..79eba884 100644 --- a/docs/toolhive/guides-ui/run-mcp-servers.mdx +++ b/docs/toolhive/guides-ui/run-mcp-servers.mdx @@ -145,9 +145,18 @@ remaining required information and adjust any optional settings as needed: - Obtains and manages client credentials - Handles token lifecycle automatically - For MCP servers that require manual configuration, ToolHive supports OAuth2 - and OIDC authentication. Obtain the necessary information from the MCP - server's documentation or administrator. + For MCP servers that use a static API key or token, select **Bearer Token**. + ToolHive stores the token securely and injects it as an + `Authorization: Bearer ` header on every request. + + **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 can be used by the MCP server without exposing them in plaintext. 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 @@ -405,9 +414,18 @@ On the configuration form, enter: - Obtains and manages client credentials - Handles token lifecycle automatically - For MCP servers that require manual configuration, ToolHive supports OAuth2 - and OIDC authentication. Obtain the necessary information from the MCP - server's documentation or administrator. + For MCP servers that use a static API key or token, select **Bearer Token**. + ToolHive stores the token securely and injects it as an + `Authorization: Bearer ` header on every request. + + **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 can be used by the MCP server without exposing them in plaintext. 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 From 94bb7fd5f97ee311208d4e46f3ed74e08eab66a9 Mon Sep 17 00:00:00 2001 From: Giuseppe Scuglia Date: Tue, 5 May 2026 19:31:51 +0200 Subject: [PATCH 2/5] Clarify Bearer Token secret storage description Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/toolhive/guides-ui/run-mcp-servers.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/toolhive/guides-ui/run-mcp-servers.mdx b/docs/toolhive/guides-ui/run-mcp-servers.mdx index 79eba884..2c791528 100644 --- a/docs/toolhive/guides-ui/run-mcp-servers.mdx +++ b/docs/toolhive/guides-ui/run-mcp-servers.mdx @@ -152,7 +152,7 @@ remaining required information and adjust any optional settings as needed: **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 can be used by the MCP server without exposing them in plaintext. See + 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 @@ -421,7 +421,7 @@ On the configuration form, enter: **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 can be used by the MCP server without exposing them in plaintext. See + 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 From 6a3156229dfcdd18da8fe539bcd1a3b2d41c1b31 Mon Sep 17 00:00:00 2001 From: Giuseppe Scuglia Date: Tue, 5 May 2026 19:34:47 +0200 Subject: [PATCH 3/5] Clarify secret storage description for OAuth2 and OIDC Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/toolhive/guides-ui/run-mcp-servers.mdx | 24 ++++++++++----------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/toolhive/guides-ui/run-mcp-servers.mdx b/docs/toolhive/guides-ui/run-mcp-servers.mdx index 2c791528..2a565329 100644 --- a/docs/toolhive/guides-ui/run-mcp-servers.mdx +++ b/docs/toolhive/guides-ui/run-mcp-servers.mdx @@ -167,9 +167,9 @@ remaining required information and adjust any optional settings as needed: 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 can be used by the MCP server - without exposing them in plaintext. See - [Secrets management](./secrets-management.mdx) for details. [Optional] + 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] @@ -180,9 +180,9 @@ remaining required information and adjust any optional settings as needed: 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 can be used by the MCP server - without exposing them in plaintext. See - [Secrets management](./secrets-management.mdx) for details. [Optional] + 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] @@ -436,9 +436,9 @@ On the configuration form, enter: 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 can be used by the MCP server - without exposing them in plaintext. See - [Secrets management](./secrets-management.mdx) for details. [Optional] + 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] **OIDC authentication options:** @@ -447,9 +447,9 @@ On the configuration form, enter: 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 can be used by the MCP server - without exposing them in plaintext. See - [Secrets management](./secrets-management.mdx) for details. [Optional] + 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] From b1dab1796830b69f173456b7a8cd346be51ff207 Mon Sep 17 00:00:00 2001 From: Giuseppe Scuglia Date: Wed, 6 May 2026 10:15:33 +0200 Subject: [PATCH 4/5] Clarify Bearer Token is for Authorization header only Tighten wording to specify that Bearer Token auth sends an Authorization: Bearer header, and that servers expecting different headers (e.g. X-API-Key) should use Custom headers instead. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../_partials/_remote-mcp-auth-examples.mdx | 5 +++-- docs/toolhive/guides-ui/run-mcp-servers.mdx | 16 ++++++++++------ 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/toolhive/_partials/_remote-mcp-auth-examples.mdx b/docs/toolhive/_partials/_remote-mcp-auth-examples.mdx index 4dc36c1d..af0ff48e 100644 --- a/docs/toolhive/_partials/_remote-mcp-auth-examples.mdx +++ b/docs/toolhive/_partials/_remote-mcp-auth-examples.mdx @@ -19,7 +19,8 @@ that supports this feature: #### Remote MCP server with Bearer Token authentication Bearer Token authentication is the simplest option for MCP servers that accept a -static API key or token. Brave Search's remote MCP server is one example: +bearer token in the `Authorization` header. Brave Search's remote MCP server is +one example: 1. Configuration settings: - **Server name**: `brave-search` @@ -28,7 +29,7 @@ static API key or token. Brave Search's remote MCP server is one example: - **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` header on every request. + 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 diff --git a/docs/toolhive/guides-ui/run-mcp-servers.mdx b/docs/toolhive/guides-ui/run-mcp-servers.mdx index 2a565329..f02342e6 100644 --- a/docs/toolhive/guides-ui/run-mcp-servers.mdx +++ b/docs/toolhive/guides-ui/run-mcp-servers.mdx @@ -145,9 +145,11 @@ remaining required information and adjust any optional settings as needed: - Obtains and manages client credentials - Handles token lifecycle automatically - For MCP servers that use a static API key or token, select **Bearer Token**. - ToolHive stores the token securely and injects it as an - `Authorization: Bearer ` header on every request. + 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 @@ -414,9 +416,11 @@ On the configuration form, enter: - Obtains and manages client credentials - Handles token lifecycle automatically - For MCP servers that use a static API key or token, select **Bearer Token**. - ToolHive stores the token securely and injects it as an - `Authorization: Bearer ` header on every request. + 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 From b148453938087779a350a4f18a07127f969a79fe Mon Sep 17 00:00:00 2001 From: Giuseppe Scuglia Date: Wed, 6 May 2026 13:18:16 +0200 Subject: [PATCH 5/5] Add missing PKCE option to custom remote OAuth2 docs The PKCE toggle is available in the UI for OAuth2 in both registry and custom remote flows, but was only documented for registry. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/toolhive/guides-ui/run-mcp-servers.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/toolhive/guides-ui/run-mcp-servers.mdx b/docs/toolhive/guides-ui/run-mcp-servers.mdx index f02342e6..678a8ebf 100644 --- a/docs/toolhive/guides-ui/run-mcp-servers.mdx +++ b/docs/toolhive/guides-ui/run-mcp-servers.mdx @@ -444,6 +444,8 @@ On the configuration form, enter: 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]