MCP Tool Execution#

The runner service (services/runner/) delivers Agenta gateway tools (Composio/callback) to agent harnesses via the Model Context Protocol (MCP). Two transports are available depending on sandbox type 1:

• HTTP loopback (tool-mcp-http.ts) — used on local sandboxes; the runner serves a stateless JSON-RPC endpoint on 127.0.0.1.
• In-sandbox stdio shim (tool-mcp-stdio.ts) — used on remote Daytona sandboxes, where 127.0.0.1 resolves to the sandbox's own loopback and cannot reach the runner host 2.

Transport selection happens in buildSessionMcpServers() 3. Both transports advertise tools under the reserved MCP server name agenta-tools (INTERNAL_TOOL_MCP_SERVER_NAME). User-declared MCP servers are blocked from claiming this name via assertNoReservedUserMcpName() — the name is load-bearing because Claude Code permission rules are keyed against it 3.

Transport Details#

HTTP Loopback (tool-mcp-http.ts)#

startInternalToolMcpServer() mints a randomBytes(32).toString("base64url") bearer token per instance and exposes the InternalToolMcpServer interface (URL + authorizationToken + close()) 4. The token is advertised to the harness as an Authorization: Bearer <token> header in the MCP server entry 1.

Authentication is enforced via hasValidAuthorization() using crypto.timingSafeEqual — requests are rejected with 401 before the body is read, preventing untrusted input from reaching the parser 4. JSON-RPC batch requests that include a client-kind tools/call are rejected upfront with code -32600, because client tools cross a turn boundary and cannot safely participate in concurrent batch execution 1.

Handled JSON-RPC methods: initialize, tools/list, tools/call 4.

In-Sandbox Stdio Shim (tool-mcp-stdio.ts)#

A dependency-free NDJSON JSON-RPC shim bundled into the Daytona sandbox via tool-mcp-assets.ts. It implements the same three handlers and calls the runner's relay on execution 1. The shim reads its environment contract from tool-mcp-env.ts: AGENTA_AGENT_TOOLS_RELAY_DIR and AGENTA_AGENT_TOOLS_PUBLIC_SPECS_FILE 1.

Argument and Result Storage Caps#

In cold-replay transcripts, tool call arguments are never capped — approval resume instructions tell the model to re-issue calls "with the same arguments," so args must remain complete 5 6.

Tool result bodies are capped at 4,000 characters (TOOL_RESULT_RENDER_MAX_CHARS = 4000) with an [... N chars omitted] marker 5. This prevents large outputs (e.g., discover_tools dumps at 30–60 KB) from evicting earlier conversation history via tail-slicing. The default transcript window (DEFAULT_HISTORY_MAX_CHARS) is 100,000 characters, overridable via AGENTA_AGENT_HISTORY_MAX_CHARS 6.

The runner-side tool_call_update handler in tracing/otel.ts records args whenever the serialized form genuinely changes (not just once), fixing a bug where early partial deltas could suppress final argument recording 7.

Claude Code MCP Settings & Permission Gates#

For Claude Code harnesses, the runner generates .claude/settings.json with per-tool MCP permission rules using the naming convention mcp__agenta-tools__<tool_name> 8. An allow permission writes a rule that bypasses Claude's own interactive gate; ask preserves human-in-the-loop (HITL) by keeping Claude's native approval prompt 8.

The central enforcement module is services/runner/src/permission-plan.ts, which both the Pi relay gate and the Claude Code gate read from — ensuring they cannot produce conflicting decisions 8.

Permission values and semantics:

Approval decisions are keyed on stable anchors: tool spec name (relay gate) or recorded tool_call name plus a canonical args hash (Claude gate). Each decision is consumed once — a config change to deny overrides a stale approval 8.

Key Source Files#