Address feedback and change scenarios to the ones I used in demos

Signed-off-by: Juan Antonio Osorio <[email protected]>

Author: JAORMX

docs/toolhive/concepts/vmcp.mdx

@@ -16,9 +16,9 @@ workflows.
 its own authentication, manually coordinate multi-step workflows across systems,
 and repeatedly configure the same parameters.
 
-**With vMCP**: Connect once to a unified endpoint that aggregates all backends,
-execute complex multi-system workflows declaratively, and use pre-configured
-tools with sensible defaults.
+**With vMCP**: Connect once to a unified endpoint that aggregates all backend
+MCP servers, execute complex multi-system workflows declaratively, and use
+pre-configured tools with sensible defaults.
 
 ## Core value propositions
 
@@ -37,17 +37,17 @@ vMCP delivers four key benefits:
 ### Multi-server aggregation
 
 Managing 10-20+ MCP server connections is overwhelming. Each server needs its
-own configuration, authentication, and maintenance. vMCP aggregates all backends
-into one endpoint with automatic conflict resolution.
+own configuration, authentication, and maintenance. vMCP aggregates all backend
+MCP servers into one endpoint with automatic conflict resolution.
 
 **Example scenario**: An engineering team needs access to 8 backend servers
 (GitHub, Jira, Slack, Confluence, PagerDuty, Datadog, AWS, and internal company
 docs). Instead of configuring 8 separate connections, they configure one vMCP
 connection with SSO. This significantly reduces configuration complexity and
 makes onboarding new team members much easier.
 
-When multiple backends have tools with the same name (for example, both GitHub
-and Jira have `create_issue`), vMCP automatically prefixes them:
+When multiple backend MCP servers have tools with the same name (for example,
+both GitHub and Jira have `create_issue`), vMCP automatically prefixes them:
 `github_create_issue`, `jira_create_issue`. You can also define custom names for
 clarity.
 
@@ -57,18 +57,19 @@ Real-world tasks span multiple systems and require manual orchestration. vMCP
 lets you define declarative workflows with parallel execution, conditionals,
 error handling, and human-in-the-loop approval gates.
 
-**Example scenario**: During an incident investigation, you need logs from your
-logging system, metrics from your monitoring platform, traces from your tracing
-service, and infrastructure status from your cloud provider. Without vMCP, an
-engineer manually runs 4 commands sequentially and aggregates results. With
-vMCP, you fetch all of this in parallel, automatically aggregate it into a
-formatted report, and create a Jira ticket with all the data. This workflow is
-reusable for every incident.
+**Real example**: The `aggregate_docs` composite tool fetches documentation from
+multiple sources in parallel (MCP specification, Python SDK, and server
+implementations), then aggregates them into a structured report with metadata.
+Without vMCP, you'd manually fetch each URL sequentially. With vMCP, all three
+fetches run concurrently, and results are automatically combined with timing
+information and status for each source.
 
-**Example scenario**: For an app deployment, merge the pull request, wait for
-tests, ask a human for approval, deploy only if approved, and notify the team in
-Slack. vMCP handles this entire flow declaratively, with automatic rollback on
-deployment failure.
+**Real example**: The `investigate_image` composite tool analyzes container
+images by querying an OCI registry for image info, manifest, and configuration
+in a coordinated workflow. The first step fetches basic info, then the manifest
+and config steps run in parallel (both depend on the initial step). This
+demonstrates how vMCP orchestrates multi-step operations across backend MCP
+servers with dependency management.
 
 ### Tool customization and overrides
 
@@ -91,21 +92,24 @@ Generic servers require repetitive parameter specification. You always use the
 same repo, channel, or database. vMCP lets you create specialized instances with
 pre-configured defaults.
 
-**Example scenario**: Without vMCP, every GitHub query requires specifying
-`repo: stacklok/toolhive`. With vMCP, you pre-configure this default - engineers
-never specify the repo parameter, and they can't accidentally query the wrong
-repository. This eliminates hundreds of repetitive parameter entries per week.
+**Real example**: The `analyze_repository` composite tool demonstrates parameter
+defaults. The tool accepts `owner` and `repo` parameters with defaults set to
+`modelcontextprotocol` and `specification`. Engineers can run the tool without
+specifying these parameters for the common case, or override them when analyzing
+different repositories. This eliminates repetitive parameter entry while
+maintaining flexibility.
 
