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, pending approval backlog, session usage, and backend-specific health. For each agent, branches on backend_type (docker, subprocess, pty, tmux) and cross-checks the wrap service to detect mismatches between orchestrator state and the actual backend session.

diagnose_workflow¶

Workflow health analysis with trigger-type-specific notes. Verifies the associated agent is running, analyzes dispatch success rate, and adds guidance based on the workflow trigger (cron, webhook, agent_lifecycle, agent_idle, dispatch_result, delay, manual, github_issues, github_pull_requests, linear_issues).

diagnose_state_mismatches¶

Detect orchestrator state mismatches: agents that are running but have no WebSocket, agents connected but not running, and orphan WebSocket connections with no database record. Highest-value tool for catching subtle agent stuckness.

Parameters: None

inspect_queue¶

Inspect a named orchestrator queue. Returns counts (pending, processing, completed, failed, dead) and peeks at the next N pending tasks with retry counts. Use to diagnose queue backpressure or stuck workflow triggers.

get_conversation_summary¶

Per-event-type counts, session count, and first/last event timestamps for an agent's conversation. Cheap productivity check without loading full transcripts.

Communicate: Rooms & Messages¶

list_rooms¶

List rooms in the communicate service.

get_room¶

Get a room's metadata plus its full participant list.

list_messages¶

Recent messages in a room with sender, status, and content preview.

send_room_message¶

Post a message to a room. The sender must be a participant. Useful for remediation flows where the system or an admin agent posts a coordination update.

Memory¶

search_memories¶

Semantic search across stored agent memories.

list_memories¶

List memories with metadata filters.

get_memory¶

Fetch a single memory's full content and metadata.

Projects¶

list_projects¶

List projects grouping agents and workflows.

get_project¶

Project details including counts of associated agents and workflows.

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 any agentd service. Highlights operational metrics specific to each service (agents, approvals, notifications, memories, rooms, system resources, etc.).

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.