Skip to content
Python

OPE-228 headless: attach MCP servers to `openworker run`

Devika Vermafafc2ed33d15
diff --git a/coworker/headless/runner.py b/coworker/headless/runner.py
index 5d32873d..3cadae25 100644
--- a/coworker/headless/runner.py
+++ b/coworker/headless/runner.py
@@ -178,6 +178,23 @@ def parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace:
help="reasoning-effort level sent to the provider (Anthropic output_config.effort, "
"Together/Moonshot reasoning_effort). Default: nothing sent; the provider default is recorded",
)
+ p.add_argument(
+ "--mcp",
+ action="store_true",
+ help="attach MCP servers as tools for this run (off by default). Reads this "
+ "computer's mcp.json unless --mcp-config points elsewhere; for an --isolated run "
+ "that is <out>/state/mcp.json. A server's tools reach the model as "
+ "mcp__<server>__<tool>; a server that fails to connect is skipped and the run "
+ "goes on. The headless runner attaches only the global (or --mcp-config) file — a "
+ "workspace .coworker/mcp.json needs trust it does not establish.",
+ )
+ p.add_argument(
+ "--mcp-config",
+ default=None,
+ metavar="FILE",
+ help="load MCP servers from this mcpServers JSON file only, with no global or "
+ "workspace merge (implies --mcp). For a run that brings its own server config.",
+ )
p.add_argument("--scripted", default=None, help=argparse.SUPPRESS) # tests: a fake model
args = p.parse_args(argv)
# The engine's name for the mode, which is also what the record states.
@@ -703,6 +720,64 @@ def _extra_dirs(args: argparse.Namespace, workspace: Path) -> list:
return found
+def _mcp_server_defs(
+ args: argparse.Namespace, workspace: Path, secrets: Any
+) -> list:
+ """The MCP servers to attach for this run, or [] when MCP is off. `--mcp-config`
+ names one explicit file (the only source); otherwise this computer's layered config.
+ A workspace `.coworker/mcp.json` is executable provenance that needs trust the
+ headless runner does not establish, so only the global (or explicit) file is read."""
+ if not (args.mcp or args.mcp_config):
+ return []
+ from ..mcp import load_mcp_file, load_mcp_servers
+
+ if args.mcp_config:
+ return load_mcp_file(args.mcp_config, secrets=secrets)
+ return load_mcp_servers(workspace, secrets=secrets, workspace_trusted=False)
+
+
+async def _attach_mcp(engine: Any, servers: list, secrets: Any, *, on_note: Any) -> Any:
+ """Connect each enabled MCP server and register its tools on the LIVE engine.
+
+ Runs on the engine's own event loop (the `asyncio.run` loop that drives the turn),
+ so the sync→async tool bridge in `build_callables` targets the loop the tool thread
+ bridges back to. The engine reads `registry.schemas()` per turn, so tools registered
+ here are visible from the first model call. A server that fails to connect is noted
+ and skipped — the run continues without its tools. Returns the MCPManager to close
+ when the run ends, or None when nothing attached (so there is nothing to close)."""
+ from ..mcp import MCPManager, build_callables
+
+ manager = MCPManager(secrets=secrets)
+ loop = asyncio.get_running_loop()
+ attached = 0
+ for server in servers:
+ if not server.enabled:
+ continue
+ try:
+ conn = await manager.ensure(server)
+ except Exception as exc: # noqa: BLE001 - a bad server must never kill the run
+ tail = manager.last_stderr(server.name)
+ msg = f"{exc}" + (f" — {tail}" if tail else "")
+ on_note("mcp_server_failed", {"server": server.name, "error": msg[:600]})
+ continue
+ callables = build_callables(
+ server,
+ conn.tools,
+ lambda tool, a, name=server.name: manager.call(name, tool, a),
+ loop,
+ )
+ engine.registry.register_all(callables)
+ attached += len(callables)
+ on_note(
+ "mcp_server_attached",
+ {"server": server.name, "tools": [c.__name__ for c in callables]},
+ )
+ if attached == 0:
+ await manager.aclose()
+ return None
+ return manager
+
+
class UsageError(Exception):
"""The command line cannot be run as given: said on standard error, exit code 2."""
@@ -848,6 +923,17 @@ def _run(args: argparse.Namespace) -> int:
)
secrets = SecretStore(state_dir() / "secrets.json")
+ # MCP servers to attach (if any), resolved with this run's SecretStore for ${VAR}
+ # refs. Connected later, on the engine's own event loop (see guarded()).
+ mcp_servers = _mcp_server_defs(args, workspace, secrets)
+ if (args.mcp or args.mcp_config) and not mcp_servers:
+ print(
+ "openworker run: --mcp was given but no MCP servers were found in "
+ + (args.mcp_config or "this computer's mcp.json")
+ + "; the run continues with no MCP tools.",
+ file=sys.stderr,
+ flush=True,
+ )
if args.scripted:
provider = scripted_provider(Path(args.scripted))
else:
@@ -950,6 +1036,27 @@ def _run(args: argparse.Namespace) -> int:
# provisional summary, messages, and trajectory are rewritten. SIGTERM also flushes.
events_fh = (out / "events.jsonl").open("w", encoding="utf-8")
+ def _mcp_note(kind: str, data: dict[str, Any]) -> None:
+ """Record one MCP attach/fail line to the event stream and stderr."""
+ rec = {"ts": time.time(), "type": kind, "data": data}
+ events.append(rec)
+ events_fh.write(json.dumps(rec, default=str) + "\n")
+ events_fh.flush()
+ if kind == "mcp_server_failed":
+ print(
+ f"openworker run: MCP server {data.get('server')!r} failed to connect: "
+ f"{data.get('error')}",
+ file=sys.stderr,
+ flush=True,
+ )
+ else:
+ print(
+ f"openworker run: MCP {data.get('server')}: "
+ f"{len(data.get('tools') or [])} tools attached",
+ file=sys.stderr,
+ flush=True,
+ )
+
def flush_provisional(status: str) -> None:
try:
events_fh.flush()
@@ -1102,12 +1209,25 @@ def _run(args: argparse.Namespace) -> int:
break
async def guarded() -> None:
- # timeout_seconds <= 0 disables the run's own limit (an outer runner may enforce
- # its own; a second, shorter limit here would cut long tasks early).
- if args.timeout_seconds and args.timeout_seconds > 0:
- await asyncio.wait_for(consume(), timeout=args.timeout_seconds)
- else:
- await consume()
+ # MCP servers attach on THIS loop so their sync→async tool bridge targets the loop
+ # the engine runs on, and close here too (same task — the SDK's transports require
+ # enter and exit on one task). Attachment is outside the run's timeout: it is a
+ # one-time local connect, and a slow server should not eat the task's clock.
+ mcp_manager = (
+ await _attach_mcp(engine, mcp_servers, secrets, on_note=_mcp_note)
+ if mcp_servers
+ else None
+ )
+ try:
+ # timeout_seconds <= 0 disables the run's own limit (an outer runner may enforce
+ # its own; a second, shorter limit here would cut long tasks early).
+ if args.timeout_seconds and args.timeout_seconds > 0:
+ await asyncio.wait_for(consume(), timeout=args.timeout_seconds)
+ else:
+ await consume()
+ finally:
+ if mcp_manager is not None:
+ await mcp_manager.aclose()
try:
asyncio.run(guarded())
@@ -1405,8 +1525,16 @@ def _write_records(
"timeout_seconds": args.timeout_seconds,
"workspace": str(Path(args.workspace).resolve()),
"extra_dirs": [str(Path(r).expanduser().resolve()) for r in (args.add_dir or [])],
+ "mcp": bool(args.mcp or args.mcp_config),
+ "mcp_config": args.mcp_config,
"scripted": bool(args.scripted),
},
+ # MCP servers attached this run and the tools each exposed, from the attach events.
+ "mcp_servers": [
+ {"server": e["data"].get("server"), "tools": e["data"].get("tools")}
+ for e in events
+ if e["type"] == "mcp_server_attached"
+ ],
"isolation": isolation,
# The window and trigger the engine actually used: an unlisted model shows
# window null and the fallback trigger.
diff --git a/coworker/mcp/__init__.py b/coworker/mcp/__init__.py
index bfbc8df5..31ba9da9 100644
--- a/coworker/mcp/__init__.py
+++ b/coworker/mcp/__init__.py
@@ -9,6 +9,7 @@ from .client import MCPManager
from .config import (
MCPServerDef,
delete_global_server,
+ load_mcp_file,
load_mcp_servers,
patch_global_server,
put_global_server,
@@ -20,6 +21,7 @@ __all__ = [
"MCPManager",
"MCPServerDef",
"load_mcp_servers",
+ "load_mcp_file",
"read_global",
"put_global_server",
"patch_global_server",
diff --git a/coworker/mcp/config.py b/coworker/mcp/config.py
index a0c211df..1b0eb323 100644
--- a/coworker/mcp/config.py
+++ b/coworker/mcp/config.py
@@ -109,6 +109,26 @@ def load_mcp_servers(
return [_parse(name, raw, secrets) for name, raw in merged.items()]
+def load_mcp_file(
+ path: str | Path, *, secrets: Optional[SecretStore] = None
+) -> list[MCPServerDef]:
+ """Parse the `mcpServers` map from ONE explicit JSON file — no global/workspace merge.
+
+ For a caller that points at a specific config rather than this computer's layered one
+ (the headless runner's ``--mcp-config``, e.g. a benchmark's own mcp.json). ``${VAR}``
+ refs resolve the same way as in ``load_mcp_servers``; a missing or malformed file
+ yields no servers. The file is the sole source, so the workspace-trust gate does not
+ apply — the caller chose this path explicitly.
+ """
+ secrets = secrets or SecretStore()
+ raw = _read(Path(path).expanduser())
+ return [
+ _parse(name, cfg, secrets)
+ for name, cfg in (raw.get("mcpServers") or {}).items()
+ if isinstance(cfg, dict)
+ ]
+
+
# -- raw global-file mutation (REST) -------------------------------------------
def read_global() -> dict[str, dict[str, Any]]:
"""Raw `mcpServers` map from the global file (no `${VAR}` resolution)."""
diff --git a/tests/test_headless_mcp.py b/tests/test_headless_mcp.py
new file mode 100644
index 00000000..e0a4898b
--- /dev/null
+++ b/tests/test_headless_mcp.py
@@ -0,0 +1,128 @@
+"""`openworker run --mcp`: the headless runner attaches MCP servers as tools.
+
+End to end with a scripted fake model (no network, no keys) and a REAL stdio MCP server —
+a tiny FastMCP `echo` server spawned as a subprocess, so the whole path is exercised:
+connect, list tools, register on the live engine, the model calls the tool, the grader-style
+result comes back. Run in a subprocess for the same reason as test_headless_run: the runner
+redirects OpenWorker's state/scratch folders before the engine is built.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+# A minimal stdio MCP server with one tool. Only depends on the `mcp` SDK, so it starts fast.
+ECHO_SERVER = """\
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("echo")
+
+
+def ping(text: str) -> str:
+ return f"pong:{text}"
+
+
+if __name__ == "__main__":
+ mcp.run()
+"""
+
+
+def _env() -> dict:
+ env = dict(os.environ)
+ env["PYTHONPATH"] = str(ROOT) + os.pathsep + env.get("PYTHONPATH", "")
+ env.pop("ANTHROPIC_API_KEY", None)
+ env.pop("OPENAI_API_KEY", None)
+ env.pop("COWORKER_SCRATCH_BASE", None)
+ env["COWORKER_STATE_DIR"] = tempfile.mkdtemp(prefix="ow-run-machine-")
+ return env
+
+
+def _write(path: Path, text: str) -> Path:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(text, encoding="utf-8")
+ return path
+
+
+def _run(tmp_path: Path, script: list[dict], servers: dict) -> tuple[subprocess.CompletedProcess, Path]:
+ ws = tmp_path / "ws"
+ ws.mkdir(exist_ok=True)
+ out = tmp_path / "out"
+ script_path = _write(tmp_path / "script.json", json.dumps(script))
+ mcp_path = _write(tmp_path / "mcp.json", json.dumps({"mcpServers": servers}))
+ cmd = [
+ sys.executable, "-m", "coworker.cli", "run",
+ "--prompt", "Use the echo tool.",
+ "--workspace", str(ws), "--model", "anthropic/claude-sonnet-5",
+ "--approval-mode", "bypass-approvals", "--out", str(out),
+ "--scripted", str(script_path),
+ "--mcp-config", str(mcp_path),
+ "--isolated", "--timeout-seconds", "120",
+ ]
+ proc = subprocess.run(cmd, env=_env(), capture_output=True, text=True, timeout=300)
+ return proc, out
+
+
+def _events(out: Path) -> list[dict]:
+ return [
+ json.loads(line)
+ for line in (out / "events.jsonl").read_text(encoding="utf-8").splitlines()
+ if line.strip()
+ ]
+
+
+def _summary(out: Path) -> dict:
+ return json.loads((out / "summary.json").read_text(encoding="utf-8"))
+
+
+def test_mcp_tool_attached_and_callable(tmp_path: Path) -> None:
+ """A real stdio MCP server's tool is attached and the scripted model calls it; its
+ result lands in the record and the run completes."""
+ server = _write(tmp_path / "echo_server.py", ECHO_SERVER)
+ script = [
+ {"text": "Calling echo.", "tool_calls": [{"name": "mcp__echo__ping", "arguments": {"text": "hi"}}]},
+ {"text": "Got the result. Done.", "usage": {"input": 100, "output": 20}},
+ ]
+ proc, out = _run(
+ tmp_path,
+ script,
+ {"echo": {"command": sys.executable, "args": [str(server)], "requires_approval": False}},
+ )
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+
+ summary = _summary(out)
+ assert summary["outcome"] == "completed"
+ assert summary["args"]["mcp"] is True
+ # The attach is recorded with the server and its tool.
+ assert summary["mcp_servers"] == [{"server": "echo", "tools": ["mcp__echo__ping"]}]
+
+ events = _events(out)
+ assert any(e["type"] == "mcp_server_attached" and e["data"]["server"] == "echo" for e in events)
+ # The tool call ran against the real server and returned the pong.
+ finished = [e for e in events if e["type"] == "tool_finished" and e["data"].get("name") == "mcp__echo__ping"]
+ assert finished and finished[0]["data"]["status"] == "ok", events
+ assert "pong:hi" in (out / "messages.json").read_text(encoding="utf-8")
+
+
+def test_mcp_server_failure_is_noted_and_run_continues(tmp_path: Path) -> None:
+ """A server that cannot start is noted and skipped; the run still completes."""
+ script = [{"text": "Nothing to do. Done.", "usage": {"input": 100, "output": 20}}]
+ proc, out = _run(
+ tmp_path,
+ script,
+ {"nope": {"command": "ow-no-such-command-xyz", "args": [], "requires_approval": False}},
+ )
+ assert proc.returncode == 0, proc.stdout + proc.stderr
+
+ summary = _summary(out)
+ assert summary["outcome"] == "completed"
+ assert summary["mcp_servers"] == [] # nothing attached
+ events = _events(out)
+ assert any(e["type"] == "mcp_server_failed" and e["data"]["server"] == "nope" for e in events)