-**Example scenario**: Configure staging database as the default (safe for
-development), while production queries require an explicit approval gate.
-Connection details are centralized in vMCP configuration instead of scattered
-across individual tool configurations.
+**Real example**: In the demo configuration, all three composite tools
+(`aggregate_docs`, `analyze_repository`, `investigate_image`) have
+pre-configured defaults - documentation URLs, repository names, and container
+image references. This makes the tools immediately usable while remaining
+customizable for different scenarios.
 
 ### Authentication boundary separation
 
-Different auth is needed for clients versus backends, and managing credentials
-across multiple systems is complex. vMCP implements a two-boundary auth model
-that separates these concerns.
+Different authentication is needed for clients versus backend MCP servers, and
+managing credentials across multiple systems is complex. vMCP implements a
+two-boundary auth model that separates these concerns.
 
 **How it works**: Clients authenticate to vMCP using OAuth 2.1 authorization as
 defined in the MCP specification. vMCP then handles authentication to each

docs/toolhive/guides-vmcp/composite-tools.mdx

@@ -4,14 +4,14 @@ description: Create multi-step workflows that span multiple backend MCP servers.
 ---
 
 Composite tools let you define multi-step workflows that execute across multiple
-backends with parallel execution, conditional logic, approval gates, and error
-handling.
+backend MCP servers with parallel execution, conditional logic, approval gates,
+and error handling.
 
 ## Overview
 
 A composite tool combines multiple backend tool calls into a single workflow.
 When a client calls a composite tool, vMCP orchestrates the execution across
-backends, handling dependencies and collecting results.
+backend MCP servers, handling dependencies and collecting results.
 
 ## Key capabilities
 
@@ -98,126 +98,112 @@ and returns the final summary.
 
 ## Use cases
 
-### Incident investigation
+### Multi-source documentation aggregation
 
-Gather data from multiple monitoring systems in parallel:
+Fetch and aggregate documentation from multiple sources in parallel:
 
 ```yaml title="VirtualMCPServer resource"
 spec:
   compositeTools:
-    - name: investigate_incident
-      description: Gather incident data from multiple sources in parallel
+    - name: aggregate_docs
+      description: Fetch and aggregate documentation from multiple sources
       parameters:
         type: object
         properties:
-          incident_id:
-            type: string
-        required:
-          - incident_id
+          sources:
+            type: array
+            default:
+              - https://raw.githubusercontent.com/modelcontextprotocol/specification/main/README.md
+              - https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
+              - https://raw.githubusercontent.com/modelcontextprotocol/servers/main/README.md
+      timeout: '2m'
       steps:
-        # These steps run in parallel (no dependencies)
-        - id: get_logs
-          tool: logging.search_logs
+        # These three steps run in parallel (no dependencies)
+        - id: fetch_source_1
+          tool: fetch_fetch
           arguments:
-            query: 'incident_id={{.params.incident_id}}'
-            timerange: '1h'
-        - id: get_metrics
-          tool: monitoring.get_metrics
+            url: '{{index .params.sources 0}}'
+            max_length: 5000
+        - id: fetch_source_2
+          tool: fetch_fetch
           arguments:
-            filter: 'error_rate'
-            timerange: '1h'
-        - id: get_alerts
-          tool: pagerduty.list_alerts
+            url: '{{index .params.sources 1}}'
+            max_length: 5000
+        - id: fetch_source_3
+          tool: fetch_fetch
           arguments:
-            incident: '{{.params.incident_id}}'
-        # This step waits for all parallel steps to complete
-        - id: create_summary
-          tool: docs.create_document
-          arguments:
-            title: 'Incident {{.params.incident_id}} Summary'
-            content: 'Logs: {{.steps.get_logs.output.results}}'
-          dependsOn: [get_logs, get_metrics, get_alerts]
+            url: '{{index .params.sources 2}}'
+            max_length: 5000
 ```
 
-### Deployment with approval
+### GitHub repository analysis
 
