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)
• Iteration: Loop over collections with forEach steps
• 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/v1beta1
kind: VirtualMCPServer
metadata:
  name: my-vmcp
spec:
  incomingAuth:
    type: anonymous
  groupRef:
    name: my-tools
  config:
    # ... 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. This example assumes you have an MCPServer resource named arxiv in a group that your vMCP server references, and that you're using the default conflict resolution strategy and prefix format (<SERVER_NAME>_<TOOL_NAME>):

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.output.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, an elicitation, or a forEach loop:

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

The tool field specifies which MCP server tool to call. This depends on your conflict resolution strategy and prefix format. For example, if you have a tool named search in an MCP server named arxiv, and you're using the default prefix format, you would reference it as arxiv_search.

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'

forEach steps

Iterate over a collection from a previous step's output and execute a tool call for each item:

VirtualMCPServer resource

spec:
  config:
    compositeTools:
      - name: scan_repositories
        description: Check each repository for security advisories
        parameters:
          type: object
          properties:
            org:
              type: string
          required:
            - org
        steps:
          - id: list_repos
            tool: github_list_repos
            arguments:
              org: '{{.params.org}}'
          - id: check_advisories
            type: forEach
            collection: '{{json .steps.list_repos.output.repositories}}'
            itemVar: repo
            maxParallel: 5
            step:
              type: tool
              tool: github_list_security_advisories
              arguments:
                repo: '{{.forEach.repo.name}}'
            onError:
              action: continue
            dependsOn: [list_repos]

forEach fields:

Field	Description	Default
collection	Template expression that resolves to a JSON array	-
itemVar	Variable name for the current item	item
maxParallel	Maximum concurrent iterations (max 50)	10
maxIterations	Maximum total iterations (max 1000)	100
step	Inner step definition (tool call to execute per item)	-
onError	Error handling: abort (stop) or continue (skip)	abort

note

forEach does not support onError.action: retry. Use retry on regular tool steps. The maxParallel cap of 50 is enforced at runtime regardless of the configured value.

Access the current item inside the inner step using {{.forEach.<itemVar>.<field>}}. In the example above, {{.forEach.repo.name}} accesses the name field of the current repository. You can also use {{.forEach.index}} to access the zero-based iteration index.

maxParallel controls how many iterations run concurrently on the pod that received the composite tool request. Iterations are not distributed across vMCP replicas - all parallel backend calls originate from a single pod regardless of spec.replicas. When sizing your deployment, account for the per-pod fan-out: a maxParallel: 50 forEach step can open up to 50 simultaneous connections to backend MCP servers from one pod. Ensure both the vMCP pod resources and the backend MCP servers can handle that per-pod concurrency.

Plan your workflow timeouts

With maxIterations: 1000 and maxParallel: 10 (the defaults), a forEach loop runs up to 100 serial batches. If each backend call takes a few seconds, the total duration can easily exceed a workflow-level timeout. Set the workflow timeout to at least ceil(maxIterations / maxParallel) × expected step duration to avoid silent truncation.

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

Structured output

By default, a composite tool returns the raw output of its last step. Add an output block to define a structured, typed response instead. This is useful when you want to aggregate data from multiple steps, enforce types, or give models a consistent response shape.

VirtualMCPServer resource

spec:
  config:
    compositeTools:
      - name: create_github_issue
        description: Create an issue and return structured result
        parameters:
          type: object
          properties:
            title:
              type: string
            body:
              type: string
          required: [title, body]
        steps:
          - id: create
            tool: github_create_issue
            arguments:
              title: '{{.params.title}}'
              body: '{{.params.body}}'
        output:
          properties:
            issue_number:
              type: integer
              description: Number of the created issue
              value: '{{.steps.create.output.number}}'
            issue_url:
              type: string
              description: URL of the created issue
              value: '{{.steps.create.output.url}}'
          required: [issue_number, issue_url]

Property fields

Each entry in output.properties requires type and either value or properties:

Field	Required	Description
type	Yes	JSON Schema type: string, integer, number, boolean, object, array
description	Recommended	Human-readable description exposed to clients and models
value	Yes*	Template string that resolves to the property value
properties	Yes*	Nested property definitions (object type only)
default	No	Fallback value when template expansion returns no value or coercion fails

* value and properties are mutually exclusive. Non-object types must use value. Object types may use either.

note

description is optional in the CRD schema but is required by the vMCP runtime validator. Omitting it causes the composite tool to fail at load time.

The top-level required list names properties that must be present and non-null at runtime. If a required property is missing or null, the workflow fails.

Type coercion

Template expansion always produces a string. The runtime converts that string to the declared type:

Type	Coercion
string	Used as-is
integer	Parsed as a base-10 integer; fails if not parseable
number	Parsed as a float; fails if not parseable
boolean	Accepts true/false, 1/0; fails otherwise
object	Parsed as a JSON object string; fails if not valid JSON
array	Parsed as a JSON array string; fails if not valid JSON

