Correct static auth and DCR guidance

danbarr · danbarr · commit be6fdfd89cb6 · 2026-07-21T17:52:37.000-04:00
diff --git a/docs/toolhive/guides-k8s/auth-k8s.mdx b/docs/toolhive/guides-k8s/auth-k8s.mdx
@@ -49,103 +49,16 @@ authenticated, your MCP server or `MCPRemoteProxy` may separately need its own
 way to authenticate to the backend API it calls. Which pattern fits depends on
 that backend's relationship to your identity provider:
 
-| Scenario                                                            | Pattern                       | K8s guide                                                                                                                                                                                                              |
-| ------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Backend only accepts API keys or static credentials                 | Static credentials            | [Inject static backend credentials](#inject-static-backend-credentials), [run a server with secrets](./run-mcp-k8s.mdx#run-a-server-with-secrets), or use the [HashiCorp Vault integration](../integrations/vault.mdx) |
-| Backend trusts the same IdP as your clients                         | Token exchange (RFC 8693)     | [Configure token exchange](./token-exchange-k8s.mdx)                                                                                                                                                                   |
-| Backend trusts a federated IdP (for example, AWS)                   | Federated token exchange      | [AWS STS integration](../integrations/aws-sts.mdx)                                                                                                                                                                     |
-| Backend is an external API with no federation (for example, GitHub) | Embedded authorization server | [Run an embedded OAuth server](#run-an-embedded-oauth-server)                                                                                                                                                          |
+| Scenario                                                            | Pattern                       | K8s guide                                                                                                                                                                                                                                                                                |
+| ------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Backend only accepts API keys or static credentials                 | Static credentials            | [Run a server with secrets](./run-mcp-k8s.mdx#run-a-server-with-secrets) or use the [HashiCorp Vault integration](../integrations/vault.mdx) for `MCPServer`; [inject headers into upstream requests](./remote-mcp-proxy.mdx#inject-headers-into-upstream-requests) for `MCPRemoteProxy` |
+| Backend trusts the same IdP as your clients                         | Token exchange (RFC 8693)     | [Configure token exchange](./token-exchange-k8s.mdx)                                                                                                                                                                                                                                     |
+| Backend trusts a federated IdP (for example, AWS)                   | Federated token exchange      | [AWS STS integration](../integrations/aws-sts.mdx)                                                                                                                                                                                                                                       |
+| Backend is an external API with no federation (for example, GitHub) | Embedded authorization server | [Run an embedded OAuth server](#run-an-embedded-oauth-server)                                                                                                                                                                                                                            |
 
 For the full comparison and why each pattern fits its scenario, see
 [Choosing the right backend authentication pattern](../concepts/backend-auth.mdx#choosing-the-right-backend-authentication-pattern).
 
-### Inject static backend credentials
-
-Use an `MCPExternalAuthConfig` when the MCP server can't read a credential from
-an environment variable, or when you want multiple workloads to share one
-authentication configuration. ToolHive injects the credential into outbound HTTP
-requests at the proxy layer.
-
-This differs from [`spec.secrets`](./run-mcp-k8s.mdx#run-a-server-with-secrets)
-and the [HashiCorp Vault integration](../integrations/vault.mdx), which pass
-credentials to the MCP server process as environment variables.
-
-Two static credential types are available:
-
-- `headerInjection` adds one custom header using `headerName` and a
-  `valueSecretRef`.
-- `bearerToken` reads `tokenSecretRef` and adds it as
-  `Authorization: Bearer <TOKEN_VALUE>`.
-
-First, store the credential in a Secret:
-
-```yaml title="backend-api-key-secret.yaml"
-apiVersion: v1
-kind: Secret
-metadata:
-  name: backend-api-key
-  namespace: toolhive-system
-type: Opaque
-stringData:
-  api-key: '<YOUR_API_KEY>'
-```
-
-Then create the `MCPExternalAuthConfig`:
-
-```yaml title="backend-api-key-auth.yaml"
-apiVersion: toolhive.stacklok.dev/v1beta1
-kind: MCPExternalAuthConfig
-metadata:
-  name: backend-api-key
-  namespace: toolhive-system
-spec:
-  type: headerInjection
-  headerInjection:
-    headerName: X-API-Key
-    valueSecretRef:
-      name: backend-api-key
-      key: api-key
-```
-
-For an `Authorization: Bearer` header, use this configuration instead. Store
-only the token value in the Secret, without the `Bearer` prefix:
-
-```yaml title="backend-bearer-auth.yaml"
-apiVersion: toolhive.stacklok.dev/v1beta1
-kind: MCPExternalAuthConfig
-metadata:
-  name: backend-bearer-token
-  namespace: toolhive-system
-spec:
-  type: bearerToken
-  bearerToken:
-    tokenSecretRef:
-      name: backend-bearer-token
-      key: token
-```
-
-Reference the configuration from an `MCPServer` or `MCPRemoteProxy` in the same
-namespace:
-
-```yaml title="MCPServer or MCPRemoteProxy: externalAuthConfigRef"
-spec:
-  externalAuthConfigRef:
-    name: backend-api-key
-```
-
-The same `MCPExternalAuthConfig` can be referenced by multiple workloads. To
-configure headers specifically for one `MCPRemoteProxy`, including multiple
-plaintext or Secret-backed headers, use
-[`headerForward`](./remote-mcp-proxy.mdx#inject-custom-headers) instead.
-
-:::note[Client authentication is separate]
-
-Static credential injection authenticates ToolHive to the backend. It does not
-authenticate clients connecting to ToolHive. Configure client authentication
-separately using one of the approaches below.
-
-:::
-
 ## Authenticate with OIDC
 
 Both external IdP and Kubernetes service-to-service authentication use the same
diff --git a/docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx b/docs/toolhive/guides-k8s/embedded-auth-server-k8s.mdx
@@ -319,15 +319,15 @@ instead.
 
 ## Configure session storage
 
-The embedded authorization server caches upstream tokens and DCR-issued client
-credentials in the same store as sessions. By default, that store is in memory,
-so these values are lost when pods restart and users must re-authenticate. When
-you use DCR, a restart also registers a new client with the upstream and leaves
-the previous registration orphaned. For production deployments, configure a
-Redis backend so ToolHive can reuse the DCR credentials and sessions after a
-restart. Add one of the following `storage` blocks at
-`spec.embeddedAuthServer.storage` in the `MCPExternalAuthConfig`. The `redis`
-block supports three connection modes; you must set exactly one:
+The embedded authorization server caches upstream tokens and client credentials
+obtained through DCR with an upstream provider in the same store as sessions. By
+default, that store is in memory, so these values are lost when pods restart and
+users must re-authenticate. When you use upstream DCR, a restart also registers
+a new client with the upstream and leaves the previous registration orphaned.
+For production deployments, configure a Redis backend so ToolHive can reuse the
+DCR credentials and sessions after a restart. Add one of the following `storage`
+blocks at `spec.embeddedAuthServer.storage` in the `MCPExternalAuthConfig`. The
+`redis` block supports three connection modes; you must set exactly one:
 
 - **Sentinel** (`sentinelConfig`) - self-managed Redis with Sentinel-based high
   availability (HA)
@@ -396,21 +396,22 @@ For a complete walkthrough including deploying Redis Sentinel from scratch, see
 
 ## Configure MCP client registration
 
-MCP clients must identify themselves to the embedded authorization server. DCR
-is enabled by default for backward compatibility. Enable CIMD for clients that
-support the MCP specification's preferred registration mechanism. You can also
-set baseline scopes for clients that need to request scopes beyond those in
-their registration metadata.
+MCP clients must identify themselves to the embedded authorization server. The
+server always accepts Dynamic Client Registration (DCR) requests from MCP
+clients; no configuration is required. Enable CIMD for clients that support the
+MCP specification's preferred registration mechanism. You can also set baseline
+scopes for clients that need to request scopes beyond those in their
+registration metadata.
 
 ### Enable CIMD for zero-registration clients
 
-DCR requires every client to register before its first authorization request.
-Some MCP clients, including recent VS Code builds, can instead present an HTTPS
-URL that hosts a Client ID Metadata Document (CIMD), letting the authorization
-server resolve client metadata on demand with no prior registration step. CIMD
-is the MCP specification's preferred client registration mechanism; DCR is the
-backward-compatibility fallback. Add `cimd` under `spec.embeddedAuthServer` in
-the `MCPExternalAuthConfig`:
+Client-side DCR requires every client to register before its first authorization
+request. Some MCP clients, including recent VS Code builds, can instead present
+an HTTPS URL that hosts a Client ID Metadata Document (CIMD), letting the
+authorization server resolve client metadata on demand with no prior
+registration step. CIMD is the MCP specification's preferred client registration
+mechanism; client-side DCR is the backward-compatibility fallback. Add `cimd`
+under `spec.embeddedAuthServer` in the `MCPExternalAuthConfig`:
 
 ```yaml title="MCPExternalAuthConfig: CIMD configuration"
 spec:
@@ -580,6 +581,11 @@ to create an application in a provider dashboard. Add `dcrConfig` to an
 `oauth2Config` upstream to have the embedded authorization server register
 itself at runtime using RFC 7591.
 
+In this flow, ToolHive registers with the upstream provider as an OAuth client.
+This is separate from MCP clients registering with ToolHive's embedded
+authorization server in
+[Configure MCP client registration](#configure-mcp-client-registration).
+
 This example uses an RFC 8414 discovery document. ToolHive reads the
 `registration_endpoint` and other provider metadata from `discoveryUrl`:
 
@@ -615,6 +621,9 @@ spec:
 Set `authorizationEndpoint` and `tokenEndpoint` even when the discovery document
 advertises them. The CRD requires both fields on `oauth2Config`.
 
+For a complete deployment that uses `discoveryUrl` with Notion, see the
+[Notion MCP server guide](../guides-mcp/notion-remote.mdx).
+
 If the provider gives you a registration URL directly, use
 `registrationEndpoint` instead of `discoveryUrl` in the `MCPExternalAuthConfig`
 provider's `oauth2Config`:
@@ -641,17 +650,10 @@ endpoints and the scopes that ToolHive should request.
 Don't set `clientId` or `clientSecretRef` when you set `dcrConfig`. ToolHive
 obtains the client ID and client secret from the DCR response.
 
-#### Optional DCR fields
-
-Use these fields only when the upstream provider requires them:
+#### Authorize registration with an initial access token
 
-| Field                   | Purpose                                                                                                                                  |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `initialAccessTokenRef` | References a Secret containing the bearer token that authorizes the registration request.                                                |
-| `softwareId`            | Sends an RFC 7591 `software_id` value that identifies the client software independently of a particular registration.                    |
-| `softwareStatement`     | Sends a signed RFC 7591 `software_statement` JWT. The value is visible in the resource and etcd backups, so don't put secrets inside it. |
-
-For an initial access token, create a Secret in the same namespace:
+If the upstream provider requires an initial access token, create a Secret in
+the same namespace:
 
 ```yaml title="dcr-initial-access-token.yaml"
 apiVersion: v1
@@ -664,22 +666,18 @@ stringData:
   token: '<YOUR_DCR_INITIAL_ACCESS_TOKEN>'
 ```
 
-Then add the reference to the upstream provider's `oauth2Config.dcrConfig` in
-the `MCPExternalAuthConfig`:
+Then add `initialAccessTokenRef` to the upstream provider's
+`oauth2Config.dcrConfig` in the `MCPExternalAuthConfig`. ToolHive sends the
+Secret value as a bearer token when it calls the registration endpoint:
 
-```yaml title="MCPExternalAuthConfig: optional DCR fields"
+```yaml title="MCPExternalAuthConfig: DCR initial access token"
 dcrConfig:
   registrationEndpoint: 'https://mcp.example.com/register'
   initialAccessTokenRef:
     name: dcr-initial-access-token
     key: token
-  softwareId: 'toolhive-embedded-auth'
-  softwareStatement: '<YOUR_SIGNED_SOFTWARE_STATEMENT_JWT>'
 ```
 
-The `softwareStatement` is a signed attestation, not a secret. Anyone who can
-read the `MCPExternalAuthConfig` can see its contents.
-
 ### Extract identity from the token response
 
 Some providers don't expose a userinfo endpoint but return user identity in the
diff --git a/docs/toolhive/guides-k8s/mcp-server-entry.mdx b/docs/toolhive/guides-k8s/mcp-server-entry.mdx
@@ -229,8 +229,9 @@ spec:
 ```
 
 For sensitive values like API keys, use `addHeadersFromSecret` instead. See the
-[Inject custom headers](./remote-mcp-proxy.mdx#inject-custom-headers) section of
-the MCPRemoteProxy guide for the full syntax, which MCPServerEntry shares.
+[Inject headers into upstream requests](./remote-mcp-proxy.mdx#inject-headers-into-upstream-requests)
+section of the MCPRemoteProxy guide for the full syntax, which MCPServerEntry
+shares.
 
 ## Complete example
 
diff --git a/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx b/docs/toolhive/guides-k8s/remote-mcp-proxy.mdx
@@ -511,18 +511,12 @@ condition to `False`, moves the resource to phase `Failed`, and stops updating
 the Deployment. See [Check remote proxy status](#check-remote-proxy-status) to
 inspect the failure message.
 
-### Inject custom headers
+### Inject headers into upstream requests
 
 Some remote MCP servers require custom headers for tenant identification, API
 keys, or other purposes. Use the `headerForward` field to inject headers into
-every request forwarded to the remote server.
-
-To put a single API key or bearer token behind a reusable authentication
-resource, use an
-[`MCPExternalAuthConfig`](./auth-k8s.mdx#inject-static-backend-credentials)
-instead. That approach also works with `MCPServer`. Use `headerForward` when you
-want to configure headers specifically for this proxy, including multiple
-plaintext or Secret-backed values.
+every request forwarded to the remote server. This configuration belongs to one
+`MCPRemoteProxy` and supports multiple plaintext or Secret-backed values.
 
 For non-sensitive values like tenant IDs or correlation headers, use
 `addPlaintextHeaders`:
@@ -609,6 +603,58 @@ spec:
 
 :::
 
+#### Reuse a bearer token across remote proxies
+
+To inject the same `Authorization: Bearer <TOKEN>` header from multiple
+`MCPRemoteProxy` resources, store the token behind a shared
+`MCPExternalAuthConfig` of type `bearerToken`.
+
+First, create a Secret containing only the token value, without the `Bearer`
+prefix:
+
+```yaml title="backend-bearer-token-secret.yaml"
+apiVersion: v1
+kind: Secret
+metadata:
+  name: backend-bearer-token
+  namespace: toolhive-system
+type: Opaque
+stringData:
+  token: '<YOUR_BEARER_TOKEN>'
+```
+
+Create the authentication configuration in the same namespace:
+
+```yaml title="backend-bearer-auth.yaml"
+apiVersion: toolhive.stacklok.dev/v1beta1
+kind: MCPExternalAuthConfig
+metadata:
+  name: backend-bearer-auth
+  namespace: toolhive-system
+spec:
+  type: bearerToken
+  bearerToken:
+    tokenSecretRef:
+      name: backend-bearer-token
+      key: token
+```
+
+Reference it from each remote proxy that uses the token:
+
+```yaml title="MCPRemoteProxy: externalAuthConfigRef"
+spec:
+  externalAuthConfigRef:
+    name: backend-bearer-auth
+```
+
+Both `headerForward` and `bearerToken` authenticate the proxy to the remote MCP
+server. They do not authenticate clients connecting to the proxy. Configure
+client authentication separately with `oidcConfigRef` or `authServerRef`.
+
+For static credentials sent from a Virtual MCP Server (vMCP) directly to its
+backends, see
+[Inject a static credential](../guides-vmcp/authentication.mdx#inject-a-static-credential-header-injection).
+
 ## Quick start example
 
 For testing and development, you can use the public MCP specification server:
diff --git a/docs/toolhive/guides-vmcp/authentication.mdx b/docs/toolhive/guides-vmcp/authentication.mdx
@@ -463,7 +463,8 @@ spec:
 
 Alternatively, attach the `MCPExternalAuthConfig` to a backend `MCPServer` via
 its `externalAuthConfigRef` and use `outgoingAuth.source: discovered` to pick it
-up automatically.
+up automatically. In that case, the reference is metadata that vMCP reads; the
+`MCPServer` does not inject the header itself.
 
 For an `Authorization: Bearer <token>` header, set `headerName: Authorization`
 and store the full `Bearer <token>` string (including the `Bearer` prefix) in