-Human-in-the-loop workflow for production deployments:
+Analyze a GitHub repository's health and activity:
 
 ```yaml title="VirtualMCPServer resource"
 spec:
   compositeTools:
-    - name: deploy_with_approval
-      description: Deploy to production with human approval gate
+    - name: analyze_repository
+      description: Analyze a GitHub repository's health and activity
       parameters:
         type: object
         properties:
-          pr_number:
+          owner:
             type: string
-          environment:
+            default: modelcontextprotocol
+          repo:
             type: string
-            default: production
-        required:
-          - pr_number
+            default: specification
+      timeout: '2m'
       steps:
-        - id: get_pr_details
-          tool: github.get_pull_request
+        # These steps run in parallel
+        - id: list_issues
+          tool: github_list_issues
           arguments:
-            pr: '{{.params.pr_number}}'
-        - id: approval
-          type: elicitation
-          message:
-            'Deploy PR #{{.params.pr_number}} to {{.params.environment}}?'
-          schema:
-            type: object
-            properties:
-              approved:
-                type: boolean
-          timeout: '10m'
-          dependsOn: [get_pr_details]
-        - id: deploy
-          tool: deploy.trigger_deployment
+            owner: '{{.params.owner}}'
+            repo: '{{.params.repo}}'
+            perPage: 5
+        - id: list_commits
+          tool: github_list_commits
           arguments:
-            ref: '{{.steps.get_pr_details.output.head_sha}}'
-            environment: '{{.params.environment}}'
-          condition: '{{.steps.approval.content.approved}}'
-          dependsOn: [approval]
+            owner: '{{.params.owner}}'
+            repo: '{{.params.repo}}'
+            perPage: 3
 ```
 
-### Cross-system data aggregation
+### Container image investigation
 
-Collect and correlate data from multiple backends:
+Investigate a container image from an OCI registry:
 
 ```yaml title="VirtualMCPServer resource"
 spec:
   compositeTools:
-    - name: security_scan_report
-      description: Run security scans and create consolidated report
+    - name: investigate_image
+      description: Investigate a container image from an OCI registry
       parameters:
         type: object
         properties:
-          repo:
+          image:
             type: string
-        required:
-          - repo
+            default: docker.io/library/alpine:latest
+      timeout: '2m'
       steps:
-        - id: vulnerability_scan
-          tool: osv.scan_dependencies
+        # Step 1: Get basic image information
+        - id: get_image_info
+          tool: oci-registry_get_image_info
           arguments:
-            repository: '{{.params.repo}}'
-        - id: secret_scan
-          tool: gitleaks.scan_repo
+            image_ref: '{{.params.image}}'
+        # Steps 2 and 3 run in parallel (both depend on step 1)
+        - id: get_manifest
+          tool: oci-registry_get_image_manifest
           arguments:
-            repository: '{{.params.repo}}'
-        - id: create_issue
-          tool: github.create_issue
+            image_ref: '{{.params.image}}'
+          dependsOn: [get_image_info]
+        - id: get_config
+          tool: oci-registry_get_image_config
           arguments:
-            repo: '{{.params.repo}}'
-            title: 'Security Scan Results'
-            body:
-              'Found {{.steps.vulnerability_scan.output.count}} vulnerabilities'
-          dependsOn: [vulnerability_scan, secret_scan]
-          onError:
-            action: continue
+            image_ref: '{{.params.image}}'
+          dependsOn: [get_image_info]
 ```
 
 ## Workflow definition

docs/toolhive/guides-vmcp/intro.mdx

@@ -14,11 +14,11 @@ through a single endpoint.
 ## Core capabilities
 
 - **Multi-server aggregation**: Connect to one endpoint instead of many
-- **Tool conflict resolution**: Automatic namespacing when backends have
-  overlapping tool names
+- **Tool conflict resolution**: Automatic namespacing when backend MCP servers
+  have overlapping tool names
 - **Centralized authentication**: Single sign-on with per-backend token exchange
-- **Composite workflows**: Multi-step operations across backends with parallel
-  execution, approval gates, and error handling
+- **Composite workflows**: Multi-step operations across backend MCP servers with
+  parallel execution, approval gates, and error handling
 
 ## When to use vMCP