When coercion fails and no default is defined, the workflow fails. When default is defined, it is used as the fallback and a warning is logged.

For object and array types, the value must expand to a JSON string. If a step's structured output already contains a map or slice (not a JSON string), use the json template function to serialize it first:

# Step returns a structured list; serialize to JSON for the output block
referrers:
  type: array
  description: Attestation referrers attached to this image
  value: '{{json .steps.list_referrers.output.referrers}}'

The default field

Use default to provide a fallback for properties that may not resolve. For example, when referencing output from a conditionally skipped step:

output:
  properties:
    processed_count:
      type: integer
      description: Number of items processed
      value: '{{.steps.optional_step.output.count}}'
      default: 0
    status:
      type: string
      description: Processing status
      value: '{{.steps.optional_step.output.status}}'
      default: not_run

note

When a step is conditionally skipped, its output fields expand to <no value> in templates. Without a default, the workflow fails. defaultResults on the step itself serves a different purpose: it provides fallback values for downstream steps that reference the skipped step's output in their arguments. See Default step outputs.

Nested objects

For object properties, use value when the step returns data to deserialize, or properties to template each field individually:

output:
  properties:
    # Option 1a: step returns a JSON string already — reference it directly
    metadata:
      type: object
      description: Metadata returned by the backend as a JSON string
      value: '{{.steps.fetch.output.metadata_json}}'

    # Option 1b: step returns structured data — use json to serialize it first
    referrers:
      type: array
      description: OCI referrers attached to this image
      value: '{{json .steps.list_referrers.output.referrers}}'

    # Option 2: nested properties, each individually templated
    summary:
      type: object
      description: Aggregated scan summary
      properties:
        issue_count:
          type: integer
          description: Total issues found
          value: '{{.steps.scan.output.count}}'
        severity:
          type: string
          description: Highest severity level
          value: '{{.steps.scan.output.max_severity}}'

Aggregating from multiple steps

The output block is the natural place to collect results from parallel or sequential steps into a single response. This example fans out three lookups in parallel, then aggregates them into one structured result:

VirtualMCPCompositeToolDefinition resource

apiVersion: toolhive.stacklok.dev/v1beta1
kind: VirtualMCPCompositeToolDefinition
metadata:
  name: image-supply-chain-audit
spec:
  name: audit_image_supply_chain
  description: Audit an OCI image (info, referrers, and recent tags in parallel)
  parameters:
    type: object
    properties:
      image_ref:
        type: string
        description: Full image reference including tag
      repository:
        type: string
        description: Repository path without tag, for listing tags
    required: [image_ref, repository]
  steps:
    # All three steps run in parallel — no dependsOn between them
    - id: image_info
      tool: oci-registry_get_image_info
      arguments:
        image_ref: '{{.params.image_ref}}'
    - id: referrers
      tool: oci-registry_list_referrers
      arguments:
        image_ref: '{{.params.image_ref}}'
    - id: tags
      tool: oci-registry_list_tags
      arguments:
        repository: '{{.params.repository}}'
        limit: 10
  output:
    properties:
      image_ref:
        type: string
        description: The image reference that was audited
        value: '{{.params.image_ref}}'
      digest:
        type: string
        description: Content-addressable digest of the image
        value: '{{.steps.image_info.output.digest}}'
      architecture:
        type: string
        description: CPU architecture of the image
        value: '{{.steps.image_info.output.architecture}}'
      layers:
        type: integer
        description: Number of image layers
        value: '{{.steps.image_info.output.layers}}'
      # referrers is a structured list — use json to serialize before output parses it
      referrers:
        type: array
        description:
          Attestation referrers attached to this image (SBOMs, signatures)
        value: '{{json .steps.referrers.output.referrers}}'
      recent_tags:
        type: array
        description: Most recent tags in the repository
        value: '{{json .steps.tags.output.tags}}'
    required: [digest]

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.output.content}}	Elicitation response content
{{.steps.id.output.action}}	Elicitation action (accept/decline/cancel)
{{.forEach.<itemVar>}}	Current forEach item
{{.forEach.<itemVar>.<field>}}	Field on current forEach item
{{.forEach.index}}	Zero-based iteration index

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/v1beta1
kind: VirtualMCPServer
metadata:
  name: research-vmcp
  namespace: toolhive-system
spec:
  incomingAuth:
    type: anonymous
  groupRef:
    name: research-tools
  config:
    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:
  groupRef:
    name: my-tools
  config:
    compositeToolRefs:
      - name: my-reusable-workflow
      - name: another-workflow

Next steps

• Configure failure handling for circuit breakers and partial failure modes in multi-backend setups

Related information

• Configure vMCP servers