Composite tools and workflows

Composite tools let you define multi-step workflows that execute across multiple 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 backend MCP servers, handling dependencies and collecting results.

Key capabilities

• Parallel execution: Independent steps run concurrently; dependent steps wait for their prerequisites
• Template expansion: Dynamic arguments using step outputs
• Elicitation: Request user input mid-workflow (approval gates, choices)
• Error handling: Configurable abort, continue, or retry behavior
• Timeouts: Workflow and per-step timeout configuration

info

Elicitation (user prompts during workflow execution) is defined in the CRD but has not been extensively tested. Test thoroughly in non-production environments first.

Configuration location

Composite tools are defined in the VirtualMCPServer resource under spec.config.compositeTools:

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: VirtualMCPServer
metadata:
  name: my-vmcp
spec:
  incomingAuth:
    type: anonymous
  config:
    groupRef: my-tools
    # ... other configuration ...
    compositeTools:
      - name: my_workflow
        description: A multi-step workflow
        parameters:
          # Input parameters (JSON Schema)
        steps:
          # Workflow steps

For complex, reusable workflows, you can also reference external VirtualMCPCompositeToolDefinition resources using spec.config.compositeToolRefs.

Simple example

Here's a composite tool that searches arXiv for papers on a topic and reads the top result:

VirtualMCPServer resource

spec:
  config:
    compositeTools:
      - name: research_topic
        description: Search arXiv for papers and read the top result
        parameters:
          type: object
          properties:
            query:
              type: string
              description: Research topic to search for
          required:
            - query
        steps:
          # Step 1: Search arXiv for papers matching the query
          - id: search
            tool: arxiv.search_papers
            arguments:
              query: '{{.params.query}}'
              max_results: 1
          # Step 2: Download the paper (required before reading)
          # Note: fromJson is needed when the MCP server returns JSON as text
          # rather than structured content. This is common for servers that
          # don't fully support MCP's structuredContent field.
          - id: download
            tool: arxiv.download_paper
            arguments:
              paper_id:
                '{{(index (fromJson .steps.search.output.text).papers 0).id}}'
            dependsOn: [search]
          # Step 3: Read the downloaded paper content
          - id: read
            tool: arxiv.read_paper
            arguments:
              paper_id:
                '{{(index (fromJson .steps.search.output.text).papers 0).id}}'
            dependsOn: [download]

What's happening:

1. Parameters: Define the workflow inputs (query for the research topic)
2. Step 1 (search): Calls arxiv.search_papers with the query from parameters using template syntax {{.params.query}}
3. Step 2 (download): Waits for search (dependsOn: [search]), then downloads the paper. The fromJson function parses the JSON text returned by the server, and index accesses the first paper's ID.
4. Step 3 (read): Waits for download, then reads the paper content.

When a client calls this composite tool, vMCP executes all three steps in sequence and returns the paper content.

Structured content vs JSON text

MCP servers can return data in two ways:

• Structured content: Data is in structuredContent and can be accessed directly: {{.steps.stepid.output.field}}
• JSON text: Data is returned as a JSON string in the text field and requires parsing: {{(fromJson .steps.stepid.output.text).field}}

The arxiv-mcp-server in this example uses JSON text, so we use fromJson. Check your backend's response format to determine which approach to use.

Use cases

Incident investigation

Gather data from multiple monitoring systems in parallel:

VirtualMCPServer resource

spec:
  config:
    compositeTools:
      - name: investigate_incident
        description: Gather incident data from multiple sources in parallel
        parameters:
          type: object
          properties:
            incident_id:
              type: string
          required:
            - incident_id
        steps:
          # These steps run in parallel (no dependencies)
          - id: get_logs
            tool: logging.search_logs
            arguments:
              query: 'incident_id={{.params.incident_id}}'
              timerange: '1h'
          - id: get_metrics
            tool: monitoring.get_metrics
            arguments:
              filter: 'error_rate'
              timerange: '1h'
          - id: get_alerts
            tool: pagerduty.list_alerts
            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]

Deployment with approval

Human-in-the-loop workflow for production deployments:

VirtualMCPServer resource

spec:
  config:
    compositeTools:
      - name: deploy_with_approval
        description: Deploy to production with human approval gate
        parameters:
          type: object
          properties:
            pr_number:
              type: string
            environment:
              type: string
              default: production
          required:
            - pr_number
        steps:
          - id: get_pr_details
            tool: github.get_pull_request
            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
            arguments:
              ref: '{{.steps.get_pr_details.output.head_sha}}'
              environment: '{{.params.environment}}'
            condition: '{{.steps.approval.content.approved}}'
            dependsOn: [approval]

