agentd-mcp Service¶

The MCP (Model Context Protocol) server exposes agentd's agent management, workflow, notification, approval, and diagnostic services as tools for Claude and other MCP clients. It enables a self-healing loop: Claude can query system state, diagnose problems, and take corrective action through structured MCP tool calls.

Unlike other agentd services, agentd-mcp is not an HTTP daemon - it communicates over stdio using the MCP JSON-RPC transport and acts as a stateless bridge to the rest of the agentd fleet.

Architecture¶

MCP Client (Claude Code, Claude Desktop)
     │ JSON-RPC over stdio
     ▼
agentd-mcp
     │ HTTP/REST
     ├── orchestrator  :17006  (agents, workflows, approvals)
     ├── communicate   :17010  (rooms, messages)
     ├── memory        :17008  (vector memory store)
     ├── notify        :17004  (notifications)
     ├── ask           :17001  (approval requests)
     ├── wrap          :17005  (Docker wrap configs)
     ├── monitor       :17003  (system metrics, alerts)
     └── hook          :17002  (pre/post tool hooks)

Each tool call makes direct HTTP requests to the relevant agentd services. No local state is maintained between calls.

Quick Start¶

# Run via the agent CLI (works from any directory)
agent mcp

# Or run the standalone binary
cargo run -p agentd-mcp

# Run with MCP Inspector for development
npx @modelcontextprotocol/inspector agent mcp

MCP Client Configuration¶

Claude Code (.claude/mcp.json)¶

{
  "mcpServers": {
    "agentd": {
      "command": "agent",
      "args": ["mcp"]
    }
  }
}

Environment variable overrides can be passed if your services run on non-default ports:

