feat(mcp-tool-proxy): private MCP integration via per-tool SLXs

[theyashl]

Summary

• New codebundles/mcp-tool-proxy/ that proxies a single MCP tool call: Python script does initialize + tools/call (handles both JSON and SSE responses), Robot wrapper dynamically imports per-tool parameters from MCP_INPUT_SCHEMA.
• Generation rule + SLX/Runbook templates render one SLX + Runbook per discovered mcp_tool resource. Generated SLXs carry platform: mcp, resource_name: {server}, resource_type: mcp_server, mcp_server: {server}, mcp_tool: {tool} tags, an additionalContext.hierarchy: [platform, mcp_server, mcp_tool] for grouping in the platform UI, and an access tag rendered from spec.access (per-tool, classified by the indexer; defaults to read-write when absent).
• SLX alias is rendered as <server> - <tool> (dash separator); the runbook task name is <server>_<tool>. Both surface the server scope alongside the tool name so the UI doesn't show 37 anonymous "list_*" tasks.
• SLX template sets additionalContext.resourcePath: mcp/<server> (2 keys) — distinct from the 3-key hierarchy. UI grouping uses hierarchy; resource addressing uses resourcePath. Requires the paired compute_resource_path_from_hierarchy change in runwhen-local#798 so the explicit value isn't overwritten.
• Runtime var defaults from the MCP input schema are always rendered as YAML strings — numbers/bools/lists/dicts are JSON-encoded first (so 42 becomes "42", true becomes "true", [1,2,3] becomes '"[1, 2, 3]"'). Robot Framework treats runtime vars as strings; un-coerced defaults caused type-mismatch failures in the runner.
• Required parameters from the schema's top-level required array get a (required) suffix appended to their rendered description ("Required parameter." as a fallback when the schema description is empty), so downstream UI/agent surfaces know which inputs are mandatory.
• Tool args from agentfarm arrive as strings (Robot's Import User Variable always returns string); the proxy coerces them to the JSON-Schema types in MCP_INPUT_SCHEMA before tools/call so boolean/integer/number/array/object parameters don't trip the MCP server's input validator.
• Error policy split: transport / initialize failures exit 1 (task fails); tools/call errors and result.isError=true are surfaced as task output (rc=0) so agentfarm can read and react to them.
• Templates use | tojson for any value sourced from upstream MCP descriptions/defaults (which may contain colons, control characters, or newlines), and the standard labels: \n {% include "common-labels.yaml" %} pattern so the SLX YAML always parses cleanly.
• Pairs with runwhen-local#798 (the mcp_tools indexer that drives this codebundle from Helm-provided mcpConfig values).

Design spec: docs/superpowers/specs/2026-05-20-private-mcp-integration-design.md.

Configuring MCP servers

MCP servers are declared on the workspace-builder side, not in this codecollection — see codebundles/mcp-tool-proxy/README.md for the full configuration example. Short version:

runwhenLocal:
  workspaceBuilder:
    workspaceInfo:
      configMap:
        data:
          mcpConfig:
            servers:
              - display_name: jira
                url: https://jira-mcp.internal:443/mcp
                secret_ref: jira-mcp-token

secret_ref points to a k8s Secret with data.token: <bearer>. The same secret must be reachable from runner pods at execution time (the generated Runbook references it via secretsProvided.workspaceKey).

Optional per-server verify_tls: false skips TLS verification for environments where the pod's CA bundle doesn't yet trust the MCP server's issuer.

Test Plan

• Python unit tests: cd codebundles/mcp-tool-proxy && PYTHONPATH=. .venv/bin/pytest tests/ -v — 22 pass + 1 skip (JSON-RPC envelope parsing, SSE handling, tool output rendering, error envelopes, transport failures, JSON-Schema arg coercion)
• Robot file parses: from robot.api import get_model; get_model('runbook.robot') clean
• Generation rule validates against runwhen-local's generation-rule-schema.json
• SLX + Runbook templates render against a synthetic mcp_tool resource with realistic tool descriptions (colons, newlines, embedded quotes) — asserts on tags, additionalContext, runtimeVarsProvided validation blocks, string-coerced defaults, (required) suffix on mandatory params, configProvided
• Local dry-run (./.test/dry-run.sh) — stub MCP server + script round-trip; bypasses Robot since RW.Core ships only in the runner image (documented in .test/README.md)
• End-to-end inside a real workspace-builder pod against https://mcp.test.runwhen.com/mcp: 37 MCP tools discovered, 37 SLX + Runbook pairs rendered and uploaded to PAPI

Out of scope (deferred follow-ups)

• Production CA-bundle distribution to remove the temporary verify_tls: false escape hatch (tracked in RW-1146)

🤖 Generated with Claude Code