Simplify authentication docs to tested configurations #343
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- 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>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
JAORMX
approved these changes
Dec 2, 2025
JAORMX
pushed a commit
that referenced
this pull request
Dec 4, 2025
- 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>
JAORMX
added a commit
that referenced
this pull request
Dec 4, 2025
* Add Virtual MCP Server documentation skeleton Add documentation structure for the new Virtual MCP Server feature that aggregates multiple MCP servers into a single unified endpoint. New guides (docs/toolhive/guides-vmcp/): - index.mdx: Landing page - intro.mdx: Introduction and use cases - quickstart.mdx: Getting started with VirtualMCPServer CRD - configuration.mdx: CRD configuration reference - tool-aggregation.mdx: Conflict resolution strategies - authentication.mdx: Two-boundary auth model - composite-tools.mdx: Multi-step workflows New concept page: - concepts/vmcp-architecture.mdx: Architecture overview New tutorial: - tutorials/quickstart-vmcp.mdx: End-to-end tutorial The documentation contains placeholder TODOs for detailed examples and manifests to be filled in. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Address PR feedback for Virtual MCP documentation Changes based on review feedback: - Fix "VS Code" to "Visual Studio Code" on first use (style guide) - Fix link text to match page title in intro.mdx - Remove redundant guides-vmcp/quickstart.mdx (duplicates tutorial) - Update sidebars.ts to remove quickstart from guides section - Rewrite concepts/vmcp-architecture.mdx to be user-focused: - Explain "why" vMCP exists and when to use it - Cover key capabilities with practical examples - Follow Diataxis "Explanation" documentation style - Remove developer-focused architecture details 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fix unimplemented pass_through auth strategy references Replace pass_through (not implemented) with actual implemented strategies: - unauthenticated: for backends requiring no auth - header_injection: for API keys and bearer tokens - token_exchange: for RFC 8693 token exchange The only implemented outgoing auth strategies are: - unauthenticated - header_injection - token_exchange pass_through is in the design but not yet implemented (see TODO in pkg/vmcp/config/validator.go). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fix broken link to deleted quickstart.mdx Update configuration.mdx to link to intro.mdx instead of the deleted quickstart.mdx file. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Address PR feedback for Virtual MCP documentation - Change title from "Virtual MCP architecture" to "Understanding Virtual MCP Server" to better reflect user-focused content - Remove specific percentages (90%, 87%) that sound LLM-generated - Simplify authentication section: reference MCP spec mechanism instead of specific implementation details like token exchange - Update related links to match new title 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fix vMCP docs to match actual CRD field names - authentication.mdx: Fix outgoing auth types to use actual CRD values (discovered, pass_through, external_auth_config_ref) instead of fictional types (unauthenticated, token_exchange, header_injection) - authentication.mdx: Clarify that MCPExternalAuthConfig defines the actual auth strategies (tokenExchange, headerInjection) - composite-tools.mdx: Fix field names (dependsOn, onError, maxRetries) to match CRD; remove fictional elicitation fields (onDecline, onCancel) - configuration.mdx: Refactor from reference doc to how-to guide; link to autogenerated CRD spec; fix incoming auth types (anonymous, local, oidc with kubernetes/configMap/inline subtypes) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Add working YAML examples to vMCP quickstart tutorial Replace TODO placeholders with actual working examples provided by jhrozek from testing: - MCPGroup manifest for demo-tools - MCPServer manifests for fetch and osv servers - VirtualMCPServer manifest with anonymous auth and prefix strategy 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fix vMCP docs: remove non-existent CRD features Verified against VirtualMCPServer CRD (virtualmcpserver_types.go): - Remove pass_through from outgoing auth (CRD only has discovered, external_auth_config_ref) - Add Failed to status phase list (CRD has Pending, Ready, Degraded, Failed) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Address jhrozek's PR feedback on vMCP documentation Based on PR review feedback: authentication.mdx: - Add OIDC inline configuration example with clientSecretRef - Add Kubernetes service account token example - REMOVE token caching section (not implemented per jhrozek) configuration.mdx: - REMOVE token caching section (not implemented) - Add link to quickstart for MCPGroup reference composite-tools.mdx: - Add info admonition noting elicitation has not been extensively tested 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Remove unimplemented features, add tool aggregation example authentication.mdx: - Remove Cedar authorization section (not implemented for vMCP) - Remove Cedar policies link from related information tool-aggregation.mdx: - Add note that MCPToolConfig via toolConfigRef is in development - Add complete working example with MCPGroup, MCPServers, and VirtualMCPServer showing prefix-based conflict resolution Verified against CRD definitions in virtualmcpserver_types.go, mcpserver_types.go, and mcpgroup_types.go. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Add workflow examples to composite-tools.mdx Replace TODO placeholders with working examples: - Incident investigation: parallel data gathering with dependsOn - Deployment with approval: elicitation step for human-in-the-loop - Cross-system data aggregation: template expansion between steps - Complete VirtualMCPServer manifest with inline composite tool Fixed parameter format to use JSON Schema (type: object, properties, required) instead of shorthand notation. Verified against CompositeToolSpec and WorkflowStep definitions in virtualmcpserver_types.go. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Add VS Code configuration to vMCP quickstart Adds VS Code/Copilot mcp.json configuration instructions to the Virtual MCP Server quickstart tutorial. Includes file paths for macOS and Linux, and links to client compatibility reference for other MCP clients. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fix vMCP documentation based on cluster testing (#331) * Fix VirtualMCPServer output columns in quickstart Update expected kubectl output to match actual CRD printer columns: - Change STATUS to PHASE - Add BACKENDS and READY columns Verified by testing against live cluster. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Fix minimal VirtualMCPServer config to include required incomingAuth The vMCP binary requires incomingAuth.type to be specified. Without it, the pod crashes with: "incoming_auth.type must be one of: oidc, local, anonymous" Verified by testing against live cluster. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Add note about optional clientSecretRef for token introspection 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com> * Fix composite tools example tool reference (#337) - Change fetch.fetch_url to fetch.fetch (correct tool name) - Add comment clarifying llm.summarize is a hypothetical backend 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com> * Simplify authentication docs to tested configurations (#343) - 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> * Fix outgoing auth and clarify OIDC clientSecretRef (#344) * Simplify outgoing auth in configuration docs - Remove broken default.type: discovered config - Remove broken source: mixed with external_auth_config_ref example - Simplify to just source: discovered (tested working) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Clarify OIDC clientSecretRef is for opaque tokens - Separate basic OIDC example (without clientSecretRef) - Add explanation for opaque OAuth token introspection - Show full example with clientSecretRef for that use case 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com> * Polish vMCP docs (#347) * Polish vMCP documentation - Apply consistent terminology: 'Virtual MCP Server (vMCP)' on first mention, then 'vMCP' - Rewrite bullet lists with complete sentences - Add MCPGroup context explanation on first use - Expand outgoing auth configuration details - Enhance experimental feature warning - Improve language directness * Add vMCP usage to style guide and LLM instructions * Note that vMCP is part of the operator * Add vMCP to nav menu * Polish the intro * Polish the config guide - Add MCPGroup section since it doesn't have its own guide - Remove redundant auth content, just point to auth guide - Note that ClusterIP can be exposed via Ingress/Gateway * Add vMCP CRDs to operator deployment guide * Rename vMCP concepts file and re-order guides Feels like the tool aggregation and composite guides logically belong together. * Polish auth guide * Polish tool aggregation guide * Polish composite tools guide - Soften technical jargon ("DAG") - Add basic info up front before the full use cases - Make sure all YAML snippets have parent keys to make location and indentation clear * Polish the quickstart and concepts guides * Add quickstart and concepts links to index * Clarify inbound auth spec conformance * Clarify service options --------- Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> Co-authored-by: Dan Barr <6922515+danbarr@users.noreply.github.com> * Address feedback about terminology Signed-off-by: Juan Antonio Osorio <ozz@stacklok.com> --------- Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> Signed-off-by: Juan Antonio Osorio <ozz@stacklok.com> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Jakub Hrozek <jakub.hrozek@posteo.se> Co-authored-by: Dan Barr <danbarr@users.noreply.github.com> Co-authored-by: Dan Barr <6922515+danbarr@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Context
Tested outgoing auth configurations against live Kubernetes cluster:
source: discovered✅ workssource: inline✅ worksdefault.type: discovered❌ CRD accepts, binary rejectsdefault.type: unauthenticated❌ binary accepts, CRD rejectsThe inline mode was removed since its intended purpose (pointing to externalAuthConfigRef) doesn't work due to the type mismatch.
Test plan
outgoingAuth.source: discoveredagainst live cluster🤖 Generated with Claude Code