{
  "mcpServers": {
    "agentd": {
      "command": "agent",
      "args": ["mcp"],
      "env": {
        "AGENTD_ORCHESTRATOR_URL": "http://127.0.0.1:17006",
        "AGENTD_NOTIFY_URL": "http://127.0.0.1:17004",
        "AGENTD_MONITOR_URL": "http://127.0.0.1:17003"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)¶

{
  "mcpServers": {
    "agentd": {
      "command": "agent",
      "args": ["mcp"]
    }
  }
}

Configuration¶

All configuration is via environment variables. Defaults target the standard localhost ports used by agentd services.

Tool Reference¶

All tools return markdown-formatted strings with severity tagging where applicable: 🔴 Critical, 🟡 Warning, 🟢 Info.

System Diagnostics¶

diagnose_system¶

Run a full system diagnostic: check all agentd services, identify failed agents, surface monitor alerts, count pending approvals and notifications. Returns a prioritized report. Tolerates partial service unavailability.

Parameters: None

Example output:

# System Diagnostic Report

## Service Health
| Service | Status |
|---|---|
| orchestrator | 🟢 Healthy |
| notify | 🟢 Healthy |
| monitor | 🔴 Unreachable |

## Issues (prioritized)
🔴 2 agents in failed state: worker-1, worker-2
🟡 5 pending approval requests blocking agents
🟢 30 notifications in backlog (12 low-priority, older than 48h)

diagnose_agent¶

Deep dive on a single agent: status, activity state, WebSocket connection, pending approval backlog, and session usage. Returns a structured report with severity-tagged issues and actionable remediation steps.

diagnose_workflow¶

Workflow health analysis: verify the associated agent is running, analyze dispatch success rate over the last 20 dispatches, and identify consecutive failure patterns.

check_connectivity¶

Test connectivity between the MCP server and all agentd services. Returns a table showing which services are reachable and which are not.

Parameters: None

Agent Inspection¶

list_agents¶

List all agents managed by agentd, optionally filtered by status. Returns a table with agent ID, name, status, and activity state.

get_agent¶

Get detailed information about a specific agent including configuration, tool policy, model, working directory, and environment variable keys (values are redacted).

get_agent_status_summary¶

Fleet-wide status counts of pending, running, stopped, and failed agents. Lists any failed agents with their IDs and names for quick identification.

Parameters: None

Workflow & Dispatch Inspection¶

list_workflows¶

List all configured workflows with trigger type, poll interval, enabled state, and associated agent.

Parameters: None

get_workflow¶

Full configuration of a workflow including trigger source config, prompt template, and tool policy.

list_dispatches¶

Dispatch records for a specific workflow showing task execution history with status and timing.

get_failed_dispatches¶

All failed dispatch records across all workflows, sorted by most recent first.

Notification Management¶

list_notifications¶

List notifications with optional filters for status and priority. Sorted by priority (highest first).

get_notification¶

Full details of a specific notification including source data, message body, and response.

get_actionable_notifications¶

All notifications that are pending or viewed and have not expired, sorted by priority (urgent first).

Parameters: None

create_notification¶

Create a system notification for flagging issues found during diagnostics or remediation.

dismiss_notification¶

Dismiss a notification, marking it as reviewed and removing it from the active backlog.

Approval Management¶

list_pending_approvals¶

All pending tool approval requests across all agents. Shows tool name, input summary, requesting agent, and expiry time.

Parameters: None

get_agent_approvals¶

Pending tool approval requests for a specific agent. Useful when diagnosing why an agent appears blocked.

approve_tool_request¶

Approve a pending tool use request, allowing the agent to proceed.

deny_tool_request¶

Deny a pending tool use request. An optional reason is sent back to the agent.

Agent Lifecycle Management¶

restart_agent¶

Restart an agent by terminating the current session and recreating it with the same configuration. Loses all in-flight work. Use on failed or stopped agents. Returns the new agent ID.

send_agent_message¶

Send a message or prompt to a running agent via the orchestrator. The agent processes the message in its current session context.

update_agent_tool_policy¶

Change an agent's tool policy to restrict or allow tool usage.

terminate_agent¶

Permanently terminate an agent. Kills the tmux session and removes the agent from the registry. All in-flight work is permanently lost.

update_agent_model¶

Change the AI model an agent is using. Takes effect for subsequent turns in the current session.

Self-Healing Remediation¶

restart_failed_agents¶

Find all agents in a failed state and restart them. For each: captures config, terminates the old session, and recreates the agent. Returns an audit report. Only targets agents already in failed state.

Parameters: None

retry_failed_dispatches¶

Retry failed dispatch records for a workflow by re-sending their prompts to the associated agent.

cleanup_stale_dispatches¶

Identify dispatch records stuck in "dispatched" state longer than the staleness threshold. This is a reporting-only tool - use restart_agent on the associated agent to unblock.

auto_approve_safe_tools¶

Automatically approve pending tool requests that match a conservative safe list of read-only tools (Read, Glob, Grep, ListFiles, WebFetch, etc.). Non-matching requests are skipped and reported.

resolve_notification_backlog¶

Bulk-dismiss pending notifications that are no longer actionable: expired ephemeral notifications and low-priority notifications older than the threshold.

Service Health & Metrics¶

check_service_health¶

Concurrent health check of all 8 agentd services. Returns a table with status, response time, and URL for each. Uses a 3-second timeout per service.

Parameters: None

check_single_service¶

Health check for a specific agentd service by name.

get_system_metrics¶

Current system metrics from the monitor service: CPU usage, memory, disk usage, and load average. Includes active alerts if any thresholds are exceeded.

Parameters: None

get_prometheus_metrics¶

Fetch and parse key Prometheus counters and gauges from a service. Supports orchestrator (agents, WebSocket, approvals) and notify (notification counts).

Troubleshooting Workflows¶

Agent Not Responding¶

1. check_service_health          → verify orchestrator is reachable
2. list_agents status=running    → confirm agent is registered
3. diagnose_agent {id}           → identify root cause (approvals? usage?)
4. get_agent_approvals {id}      → check for pending approval blocks
5. approve_tool_request {id}     → unblock if approval-gated
   - or -
6. restart_agent {id}            → restart if crashed/failed

Workflow Not Dispatching¶

1. list_workflows                → check enabled=true, find agent_id
2. get_agent {agent_id}          → verify agent status=running
3. diagnose_workflow {id}        → analyze dispatch success rate
4. list_dispatches {id} status=failed  → inspect failure details
5. retry_failed_dispatches {id}  → re-send failed prompts
   - or -
6. cleanup_stale_dispatches      → identify and unblock stuck dispatches

Full System Health Check¶

1. diagnose_system               → get prioritized issue list (🔴/🟡/🟢)
2. restart_failed_agents         → fix failed agents
3. auto_approve_safe_tools       → unblock approval-gated agents
4. cleanup_stale_dispatches      → identify stuck workflow dispatches
5. resolve_notification_backlog  → clear expired notifications
6. diagnose_system               → verify issues resolved

Notification Backlog Growing¶

1. get_actionable_notifications  → see what needs attention
2. list_notifications priority=urgent  → prioritize urgent items
3. get_notification {id}         → read full details
4. dismiss_notification {id}     → clear resolved items
   - or -
5. resolve_notification_backlog hours=24  → bulk-dismiss old low-priority

Self-Healing Automation¶

agentd-mcp is designed for the diagnose → remediate → verify loop:

Claude:
  1. diagnose_system
     → "2 failed agents, 5 stale dispatches, 30-notification backlog"
  2. restart_failed_agents
     → "Restarted: worker-agent-1, worker-agent-2"
  3. cleanup_stale_dispatches stale_hours=1
     → "5 dispatches stuck for >1h identified"
  4. resolve_notification_backlog hours=48
     → "Dismissed 25 expired/low-priority notifications"
  5. diagnose_system
     → "All systems healthy"

Safety Principles¶

• Destructive tools (restart_agent, terminate_agent, restart_failed_agents) only operate on agents already in a terminal/failed state.
• auto_approve_safe_tools uses a conservative default list of read-only tools (Read, Glob, Grep, WebFetch, etc.). Additional tools require explicit opt-in.
• cleanup_stale_dispatches is reporting-only - it identifies stuck dispatches but does not update their status. Use restart_agent on the associated agent to unblock.
• All remediation tools produce detailed audit reports of every action taken.

Escalation Pattern¶

When automated remediation is insufficient:

1. create_notification title="Agent fleet degraded" message="..." priority=urgent
2. → Notification appears in agentd dashboard for human review
3. Human reviews, takes manual action
4. dismiss_notification {id}  → mark as resolved

Development¶

# Run all tests (unit + integration)
cargo test -p agentd-mcp

# Run with verbose logging
RUST_LOG=debug cargo run -p agentd-mcp

# Format and lint
cargo fmt -p agentd-mcp
cargo clippy -p agentd-mcp

Integration tests in tests/ use lightweight axum mock servers - no running agentd services are required.