Cross-system data aggregation

Collect and correlate data from multiple backend MCP servers:

VirtualMCPServer resource

spec:
  config:
    compositeTools:
      - name: security_scan_report
        description: Run security scans and create consolidated report
        parameters:
          type: object
          properties:
            package_name:
              type: string
            ecosystem:
              type: string
            repo:
              type: string
          required:
            - package_name
            - ecosystem
            - repo
        steps:
          - id: vulnerability_scan
            tool: osv.query_vulnerability
            arguments:
              package_name: '{{.params.package_name}}'
              ecosystem: '{{.params.ecosystem}}'
          - id: secret_scan
            tool: gitleaks.scan_repo
            arguments:
              repository: '{{.params.repo}}'
          - id: create_issue
            tool: github.create_issue
            arguments:
              repo: '{{.params.repo}}'
              title: 'Security Scan Results'
              body: 'Vulnerability scan completed for {{.params.package_name}}'
            dependsOn: [vulnerability_scan, secret_scan]
            onError:
              action: continue

Workflow definition

Parameters

Define input parameters using JSON Schema format:

VirtualMCPServer resource

spec:
  config:
    compositeTools:
      - name: <TOOL_NAME>
        parameters:
          type: object
          properties:
            required_param:
              type: string
            optional_param:
              type: integer
              default: 10
          required:
            - required_param

Steps

Each step can be a tool call or an elicitation:

VirtualMCPServer resource

spec:
  config:
    compositeTools:
      - name: <TOOL_NAME>
        steps:
          - id: step_name # Unique identifier
            tool: backend.tool # Tool to call
            arguments: # Arguments with template expansion
              arg1: '{{.params.input}}'
            dependsOn: [other_step] # Dependencies (this step waits for other_step)
            condition: '{{.steps.check.output.approved}}' # Optional condition
            timeout: '30s' # Step timeout
            onError:
              action: abort # abort | continue | retry

tip

When using the condition field, downstream steps that reference the conditional step's output may require default step outputs to handle cases where the condition evaluates to false.

Elicitation (user prompts)

Request input from users during workflow execution:

VirtualMCPServer resource

spec:
  config:
    compositeTools:
      - name: <TOOL_NAME>
        steps:
          - id: approval
            type: elicitation
            message: 'Proceed with deployment?'
            schema:
              type: object
              properties:
                confirm: { type: boolean }
            timeout: '5m'

Error handling

Configure behavior when steps fail:

Action	Description
abort	Stop workflow immediately
continue	Log error, proceed to next step
retry	Retry with exponential backoff

VirtualMCPServer resource

spec:
  config:
    compositeTools:
      - name: <TOOL_NAME>
        steps:
          - id: <STEP_ID>
            # ... other step config (tool, arguments, etc.)
            onError:
              action: retry
              retryCount: 3

tip

When using onError.action: continue, downstream steps that reference this step's output may require default step outputs to handle cases where the step fails.

Default step outputs

When steps can be skipped (due to condition being false or onError.action: continue), downstream steps that reference their outputs need fallback values. Use defaultResults to provide these values.

When defaultResults are required

You must provide defaultResults when both of these conditions are true:

1. A step can be skipped (has a condition field or onError.action: continue)
2. A downstream step references the skipped step's output in its arguments

Configuration

Define default values that match the expected output structure:

VirtualMCPServer resource

spec:
  config:
    compositeTools:
      - name: optional_security_check
        description: Run security scan with optional vulnerability check
        parameters:
          type: object
          properties:
            package_name:
              type: string
            ecosystem:
              type: string
            run_vuln_scan:
              type: boolean
              default: false
          required:
            - package_name
            - ecosystem
        steps:
          # Step 1: Optional vulnerability scan
          - id: vuln_scan
            tool: osv.query_vulnerability
            arguments:
              package_name: '{{.params.package_name}}'
              ecosystem: '{{.params.ecosystem}}'
            condition: '{{.params.run_vuln_scan}}'
            defaultResults:
              vulns: []
          # Step 2: Create report using scan results
          - id: create_report
            tool: docs.create_document
            arguments:
              title: 'Security Report'
              # This references vuln_scan output, so defaultResults are needed
              body:
                'Found {{len .steps.vuln_scan.output.vulns}} vulnerabilities'
            dependsOn: [vuln_scan]

Continue on error example

When using onError.action: continue, provide defaults for potential failures:

VirtualMCPServer resource

