VirtualMCPServer: Add tool execution trace output for composite tools

[aponcedeleonch]

Description

When using VirtualMCPServer with composite tools that execute multiple backend tool calls in sequence, developers currently have limited visibility into which specific tools were invoked during execution. This makes debugging and auditing composite tool workflows challenging.

Current Behavior

When a composite tool executes:

• Multiple backend MCP tools are called sequentially based on the workflow steps
• Step outputs are used internally for template variable expansion (e.g., {{.steps.step_id.output}})
• The final response is returned to the client
• No information about the internal tool execution flow is exposed to the caller

Desired Behavior

VirtualMCPServer should provide an optional output that includes execution trace information showing:

• Which backend tools were called during the composite tool execution
• The order of execution
• Step IDs and their corresponding tool invocations
• Any relevant execution metadata (timing, status, etc.)

This trace information would be invaluable for:

• Debugging: Understanding why a composite tool produced unexpected results
• Development: Validating that workflow steps execute as intended
• Auditing: Tracking which backend services were accessed during a request

Suggested Implementation

Add a debug flag or configuration option (e.g., include_execution_trace: true) that when enabled, includes execution trace metadata in the tool response. This could be:

• An additional field in the response payload
• Part of the tool metadata
• Configurable at the VirtualMCPServer CRD level or per-request

Example response structure:

{
  "result": "...",
  "execution_trace": [
    {"step_id": "fetch_data", "tool": "backend1.fetch_api", "status": "success", "parameters": {...}},
    {"step_id": "process", "tool": "backend2.transform", "status": "success", "parameters": {...}}
  ]
}

Related Issues

This issue complements but differs from existing observability work:

• Add OpenTelemetry metrics to vMCP server #2849 (OpenTelemetry metrics): Focuses on infrastructure-level monitoring and metrics collection for operational observability
• Add audit logging middleware to vMCP server #2850 (Audit logging): Focuses on compliance and security audit trails stored server-side

This proposal differs by providing client-visible execution traces specifically for development and debugging purposes. While #2849 and #2850 focus on backend observability and compliance, this feature would give developers immediate feedback about composite tool execution in the tool response itself.

References

• THV-2106 Virtual MCP Server Proposal

[jhrozek]

@jerm-dro do you have thoughts on the request?

[jerm-dro]

@jerm-dro do you have thoughts on the request?

@jhrozek I can see why we might want this, but I do wonder if it's not solved by tracing. Without more details on the exact use case, it's unclear whether we should do this. For example, if this is for local debugging/iteration, it may make more sense to provide easy-to-use instructions for wiring up zipkin locally.

[aponcedeleonch]

@jerm-dro yeah, good point, I'm not 100% sure myself either. Easy-to-use Zipkin instructions could definitely work well for the local debugging/iteration case.

I was also thinking about scenarios like CI testing, where you might want to verify that a vMCP is calling the right underlying MCPs as part of your test suite. For that specific use case, spinning up Zipkin feels like overkill, but maybe there's a simpler / other solution I'm not seeing. Also I've been lately testing MCP servers and the tools they call, that's how I'm biased. Maybe testing MCPs in CI is a corner case that doesn't need special treating

[jerm-dro]

@aponcedeleonch I'm curious what sorts of bugs/problems you've encountered. Instead of improving debug-ability, could we make composite tool development less bug-prone or cause clearer errors to happen sooner (i.e. catching errors at validation time rather than runtime)?

[aponcedeleonch]

@jerm-dro sorry, I was meaning LLM + query test cases validation rather than something that actually caused an application error. For example, assume the following scenario

• A vMCP which internally has a composite tool that calls:
  1. arxiv MCP server - to fetch a paper
  2. Google Drive MCP server - to store a summary in my GDrive in a specific folder
• Query: "Please help me finding paper X in arvix, and upload a summary to google drive".

Then I would like to validate that vMCP internally called both MCP servers with the expected parameters. The tricky part is that neither MCP server might fail (everything returns successfully) but maybe the parameters passed to them aren't quite right (wrong folder ID, incorrect search terms, etc.).

Having visibility into which tools were called and with what parameters would be helpful for this kind of validation

Edit: just to be clear, I haven't tested with vMCP. I meant I've done some testing of MCPs as part of other project and that's why I see a use case for testing. Maybe this is already taken care of in vMCP's implementation or could already be taken care of as part of validation or some other stage