Skip to content

Commit 3378369

Browse files
jhrozekCopilot
andauthored
Document static header injection outgoing auth in vMCP (#892)
* 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. * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
1 parent c0992a0 commit 3378369

1 file changed

Lines changed: 68 additions & 0 deletions

File tree

docs/toolhive/guides-vmcp/authentication.mdx

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,6 +205,74 @@ See
205205
[Configure token exchange for backend authentication](../guides-k8s/token-exchange-k8s.mdx)
206206
for details on using service account token exchange for backend authentication.
207207

208+
### Static header injection
209+
210+
The `headerInjection` outgoing auth strategy injects a fixed HTTP header into
211+
every request to a backend. Use it when the backend authenticates with a
212+
pre-issued API key or static bearer token rather than per-user OAuth — for
213+
example, an MCP server that wraps a SaaS API behind a single shared credential.
214+
215+
Store the header value in a Secret, then create an `MCPExternalAuthConfig` of
216+
type `headerInjection` that references it:
217+
218+
```yaml title="Secret"
219+
apiVersion: v1
220+
kind: Secret
221+
metadata:
222+
name: backend-api-key
223+
namespace: toolhive-system
224+
type: Opaque
225+
stringData:
226+
value: <YOUR_API_KEY>
227+
```
228+
229+
```yaml title="MCPExternalAuthConfig resource"
230+
apiVersion: toolhive.stacklok.dev/v1beta1
231+
kind: MCPExternalAuthConfig
232+
metadata:
233+
name: backend-api-key-header
234+
namespace: toolhive-system
235+
spec:
236+
type: headerInjection
237+
headerInjection:
238+
headerName: X-API-Key
239+
valueSecretRef:
240+
name: backend-api-key
241+
key: value
242+
```
243+
244+
Reference the config from the VirtualMCPServer's outgoing auth, the same way as
245+
other strategies:
246+
247+
```yaml title="VirtualMCPServer resource"
248+
spec:
249+
outgoingAuth:
250+
source: inline
251+
backends:
252+
backend-private-api:
253+
type: externalAuthConfigRef
254+
externalAuthConfigRef:
255+
name: backend-api-key-header
256+
```
257+
258+
Alternatively, attach the `MCPExternalAuthConfig` to a backend `MCPServer` via
259+
its `externalAuthConfigRef` and use `outgoingAuth.source: discovered` to pick it
260+
up automatically.
261+
262+
For an `Authorization: Bearer <token>` header, set `headerName: Authorization`
263+
and store the full `Bearer <token>` string (including the `Bearer` prefix) in
264+
the Secret value.
265+
266+
:::note
267+
268+
The header value must come from a Kubernetes Secret — plaintext inline values
269+
are not accepted at the CRD layer. Rotating the credential is a matter of
270+
updating the Secret; restart the vMCP deployment/pods, or whichever ToolHive
271+
workload is making the outbound requests using this `MCPExternalAuthConfig`, to
272+
pick up the new value.
273+
274+
:::
275+
208276
### Upstream token injection
209277

210278
The `upstreamInject` outgoing auth strategy injects a user's upstream access

0 commit comments

Comments
 (0)