vMCP Code Mode
@jerm-dro is already working on this.
Since Apr 10, 2026.
- Dominant language
- Go
- Stars
- 2.2k
- Forks
- 300
- Avg merge
- 1d 15h
- Merged PRs (30d)
- 184
Description
Overview
Add opt-in Starlark script execution ("code mode") to vMCP, allowing agents to batch multi-tool workflows into a single server-side call — reducing round-trips, context bloat, and inference cycles. Based on the prototype in PR #4714.
Background
Agents today make sequential tool calls with model inference between each one. For multi-service workflows (e.g., incident triage across PagerDuty, Datadog, Slack, Jira), this means 10+ round-trips and significant token spend. Scripting is possible today only through CLI/shell access, which is less safe and unavailable for knowledge worker use cases where agents lack a shell environment. The prototype demonstrates ~15s improvement by executing a Starlark script server-side that calls tools directly, with parallel() fan-out — without requiring shell access.
This epic production-hardens the prototype and ships it as an opt-in feature. It does NOT implement the full RFC THV-0060 session initialization model.
User Story Breakdown
| Story ID | Title | Description | Persona | Goal | Acceptance Criteria | GitHub Issue # |
|---|---|---|---|---|---|---|
| STORY-001 | Ship opt-in code mode for vMCP | As a platform engineer, I want my agents to be able to execute scripts on tools without shell access so that they can safely reduce context bloat and inference cycles | Platform engineer | Enable server-side script execution for agents | Config toggle, proper dispatch, configurable limits, timeouts, optimizer compat | |
| STORY-002 | Add observability for script execution | As a cluster operator, I want logging and metrics for script execution so that I can monitor and diagnose issues | Cluster operator | Operational visibility | Structured logs, execution metrics, telemetry integration | |
| STORY-003 | Track code mode adoption and usage | As a ToolHive developer, I want to know how many people are opting in to code mode and how many tool calls come through it so that I can gauge adoption and prioritize investment | ToolHive developer | Understand adoption | Opt-in counts, call volume comparison, telemetry pipeline |
Acceptance Criteria
- Code mode can be enabled per-VirtualMCPServer via config flag
- Agents can execute Starlark scripts with tool calls, loops, conditionals, and
parallel() - Script execution is bounded (step limits, concurrency caps, timeouts)
- Works correctly with optimizer enabled
- Observability: logs and metrics for script execution
- Adoption tracking: code mode opt-in and call volume metrics
- All linked user stories completed
References
- Prototype PR: https://github.com/stacklok/toolhive/pull/4714
- RFC THV-0060: https://github.com/stacklok/toolhive-rfcs/pull/60
- Slack thread: https://stacklok.slack.com/archives/C0AMVK58NUD/p1775761162900059
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.