spec:
  config:
    compositeTools:
      - name: multi_source_data
        description: Gather data from multiple sources, continue on failures
        steps:
          # Step 1: Fetch from primary source (may fail)
          - id: fetch_primary
            tool: api.get_data
            arguments:
              source: 'primary'
            onError:
              action: continue
            defaultResults:
              status: 'unavailable'
              data: null
          # Step 2: Aggregate results
          - id: aggregate
            tool: processing.combine_data
            arguments:
              # Uses fetch_primary output even if it failed
              primary: '{{.steps.fetch_primary.output.data}}'
            dependsOn: [fetch_primary]

Validation

vMCP validates defaultResults at configuration time:

• Missing defaults: If a step can be skipped and downstream steps reference its output, but defaultResults is not provided, vMCP returns a validation error
• Structure: The defaultResults value can be any valid JSON type (object, array, string, number, boolean, null)
• No type checking: vMCP does not verify that defaultResults match the actual output structure—you must ensure they match the format your downstream steps expect

Example validation error

# This will fail validation
steps:
  - id: conditional_step
    tool: backend.fetch
    condition: '{{.params.enabled}}'
    # Missing defaultResults!
  - id: use_result
    tool: backend.process
    arguments:
      # References conditional_step output
      data: '{{.steps.conditional_step.output.value}}'
    dependsOn: [conditional_step]

Error message:

step 'conditional_step' can be skipped but is referenced by downstream steps
without defaultResults defined

Template syntax

Access workflow context in arguments:

Template	Description
{{.params.name}}	Input parameter
{{.steps.id.output}}	Step output (map)
{{.steps.id.output.text}}	Text content from step output
{{.steps.id.content}}	Elicitation response content
{{.steps.id.action}}	Elicitation action (accept/decline/cancel)

Template functions

The following functions are available for use in templates:

Function	Description	Example
fromJson	Parse a JSON string into a value	{{(fromJson .steps.s1.output.text).field}}
json	Encode a value as a JSON string	{{json .steps.s1.output}}
quote	Quote a string value	{{quote .params.name}}
index	Access array elements by index	{{index .steps.s1.output.items 0}}

All Go template built-in functions are also supported (e.g., len, eq, and, or, printf).

Accessing step outputs

When an MCP server returns structured content, you can access output fields directly:

# Direct access when server supports structuredContent
result: '{{.steps.fetch.output.data}}'
items: '{{index .steps.search.output.results 0}}'

This is the simplest approach and works when the backend MCP server populates the structuredContent field in its response.

Working with JSON text responses

Some MCP servers return structured data as JSON text rather than using MCP's structuredContent field. When this happens, use fromJson to parse it:

# Parse JSON text and access a nested field
paper_id: '{{(index (fromJson .steps.search.output.text).papers 0).id}}'

This pattern:

1. Gets the text output: .steps.search.output.text
2. Parses it as JSON: fromJson ...
3. Accesses the papers array and gets the first element: index ... 0
4. Gets the id field: .id

How to tell which approach to use: Call the backend tool directly and inspect the response. If structuredContent contains your data fields, use direct access. If structuredContent only has a text field containing JSON, use fromJson.

Complete example

A VirtualMCPServer with an inline composite tool using the arxiv-mcp-server:

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: VirtualMCPServer
metadata:
  name: research-vmcp
  namespace: toolhive-system
spec:
  incomingAuth:
    type: anonymous
  config:
    groupRef: research-tools
    aggregation:
      conflictResolution: prefix
      conflictResolutionConfig:
        prefixFormat: '{workload}_'
    compositeTools:
      - name: research_topic
        description: Search arXiv for papers and read the top result
        parameters:
          type: object
          properties:
            query:
              type: string
              description: Research topic to search for
          required:
            - query
        steps:
          - id: search
            tool: arxiv.search_papers
            arguments:
              query: '{{.params.query}}'
              max_results: 1
          - id: download
            tool: arxiv.download_paper
            arguments:
              paper_id:
                '{{(index (fromJson .steps.search.output.text).papers 0).id}}'
            dependsOn: [search]
          - id: read
            tool: arxiv.read_paper
            arguments:
              paper_id:
                '{{(index (fromJson .steps.search.output.text).papers 0).id}}'
            dependsOn: [download]
        timeout: '5m'

Note: The example above assumes you have:

• An MCPGroup named research-tools.
• An arxiv-mcp-server deployed as an MCPServer or MCPRemoteProxy resource that references the research-tools group.

For a complete example of configuring MCP groups and backend servers, see the quickstart and tool aggregation guides. For complex, reusable workflows, create VirtualMCPCompositeToolDefinition resources and reference them with spec.config.compositeToolRefs:

VirtualMCPServer resource

spec:
  config:
    groupRef: my-tools
    compositeToolRefs:
      - name: my-reusable-workflow
      - name: another-workflow

Related information

• Configure vMCP servers