feat(agent): run MCP tools as scripts

[Twixes]

Problem

The agent calls connected MCP tools one at a time. Anything that fans out (read 100 issues, comment on the stale ones) becomes 100 sequential round-trips, each paying full tool-call overhead and burning context. There was no way to express "loop over these results and act on each" in a single step.

Changes

Adds a capability that lets the agent write one JavaScript script that calls connected MCP tools as async functions:

const issues = await tools.linear.listIssues({ teamId })
for (const i of issues.filter((x) => x.stale)) {
  await tools.linear.createComment({ issueId: i.id, body: "bump" })
}
return { bumped: issues.length }

Two local tools sit alongside the existing signed-git tools:

• list_mcp_tools returns .d.ts-style signatures for every tools.<server>.<tool>(args), generated from each tool's MCP input schema.
• run_mcp_script takes { script, timeoutMs? } and returns { result, logs, error? }.

New module packages/agent/src/mcp-scripting/:

• client-pool.ts opens and caches MCP Clients from the session config map, with listTools / callTool and a scriptableServerNames helper.
• proxy.ts builds the lazy tools.<server>.<tool>(args) proxy and rejects on tool isError.
• runner.ts runs the script in a constrained node:vm sandbox with a wall-clock timeout and captured console.
• signatures.ts renders JSON Schema into TS-style signatures.
• tools.ts holds the two local-tool definitions.

Wiring: local-tools/registry.ts carries the scriptable MCP server map on LocalToolCtx, local-tools/index.ts registers the tools, and both the Claude and Codex adapters thread the external MCP server map through.

Build, not adopt

Evaluated Cloudflare Code Mode, @utcp/code-mode / code-mode-mcp, and mcpac. Each runs as a separate process or MCP server with its own config and credentials, and several layer in a second abstraction (UTCP). None reuse the in-process McpServerConfig map with already-resolved credentials, which is the entire integration here. Building it is a thin layer over the MCP SDK Client we already depend on, with no new runtime dependencies (only @modelcontextprotocol/sdk and zod, both already present). Full rationale in the module README.

Auth and sandbox

No new auth path. The proxy dials the exact McpServerConfig map the agent's own MCP tools use, so credentials are inherited verbatim (stdio env, http/sse headers). In-process sdk servers are excluded since they have no dialable transport. A script can only reach servers the session was already authorized for; nothing the model writes can set or escalate credentials.

The node:vm sandbox runs with an explicit-allowlist global set (tools, captured console, pure helpers) and denies require, import, process, global / globalThis, Buffer, fetch, and filesystem access. codeGeneration is disabled so eval / new Function throw. This is deliberately not a hard boundary against adversarial in-process code, which is documented as a known limitation: the script author is the same agent that already calls these tools, and cloud runs sandbox the whole agent for real isolation.

How did you test this?

Automated tests only (authored by an agent):

• 27 new tests across mcp-scripting.test.ts (20) and client-pool.integration.test.ts (7), the latter running end-to-end against a real stdio MCP server fixture. They cover proxy generation, script execution, looping/batching, timeout enforcement, error surfacing (script throw and tool isError), blocked sandbox escapes (require / process / global / Buffer / fetch / new Function), signature rendering, tool gating, stdio env propagation, and reporting of unreachable servers.
• Full packages/agent suite: 761 passing across 58 files.
• Typecheck and build both clean.

Automatic notifications

• Publish to changelog?
• Alert Sales and Marketing teams?

🤖 Agent context

Autonomy: Human-driven (agent-assisted). Michael Matloka directed the design and scope; an agent implemented and tested it. The capability is gated behind explicit local tools and reuses existing session credentials, so it adds no new auth surface.

[greptile-apps]

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
packages/agent/src/mcp-scripting/signatures.ts:104-106
`*/` sequence in tool description breaks the JSDoc comment early. Any MCP tool whose description contains `*/` (e.g. `"Computes a*/b"`) will produce output like `/** Computes a*/b */`, which closes the JSDoc at the first `*/` and leaves trailing garbage text. The model then sees malformed TypeScript that could silently misrepresent the available signatures.

```suggestion
function oneLine(text: string): string {
  return text.replace(/\s+/g, " ").trim().replace(/\*\//g, "* /");
}
```

### Issue 2 of 2
packages/agent/src/mcp-scripting/runner.ts:96-103
**Double-budget timing: total wall-clock time up to 2× `timeoutMs`**

The `run` IIFE calls `script.runInContext(context, { timeout: timeoutMs })` synchronously. This synchronous phase completes — and blocks — entirely *before* `withTimeout(run, timeoutMs)` starts its wall-clock timer. So a script with a synchronous CPU-bound loop (capped at `timeoutMs`) followed by async tool calls (capped at another `timeoutMs`) can run for nearly 2× the configured budget. At the `MAX_TIMEOUT_MS` of 120 s, that ceiling is 240 s. The `RunScriptOptions` docs and the tool's parameter description both promise a single "wall-clock budget," but the actual guarantee is two independent, sequential budgets.

_{Reviews (1): Last reviewed commit: "feat(agent): expose run_mcp_script / lis..." | Re-trigger Greptile}

[github-actions]

React Doctor found no issues in the changed files. 🎉

_{Reviewed by React Doctor for commit 5bf7d60.}

[greptile-apps]

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
packages/agent/src/mcp-scripting/runner.ts:80-81
**`setTimeout` callbacks outlive `pool.close()` and spawn leaked connections**

The sandbox receives the real Node.js `setTimeout`, so a script can schedule work that fires after `runScript` returns and after the `finally { await pool.close() }` in `tools.ts`. When that callback calls `tools.someServer.someMethod()`, `getClient` finds `this.clients` cleared but `this.configs` still populated, so it opens a brand-new connection — spawning a fresh subprocess for stdio servers or a new HTTP/SSE socket for remote ones — with no tracking and no cleanup. The tool call succeeds silently, appears in neither `logs` nor `result`, and the connection leaks until the process exits.

_{Reviews (2): Last reviewed commit: "fix(agent): single timeout budget and JS..." | Re-trigger Greptile}

[greptile-apps]

setTimeout callbacks outlive pool.close() and spawn leaked connections

The sandbox receives the real Node.js setTimeout, so a script can schedule work that fires after runScript returns and after the finally { await pool.close() } in tools.ts. When that callback calls tools.someServer.someMethod(), getClient finds this.clients cleared but this.configs still populated, so it opens a brand-new connection — spawning a fresh subprocess for stdio servers or a new HTTP/SSE socket for remote ones — with no tracking and no cleanup. The tool call succeeds silently, appears in neither logs nor result, and the connection leaks until the process exits.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/agent/src/mcp-scripting/runner.ts
Line: 80-81

Comment:
**`setTimeout` callbacks outlive `pool.close()` and spawn leaked connections**

The sandbox receives the real Node.js `setTimeout`, so a script can schedule work that fires after `runScript` returns and after the `finally { await pool.close() }` in `tools.ts`. When that callback calls `tools.someServer.someMethod()`, `getClient` finds `this.clients` cleared but `this.configs` still populated, so it opens a brand-new connection — spawning a fresh subprocess for stdio servers or a new HTTP/SSE socket for remote ones — with no tracking and no cleanup. The tool call succeeds silently, appears in neither `logs` nor `result`, and the connection leaks until the process exits.

How can I resolve this? If you propose a fix, please make it concise.

[stamphog]

The review agent couldn't reach its LLM backend — an infrastructure or credentials issue, not a problem with this PR. The Stamphog label has been kept; the review retries automatically on the next push, or re-apply the label once the backend recovers.