VirtualMCPServer CRD: Support non-string argument types in composite tool steps

[jhrozek]

Description

The VirtualMCPServer CRD currently defines composite tool step arguments as map[string]string, which prevents passing non-string values (integers, booleans, arrays, objects) to backend MCP tools.

Current Behavior

In cmd/thv-operator/api/v1alpha1/virtualmcpserver_types.go:281:

Arguments map[string]string `json:"arguments,omitempty"`

When a composite tool step needs to pass an integer argument (e.g., max_results: 5), it must be specified as a string (max_results: "5"), which causes type validation errors in backend tools that expect integer types.

Example Manifests

ArXiv search with max_results (integer parameter)

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: VirtualMCPServer
metadata:
  name: paper-scout
spec:
  compositeTools:
    - name: find_papers
      steps:
        - id: search
          type: tool
          tool: arxiv_search_papers
          arguments:
            query: "{{.params.topic}}"
            max_results: "5"  # ❌ Must be string, but ArXiv expects integer

Error: invalid params: validating "arguments": expected integer, got string

Perplexity chat with messages (array parameter)

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: VirtualMCPServer
metadata:
  name: research-assistant
spec:
  compositeTools:
    - name: ask_perplexity
      steps:
        - id: chat
          type: tool
          tool: perplexity_chat_completions
          arguments:
            model: "sonar"
            # ❌ Cannot pass array - CRD only supports string values
            # messages:
            #   - role: "user"
            #     content: "{{.params.question}}"

Error: Cannot represent array/object types in map[string]string

Expected Behavior

The CRD should support arbitrary JSON types for arguments, matching the internal vmcp implementation which already uses map[string]any in pkg/vmcp/composite/config.go:43:

Arguments map[string]any `yaml:"arguments" json:"arguments"`

Impact

This limitation prevents using many MCP tools in composite workflows when they require:

• Integer parameters (e.g., max_results, limit, count)
• Boolean parameters
• Array parameters (e.g., messages for chat APIs)
• Object parameters

Suggested Fix

Change the CRD Arguments field to use runtime.RawExtension or apiextensionsv1.JSON to support arbitrary JSON values:

// Option 1: Using apiextensions JSON type
Arguments map[string]apiextensionsv1.JSON `json:"arguments,omitempty"`

// Option 2: Using RawExtension
Arguments runtime.RawExtension `json:"arguments,omitempty"`

This would align the CRD with the internal vmcp config structure and enable full compatibility with backend MCP tools.

Related

Found during vMCP demo development with ArXiv and Perplexity MCP servers.

[tgrunnagle]

@jhrozek @amirejaz before implementing this, we may want to decide whether we should support 'default' values for step arguments (see discussions here https://github.com/stacklok/toolhive/pull/2922/files)

[jerm-dro]

before implementing this, we may want to decide whether we should support 'default' values for step arguments (see discussions here https://github.com/stacklok/toolhive/pull/2922/files)

@tgrunnagle I can see why we'd want to support default values. Do we need to block development on this issue on the decision of if/how to support defaults though?

I can see two potential solutions:

• A helm-like default function that can be used in templates and must be used to consume values that are an Optional type.
• A parallel map of DefaultArguments which define defaults that are used if the Arguments value is nil/no value.

In either case, I don't think allowing more complex types in the Arguments increases the cost of development for the default solution. Did you have another solution in mind? or other reservations on proceeding with this work?

[tgrunnagle]

@jerm-dro I think allowing a default inline might be cleanest. A step could look like

steps: [
    {
        id: "step1",
        ...
        arguments: { // map[string]any
            arg1: { // map type
                value: "{{params.param1}}" // template expansion
                default: "explicit_default" // required if params.param1 is not guaranteed to exist (e.g. from a step with error.action = 'continue')
            },
            arg2: "{{params.param2}}" // also support primitive type
        }
    },
    ...
]

@jhrozek @JAORMX thoughts?

[jerm-dro]

@tgrunnagle I like the simplicity, but I'm concerned it may be limiting. For example, a value: {{params.someRequiredParam + params.someOptionalParam}} cannot specify a default value for just someOptionalParam. That's just a trade off though. I'd be fine with that solution.

Regardless, none of the potential solutions appear to get any harder to implement if we already have support for non-string types in place. For example, we'd simply change the type of Arguments from runtime.RawExtension to

map[string]struct{
   value runtime.RawExtension
   default runtime.RawExtension
}

I'm going to proceed adding support for non-string types unless you feel strongly that defaults need to be in place first.