From 52e55728260d6cbe949fbe216473fd7c9a506b91 Mon Sep 17 00:00:00 2001
From: Jakub Hrozek <jakub@stacklok.com>
Date: Thu, 21 May 2026 17:05:51 +0100
Subject: [PATCH 1/2] Document static header injection outgoing auth

Add a section to the vMCP authentication guide describing the
headerInjection outgoing auth strategy: when to use it, the
Secret + MCPExternalAuthConfig pair, how to wire it into a
VirtualMCPServer via inline or discovered source, and the
Authorization: Bearer variant. Notes that values must come from
a Secret and that backend pods need a restart to pick up
rotations.
---
 docs/toolhive/guides-vmcp/authentication.mdx | 66 ++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/docs/toolhive/guides-vmcp/authentication.mdx b/docs/toolhive/guides-vmcp/authentication.mdx
index 13fac9fa..df38b065 100644
--- a/docs/toolhive/guides-vmcp/authentication.mdx
+++ b/docs/toolhive/guides-vmcp/authentication.mdx
@@ -205,6 +205,72 @@ See
 [Configure token exchange for backend authentication](../guides-k8s/token-exchange-k8s.mdx)
 for details on using service account token exchange for backend authentication.
 
+### Static header injection
+
+The `headerInjection` outgoing auth strategy injects a fixed HTTP header into
+every request to a backend. Use it when the backend authenticates with a
+pre-issued API key or static bearer token rather than per-user OAuth — for
+example, an MCP server that wraps a SaaS API behind a single shared credential.
+
+Store the header value in a Secret, then create an `MCPExternalAuthConfig` of
+type `headerInjection` that references it:
+
+```yaml title="Secret"
+apiVersion: v1
+kind: Secret
+metadata:
+  name: backend-api-key
+  namespace: toolhive-system
+type: Opaque
+stringData:
+  value: <YOUR_API_KEY>
+```
+
+```yaml title="MCPExternalAuthConfig resource"
+apiVersion: toolhive.stacklok.dev/v1beta1
+kind: MCPExternalAuthConfig
+metadata:
+  name: backend-api-key-header
+  namespace: toolhive-system
+spec:
+  type: headerInjection
+  headerInjection:
+    headerName: X-API-Key
+    valueSecretRef:
+      name: backend-api-key
+      key: value
+```
+
+Reference the config from the VirtualMCPServer's outgoing auth, the same way as
+other strategies:
+
+```yaml title="VirtualMCPServer resource"
+spec:
+  outgoingAuth:
+    source: inline
+    backends:
+      backend-private-api:
+        type: externalAuthConfigRef
+        externalAuthConfigRef:
+          name: backend-api-key-header
+```
+
+Alternatively, attach the `MCPExternalAuthConfig` to a backend `MCPServer` via
+its `externalAuthConfigRef` and use `outgoingAuth.source: discovered` to pick it
+up automatically.
+
+For an `Authorization: Bearer <token>` header, set `headerName: Authorization`
+and store the full `Bearer <token>` string (including the `Bearer` prefix) in
+the Secret value.
+
+:::note
+
+The header value must come from a Kubernetes Secret — plaintext inline values
+are not accepted at the CRD layer. Rotating the credential is a matter of
+updating the Secret; restart the affected backend pods to pick up the new value.
+
+:::
+
 ### Upstream token injection
 
 The `upstreamInject` outgoing auth strategy injects a user's upstream access

From a092b0e39a1e613cd7fd16da8a45c56466bcedf8 Mon Sep 17 00:00:00 2001
From: Jakub Hrozek <jakub.hrozek@posteo.se>
Date: Thu, 21 May 2026 18:33:29 +0200
Subject: [PATCH 2/2] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 docs/toolhive/guides-vmcp/authentication.mdx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/toolhive/guides-vmcp/authentication.mdx b/docs/toolhive/guides-vmcp/authentication.mdx
index df38b065..9978d1dc 100644
--- a/docs/toolhive/guides-vmcp/authentication.mdx
+++ b/docs/toolhive/guides-vmcp/authentication.mdx
@@ -267,7 +267,9 @@ the Secret value.
 
 The header value must come from a Kubernetes Secret — plaintext inline values
 are not accepted at the CRD layer. Rotating the credential is a matter of
-updating the Secret; restart the affected backend pods to pick up the new value.
+updating the Secret; restart the vMCP deployment/pods, or whichever ToolHive
+workload is making the outbound requests using this `MCPExternalAuthConfig`, to
+pick up the new value.
 
 :::