From 3ea9710553d4bf11c994756da59520b9526e67b9 Mon Sep 17 00:00:00 2001
From: Jakub Hrozek <jakub@stacklok.com>
Date: Tue, 2 Dec 2025 10:39:49 +0000
Subject: [PATCH] Simplify authentication docs to tested configurations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add warning for anonymous incoming authentication
- Simplify outgoing auth to discovery mode only (tested working)
- Remove broken default config (CRD/binary type mismatch)
- Remove external_auth_config_ref examples (pending code fixes)
- Remove TODO placeholders
- Add link to configuration guide

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/toolhive/guides-vmcp/authentication.mdx | 45 ++++++--------------
 1 file changed, 13 insertions(+), 32 deletions(-)

diff --git a/docs/toolhive/guides-vmcp/authentication.mdx b/docs/toolhive/guides-vmcp/authentication.mdx
index 8b393d4c..2aebcfa7 100644
--- a/docs/toolhive/guides-vmcp/authentication.mdx
+++ b/docs/toolhive/guides-vmcp/authentication.mdx
@@ -57,6 +57,12 @@ spec:
     type: anonymous
 ```
 
+:::warning
+
+Never use `anonymous` incoming authentication in production environments.
+
+:::
+
 ### OIDC authentication
 
 Validate tokens from an external identity provider:
@@ -112,51 +118,26 @@ validates service account tokens. The defaults work for most clusters:
 
 ## Outgoing authentication
 
-Configure how Virtual MCP authenticates to backend MCP servers. Outgoing
-authentication is configured through `MCPExternalAuthConfig` resources.
+Configure how Virtual MCP authenticates to backend MCP servers.
 
-### Discovery mode (recommended)
+### Discovery mode
 
 When using discovery mode, Virtual MCP checks each backend MCPServer's
 `externalAuthConfigRef` to determine how to authenticate. If a backend has no
-auth config, Virtual MCP uses the specified default.
+auth config, Virtual MCP connects without authentication.
 
 ```yaml
 spec:
   outgoingAuth:
     source: discovered
-    default:
-      type: discovered
-```
-
-### External auth config reference
-
-Reference an `MCPExternalAuthConfig` resource for specific backends:
-
-```yaml
-spec:
-  outgoingAuth:
-    source: inline
-    backends:
-      github:
-        type: external_auth_config_ref
-        externalAuthConfigRef:
-          name: github-auth
 ```
 
-The `MCPExternalAuthConfig` resource defines the actual authentication strategy:
-
-- **Token exchange**: Exchange the client's token for a backend-specific token
-  using RFC 8693
-- **Header injection**: Inject a static header value (such as an API key)
-
-{/* TODO: Add MCPExternalAuthConfig examples */}
-
-## Example: Complete authentication setup
-
-{/* TODO: Add complete authentication example */}
+This is the recommended approach for most deployments. Backends that don't
+require authentication work automatically, while backends with
+`externalAuthConfigRef` configured use their specified authentication method.
 
 ## Related information
 
 - [Authentication framework concepts](../concepts/auth-framework.mdx)
+- [VirtualMCPServer configuration](./configuration.mdx)
 - [Token exchange in Kubernetes](../guides-k8s/token-exchange-k8s.mdx)