feat(claude-agent-sdk): support workflow MCP servers (#335)

[jrob5756]

Closes #335.

What

The claude-agent-sdk provider declared mcp_tools=False and the factory rejected any workflow declaring runtime.mcp_servers, so authors had to choose between the built-in claude_code tool preset and their own MCP tool servers.

That was an unimplemented gap, not an upstream limitation. ClaudeAgentOptions.mcp_servers exists at the current lock (0.2.87) and as far back as the old floor pin (0.1.64), and McpStdioServerConfig / McpSSEServerConfig / McpHttpServerConfig map almost 1:1 onto Conductor's MCPServerDef.

How

_translate_mcp_servers() maps each resolved server config onto the SDK's shapes; execute() passes them via ClaudeAgentOptions.

Secrets go in a file, not argv. The SDK serializes a mcp_servers dict straight into a --mcp-config <json> command-line argument, which would publish resolved stdio env values and http/sse Authorization headers to anything that can read /proc/<pid>/cmdline. Neither copilot nor claude exposes secrets that way. The config is written to a 0600 temp file and passed by path. The write happens inside execute's try, so the finally reclaims it on every exit path; the finally also closes the SDK iterator first, so the claude subprocess is gone before its config file is.

A narrowing per-server tools: filter is refused, not ignored. The SDK's MCP config has no equivalent field, and forwarding the server unfiltered would grant more tools than declared - the same reasoning that already justifies refusing the per-agent allowlist.

Behavior change: ambient MCP config is no longer inherited

Conductor now sets strict_mcp_config unconditionally, including for workflows that declare no mcp_servers. Without this, the claude CLI still loads project .mcp.json, user-global settings, and plugin-provided servers - and permission_mode="bypassPermissions" auto-approves whatever they expose. Only servers declared in runtime.mcp_servers now attach.

Workflows that relied on Claude Code's own MCP settings must declare those servers in the workflow. Called out in the CHANGELOG.

This also makes the validator relaxation below sound: it permits tools: [] when no MCP servers are declared, on the premise that nothing attaches - which ambient config would otherwise falsify.

Out of scope

Per-agent tools: allowlists (workflow_tools_passthrough) stay False. The SDK's tools option governs built-in tools only, and allowed_tools is a permission auto-approve list rather than an availability filter - with bypassPermissions it is a no-op. Honoring an allowlist needs a permission-mode redesign, not just a name mapping. Follow-up issue.

Same for working_dir, whose in-code justification cited mcp_tools=False and had to be rewritten here.

Note the refusals fire when the first agent on this provider runs, not at conductor validate - providers are constructed lazily, and the validator does not inspect per-server tools: filters. Documented as such rather than overclaimed; adding a validator check would need a new capability field.

Drive-by fix

config/validator.py rejected tools: [] against any provider with mcp_tools=True and workflow_tools_passthrough=False, keyed off the capability rather than whether the workflow actually declared any mcp_servers - so it rejected an empty allowlist even when there was nothing to forward. This already affected aca, and would have broken examples/experimental-claude-agent-sdk.yaml the moment mcp_tools flipped. Separate CHANGELOG entry.

Review round

The second commit is review follow-up. Most significant: the config file was originally written before execute's try, so an ordinary deep output: schema leaked a credential-bearing file - once per retry attempt. Reproduced, fixed, and pinned with a regression test.

Also corrected several claims that were false as written: the >=0.2.82 pin justification (strict_mcp_config actually landed in 0.1.74 - the pin stays, the reasoning is now honest), "fails at the factory boundary", the tools: [] descriptor comment, and stale MCP-is-rejected text in README / comparison.md / aca.md / two example pins.

Verification

• make check clean; full suite 4565 passed; make validate-examples clean.
• End-to-end probe feeding a config generated by the real code path into the real bundled claude CLI: mode 0600, accepted with --strict-mcp-config, no secret leakage.
• Confirmed empirically that the config file needs the {"mcpServers": {...}} envelope - a bare mapping is rejected with mcpServers: Invalid input: expected record, received undefined.

Note for reviewers: two ty: ignore[unresolved-import] comments in claude_agent_sdk.py look unused if you install the claude-agent-sdk extra locally. They are required - CI typechecks without the extra (ci.yml:52/78).

New example

examples/claude-agent-sdk-mcp.yaml - the CLI preset and a custom MCP server in one agent.