017: MCP Proxy via Per-Step stdio Subprocess for Tool Interception

Status: Accepted Date: 2026-05-23 Issue: F099 Supersedes: N/A Superseded by: N/A

Context#

AWF orchestrates AI agents (Claude, Gemini, Codex, OpenCode, OpenAI Compatible) that invoke file system and shell tools as part of workflow execution. Currently those tool calls are entirely opaque to AWF: the agent CLI receives a prompt, runs, and returns output — AWF cannot intercept, audit, or extend the tool set the agent uses.

F099 must solve three problems simultaneously:

1. Interception: Make AWF’s 6 built-in tools (Read, Write, Edit, Bash, Glob, Grep) available to agents via a structured protocol, so that tool calls are observable and auditable (OTel spans, structured logs).
2. Extension: Allow AWF gRPC plugins (existing ports.OperationProvider implementations) to expose their operations as agent tools without agents knowing about AWF’s plugin model.
3. Multi-provider support: The mechanism must work across five agents with different injection APIs — four stdio CLIs and one HTTP provider — without requiring provider-specific tool-call logic in the domain or application layers.

Two protocol-level questions are load-bearing beyond this feature:

• Which protocol governs the host–agent tool call contract? The answer locks in an external-facing API that plugin SDK authors and workflow authors will depend on.
• What process topology delivers that protocol? The answer determines crash isolation, subprocess lifecycle complexity, and client compatibility across all five providers.

Candidates#

Protocol#

Process Topology#

Decision#

Protocol: Adopt MCP 2024-11-05 (latest stable as of 2026-01-01). Implement only the required subset: initialize, initialized, tools/list, tools/call, shutdown. Prompts, resources, notifications/progress, and sampling are out of scope and deferred.

Process topology: Option B — per-step subprocess awf mcp-serve. One awf mcp-serve process is spawned per step where mcp_proxy.enable: true. The subprocess serves MCP over stdin/stdout. The parent awf run process spawns it via ToolProxyService.Start() and tears it down via ToolProxyService.Close().

Server implementation: The MCP server implementation initially lived in pkg/mcpserver/ but was migrated to internal/infrastructure/mcp/ in F104 to adopt the official github.com/modelcontextprotocol/go-sdk (see ADR 019). The adapter wraps the official SDK while maintaining identical user-facing behavior and continues to enforce zero internal/ imports at the adapter boundary via lint rules and AST-based architecture tests.

OpenAI Compatible exception: The HTTP provider cannot use stdio; instead, ToolRouter is invoked in-process and its tool definitions are injected as tools[] in the Chat Completions request. This is an explicit split: stdio providers use subprocess MCP, HTTP provider uses in-process tools[].

Key rules established:

• pkg/mcpserver depends on Go stdlib only — no internal/ imports, no framework deps.
• ToolProvider port in domain; BuiltinToolProvider + PluginToolAdapter in infrastructure; ToolRouter + ToolProxyService in application.
• Tool names follow <plugin>_<op> (snake-case, single underscore) to satisfy MCP client name constraints. Dots are forbidden (Claude rejects them).
• Collision detection is fatal at step startup (registration time), not at call time.
• Subprocess lifecycle uses goroutine + buffered channel + 5s SIGTERM→SIGKILL deadline, matching RPCPluginManager.connectWithTimeout exactly.
• awf mcp-serve is Hidden: true — not user-facing; no stability guarantees independent of AWF binary version.
• USER.MCP_PROXY.* validation codes extend the error taxonomy (exit code 1) with six new codes: UNKNOWN_KEY, UNKNOWN_PLUGIN, UNKNOWN_OPERATION, NAME_COLLISION, EMPTY_PROXY, UNSUPPORTED_PROVIDER.

Consequences#

What becomes easier:

• Tool calls from all five agent providers are observable: each tools/call produces an OTel span and a structured zap log line.
• AWF gRPC plugins can expose operations to agents with no changes to the plugin manifest — PluginToolAdapter wraps the existing ports.OperationProvider.
• New tools can be added by implementing ports.ToolProvider without touching any agent provider code.
• External consumers can embed pkg/mcpserver to build custom MCP-enabled tooling.
• Subprocess crash isolation: a panic in awf mcp-serve is visible to the parent as a subprocess exit error but does not crash awf run.

What becomes harder:

• Each step with mcp_proxy.enable: true spawns an extra Go process (~10 MB RSS). At AWF’s current scale this is acceptable; at high parallelism it requires monitoring.
• Codex and OpenCode have no --tools "" equivalent. Built-in tools cannot be disabled via flag injection; the proxy coexists with native tools and emits a startup WARN log. This is an accepted limitation documented in the YAML validation.
• MCP protocol version upgrades require coordinated changes to pkg/mcpserver, the hidden mcp-serve subcommand, and the per-provider config injection. The committed MCP version (2024-11-05) becomes the wire contract.
• pkg/mcpserver becoming public means adding new MCP methods (e.g., notifications/progress) is a semver-visible change.
• The OpenAI Compatible provider requires a separate in-process tools path (tools[] + tool_choice + multi-turn tool-call loop), maintained in parallel with the stdio subprocess path.

Constitution Compliance#