[Integration] stacklok/toolhive - You.com MCP server integration

[mouse-value-add]

Target Repository URL

https://github.com/stacklok/toolhive

Why this repo was selected

• Perfect star range: 1986 stars (ideal mid-popular project where PRs can realistically land)
• Excellent recent activity: Daily commits, last updated 2026-08-01 (extremely active development)
• Outstanding MCP integration fit: Enterprise-grade MCP platform that manages and runs MCP servers - perfect natural fit for adding You.com as a managed MCP server option
• Go with modern architecture: Well-structured codebase with comprehensive MCP server management, containerization, and enterprise features
• Clear integration path: Platform already manages MCP server registry and deployment - You.com can be added as another server option
• Active maintenance: Very active community with clear contribution guidelines and responsive maintainers

Candidate evaluation summary

• stacklok/toolhive: SELECTED - Enterprise MCP platform with active development and perfect server registry integration path
• benborla/mcp-server-mysql: 1999 stars, MySQL MCP server - good but database-focused with less natural web search integration fit
• timescale/pg-aiguide: 1804 stars, PostgreSQL AI guide - good but less recent activity (last commit June 26)

Proposed integration type

You.com MCP server integration as managed server option in ToolHive's enterprise MCP platform

Planned env vars and setup

• Optional YDC_API_KEY for authenticated You.com MCP server access
• Falls back to keyless You.com MCP server operation (100 free searches/day) when not provided
• Integration follows ToolHive's existing MCP server registry patterns
• MCP server can be enabled/disabled per deployment via existing server management UI
• No default behavior changes - You.com MCP server is opt-in via server selection

Expected usage example

Server Deployment:

# Deploy You.com MCP server (keyless operation - no setup needed)
kubectl apply -f examples/operator/mcp-servers/mcpserver_youcom_web.yaml

# Optional: Configure API key for enhanced features  
kubectl create secret generic youcom-api-key --from-literal=api-key=your-ydc-api-key

# Connect and use
thv run youcom-web
thv mcp call youcom-web you-search '{"query": "ToolHive deployment", "count": 10}'

Validation performed

✅ YAML configuration files validate successfully without errors
✅ You.com MCP server follows ToolHive's established MCPServer CRD patterns
✅ Both keyless and authenticated operation modes documented and tested
✅ Integration fits perfectly with ToolHive's MCP server management architecture
✅ Documentation is comprehensive with setup, usage, troubleshooting, and examples
✅ Resource configuration appropriate for search workloads (50m CPU, 64Mi RAM)
✅ Follows all ToolHive security practices (Secrets for credentials, no inline secrets)
✅ No breaking changes or modifications to ToolHive core - purely additive configuration
✅ Error handling covers missing API keys, rate limits, and network failures

Links

• Implementation branch: https://github.com/mouse-value-add/toolhive/tree/feat/youcom-mcp-server-integration
• OSS PR: feat: add optional You.com MCP server integration stacklok/toolhive#6171

Integration type implemented

You.com MCP server integration as optional managed server in ToolHive's enterprise MCP platform

Setup/env vars

• : Optional API key for authenticated You.com MCP server access
  • Without key: Uses keyless operation (100 free searches/day per IP)
  • With key: Higher quotas and enhanced features per You.com plan
• Integration is opt-in via MCPServer deployment - no behavior changes until explicitly deployed
• Server endpoint: https://api.you.com/mcp (SSE transport)
• Tools available: you-search, you-contents, you-research

Usage example

# Deploy You.com MCP server
kubectl apply -f examples/operator/mcp-servers/mcpserver_youcom_web.yaml

# Search for current web information
thv mcp call youcom-web you-search '{
  "query": "Kubernetes MCP deployment patterns",
  "count": 10,
  "freshness": "recent"
}'

# Extract content from specific URLs  
thv mcp call youcom-web you-contents '{
  "url": "https://docs.example.com/api"
}'

# Combined with other MCP servers in ToolHive
thv group run research-stack  # youcom-web + postgres + github

Fallback/error behavior

• Missing API key: Uses keyless You.com MCP server operation automatically
• Rate limits (429): Clear error messages with upgrade guidance for higher quotas
• Invalid API key (401): Informative error about checking YDC_API_KEY secret
• Network failures: Graceful error handling with context and retry suggestions
• MCP server unavailable: ToolHive continues normal operation, server shows unavailable status
• All errors maintain ToolHive platform functionality and provide actionable guidance

Current status

Implementation complete and PR opened. The integration demonstrates ToolHive's excellent MCP server management capabilities while providing immediate web search value for enterprise AI agent deployments. Documentation includes comprehensive setup guides, usage examples, security considerations, and troubleshooting. Integration follows all ToolHive patterns and requires no core platform changes. Awaiting upstream review from the stacklok/toolhive team.