mcphost

Overview ¶

config.go (v2.7 b3-ii, ADR-0049) — the pure `--mcp-config` generation helper. claude's `--mcp-config` expects a JSON object with a top-level `mcpServers` map; each entry is launched as `command` + `args` with the given `env`. This mirrors the canonical stdio MCP server config shape (the same {mcpServers:{<name>:{command,args,env}}} shape claude consumes, and the generic JSON the worker daemon's MCPInjector walks in home_dir/mcp_config.json).

This is a PURE function: it takes the launch command + args + binding params and returns the bytes. It does NO I/O and hard-codes NO binary path (the caller / D2-c supplies command + args). D2-c writes the bytes to disk and passes --mcp-config to claude.

The env keys are the exact ones runMCPHost (handlers_mcphost.go) reads:

AC_MCP_AGENT_ID           operating agent id (process-fixed)
AC_MCP_ADMIN_URL          admin endpoint (unix:/path or tcp://host:port)
AC_MCP_WORKER_TOKEN       worker bearer token (owner worker:<id>)
AC_MCP_SERVER_FINGERPRINT pinned cert fingerprint (required for tcp://)
AC_MCP_AGENT_ROOT         agent workspace root (file-tool containment)
AC_MCP_RUNTIME_SOCKET    local agent-runtime control socket
AC_MCP_TIER_TOOLS         optional bool; false exposes the full catalog
AC_MCP_GENERATION         supervisor generation that owns this host process

files.go (v2.7 b3-ii, ADR-0049) — the per-agent MCP file tools. Two of the three move BYTES (upload_file / download_file) through the FileMover seam (the daemon-side FileTransferClient, which enforces workspace path containment); attach_file is a pure JSON passthrough to the admin endpoint.

Security spine (same as every other tool): agentRoot + agentID are process-fixed — taken from Config, NEVER from tool args — so the model can neither move files for another agent nor reach outside the agent's workspace. The args structs deliberately carry NO agent_id / agent_root.

Error mapping: the FileMover returns PLAIN errors (workspace path-escape, not-reachable, admin non-2xx, etc.) rather than the typed *AdminToolError that callAdmin understands. To let claude see the actual reason (e.g. "path escapes workspace root") and self-correct rather than treating it as a transport failure, file-mover errors are surfaced as an IsError CallToolResult carrying err.Error() (see fileError). attach_file, being a callAdmin passthrough, reuses callAdmin's existing *AdminToolError → IsError mapping.

orchestration_tools.go — MCP handler factories for the orchestration engine tools (P2-T2). Every handler follows the b3-i pattern EXACTLY: a typed args struct with NO agent_id field, a handler that injects the process-fixed agent_id from cfg.AgentID and forwards via callAdmin to the matching /admin/agent-tools/<tool> endpoint.

Package mcphost implements the per-agent stdio MCP server (v2.7 b3-i, ADR-0049). One `mcp-host` process is bound to exactly ONE agent: it bridges MCP tool calls from a claude process to the center's admin agent-tool HTTP endpoints (/admin/agent-tools/<tool>).

Security spine (mirrors internal/admin/api requireAgentOnWorker): the operating agent_id is PROCESS-FIXED — it comes from Config.AgentID (sourced from the AC_MCP_AGENT_ID env by the subcommand), and is injected into every admin call body. It is NEVER taken from the model's tool args, so the model cannot act as another agent. The worker bearer token (owner worker:<id>) rides the AdminCaller transport; the center re-checks requireAgentOnWorker + per-agent domain authz on every call.

Built on the official MCP Go SDK (github.com/modelcontextprotocol/go-sdk @v1.6.1). b3-i ships 2 representative tools (get_my_work + post_task_message) to prove the shape; the full tool set + file tools + config generation are b3-ii.

tools.go (v2.7 b3-ii, ADR-0049) — the remaining OQ4 JSON passthrough tools completing the per-agent MCP surface on top of the locked b3-i form (server.go). Every handler follows the b3-i pattern EXACTLY: a typed In struct with NO agent_id field, a handler that injects the process-fixed agent_id from cfg.AgentID and forwards via callAdmin to the matching /admin/agent-tools/<tool> endpoint. The MCP tool name equals the admin route's <tool> segment (callAdmin POSTs to /admin/agent-tools/<tool>), so the registration name and the callAdmin tool string must stay in lockstep.

Admin request field names are matched VERBATIM to the handlers in internal/admin/api/agent_tools_passthrough.go + agent_tools_write.go:

• assign_task / reassign_task : {task_id, assignee}
• subscribe / unsubscribe : {task_id, identity?} (defaults to self)
• fail_task : {task_id, reason}
• retry_failed_task : {task_id}
• heartbeat : {task_id}
• complete_task : {task_id, summary?}
• discard_task : {task_id, reason}
• create_task : {project_id, title, description?, derived_from_issue?, assignee?, dispatch?, dispatch_mode?}
• update_task : {task_id, title?, description?, clear_description?}
• fork_executor : runtime-local {task_id, model?, context?}
• get_task : {task_id}
• get_issue : {issue_id}
• verify_task : {task_id}