Add MCP server support to system agent via --mcp-config

[geoffjay]

Summary

Enable the built-in system agent (agentd-system) to use the agentd MCP server, giving it access to diagnostic tools, agent management, and service health checks natively through MCP rather than relying solely on Bash-based CLI commands.

Background

Claude Code supports --mcp-config <json> and --strict-mcp-config CLI flags that allow passing MCP server configuration at launch time as inline JSON. This avoids filesystem writes (no .mcp.json needed) and gives the orchestrator full control over which MCP servers an agent can access.

The agentd MCP server (agent mcp) runs on stdio and is configured via AGENTD_*_URL environment variables. It exposes tools for diagnostics, agent lifecycle, notifications, approvals, workflows, and service health.

Implementation Plan

1. Add mcp_servers to AgentConfig (types.rs)

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct McpServerEntry {
    pub command: String,
    pub args: Vec<String>,
    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
    pub env: HashMap<String, String>,
}

// In AgentConfig:
#[serde(default, skip_serializing_if = "Option::is_none")]
pub mcp_servers: Option<HashMap<String, McpServerEntry>>,

2. Update build_claude_command() (manager.rs)

When config.mcp_servers is Some, serialize to JSON and append CLI flags:

claude --sdk-url ... --mcp-config '<json>' --strict-mcp-config

--strict-mcp-config ensures the agent only uses explicitly provided MCP servers, ignoring any project-level .mcp.json files in the working directory.

3. Wire up system agent config (system_agents.rs)

mcp_servers: Some(HashMap::from([(
    "agentd".into(),
    McpServerEntry {
        command: "agent".into(),
        args: vec!["mcp".into()],
        env: HashMap::from([
            ("AGENTD_ORCHESTRATOR_URL".into(), "http://127.0.0.1:7006".into()),
            ("AGENTD_COMMUNICATE_URL".into(), "http://127.0.0.1:7010".into()),
            ("AGENTD_MEMORY_URL".into(), "http://127.0.0.1:7008".into()),
            ("AGENTD_NOTIFY_URL".into(), "http://127.0.0.1:7004".into()),
            ("AGENTD_ASK_URL".into(), "http://127.0.0.1:7001".into()),
            ("AGENTD_WRAP_URL".into(), "http://127.0.0.1:7005".into()),
            ("AGENTD_MONITOR_URL".into(), "http://127.0.0.1:7003".into()),
            ("AGENTD_HOOK_URL".into(), "http://127.0.0.1:7002".into()),
        ]),
    },
)])),

4. Update system agent tool policy (system_agents.rs)

Add MCP tool patterns to the AllowList. Recommended read-only/diagnostic tools:

• mcp__agentd__diagnose_system
• mcp__agentd__diagnose_agent
• mcp__agentd__diagnose_workflow
• mcp__agentd__check_service_health
• mcp__agentd__check_single_service
• mcp__agentd__check_connectivity
• mcp__agentd__get_agent
• mcp__agentd__get_agent_status_summary
• mcp__agentd__list_agents
• mcp__agentd__list_workflows
• mcp__agentd__list_pending_approvals
• mcp__agentd__get_prometheus_metrics
• mcp__agentd__get_system_metrics
• mcp__agentd__get_actionable_notifications
• mcp__agentd__list_notifications

Notably absent from the allow list (state-changing operations):

• mcp__agentd__terminate_agent
• mcp__agentd__restart_agent
• mcp__agentd__send_agent_message
• mcp__agentd__update_agent_tool_policy
• mcp__agentd__approve_tool_request / deny_tool_request

5. Migration

Add nullable mcp_servers TEXT column to the agents table (stores JSON). Alternatively, this could be stored as part of the existing config JSON if the schema supports it.

6. Update system prompt (system_agents.rs)

Add a section to SYSTEM_AGENT_PROMPT documenting the available MCP tools and when to use them vs CLI/Bash equivalents. The MCP tools should be preferred for structured data access; Bash tools remain for ad-hoc inspection.

Non-goals

• No WebSocket protocol changes needed
• No filesystem writes (.mcp.json) needed
• User-created agents do not get MCP servers by default (opt-in via API)

Acceptance Criteria

• AgentConfig supports optional mcp_servers field
• build_claude_command() emits --mcp-config and --strict-mcp-config flags
• System agent launches with the agentd MCP server attached
• System agent tool policy allows read-only MCP tools
• System agent prompt documents available MCP tools
• Migration adds mcp_servers column
• User-created agents can optionally specify MCP servers via the API
• Existing agents without MCP config continue to work unchanged

[geoffjay]

✅ Triage Complete

Field	Value
Type	enhancement
Complexity	medium
Milestone	v1.0.0 — Production Readiness (existing assignment — see note below)
Labels	enhancement, complexity:medium, needs-tests

Notes:

• No duplicates found.
• enhancement retained — adding MCP server support to the system agent is a new capability with no existing broken behavior.
• Milestone note: the existing v1.0.0 assignment has a reasonable justification (the DB migration for mcp_servers column fits Production Readiness). However, the primary purpose of this feature — enabling the system agent to use MCP diagnostic and lifecycle tools in the autonomous development workflow — aligns more closely with v0.9.0 - Autonomous Development Pipeline ("conductor agent for process orchestration, specialist agents"). Consider moving to v0.9.0 if this is intended to enable the autonomous pipeline rather than as a production hardening step.
• Complexity medium: all implementation work is within crates/orchestrator/ (types.rs, manager.rs, system_agents.rs) plus one DB migration. New McpServerEntry struct (~20 lines), build_claude_command() update (~15 lines), system agent MCP wiring with 8-entry env map (~40 lines), 15-tool allowlist additions (~20 lines), system prompt documentation (~20-50 lines). Total estimated ~110–150 lines.
• needs-tests added: 8 acceptance criteria are listed but none include tests. The build_claude_command() path (JSON serialization, --mcp-config/--strict-mcp-config flags) and the system agent launch with MCP config should have unit tests before this ships.
• No blockers: no stated prerequisites; can be picked up independently.
• Acceptance criteria are complete and the implementation plan includes code samples; no clarification needed.