MCP server for orchestrating AI agents (Claude and Codex) with task graph execution, session management, and event-driven async operations
agents-mcp provides comprehensive tool definitions with mostly complete schemas and descriptions, but has several quality gaps. Tools are well-named with action verbs (claude, codex, continue_agent, task_graph, poll_events, wait_for_event, cleanup, get_agent_status, list_agents, list_sessions, get_agent_state, get_agent_output). All 12 tools have descriptions and input schemas with typed parameters. However, output schemas are not documented, tools return generic {content: Array<{type, text}>} without specifying what fields agents can rely on for downstream calls. Several parameter descriptions lack detail on constraints and valid ranges. Error handling is present but not systematically documented. The composition is reasonable: tools are mostly single-responsibility (send prompt, poll status, manage sessions), but several stateful tools (claude, codex, continue_agent) rely on session management that isn't clearly explained to callers.
Claude Code for deep analysis, architecture review, and debugging. model MUST be 'opus' or 'sonnet' (do NOT use raw model names). Always pass pwd as workDir.
Kill agent sessions belonging to this squad server. Pass workDir to only clean sessions of that project; WITHOUT workDir it kills ALL sessions of this server — on a shared (gateway) server that includes other clients' sessions, so prefer passing workDir.
Codex (gpt-5.5) for technical analysis, code review, debugging, and implementation. model MUST be 'medium' or 'xhigh' (reasoning effort). medium = quick tasks, xhigh = deep analysis with parallel agent orchestration. Always pass pwd as workDir.
Send a follow-up message to an already running agent session without reselecting the provider-specific tool.
Capture the recent tmux pane output for an agent to debug readiness prompts, stalls, or unexpected UI state.
Summarize an agent's live tmux pane into a semantic state such as awaiting confirmation, responding, or ready for input.
Output schemas not documented. Tools return generic {content: Array<{type, text}>} but do not specify what structured fields downstream tools should expect. For example, task_graph returns graphId and outputFile in a JSON string inside the text field, forcing LLMs to parse unstructured JSON from text. Async operations (continued via poll_events/wait_for_event) lack clear event schema documentation.
Parameter constraint details missing. The 'waitForResponse' parameter in claude, codex, continue_agent lacks information about what happens when false, where results are written, how to retrieve them, timeout behavior. The 'timeoutMs' in wait_for_event lacks min/max constraints. The 'lines' parameter in get_agent_state and get_agent_output lacks guidance on reasonable ranges (100-500?). The 'maxConcurrency' in task_graph has a default but no documented min/max bounds.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 55 | 2026-07-28+ | v2 |
| 2026-03-09 | D | 55 | - | v1 |
Get the current status of a specific agent (connection state, tmux session, last activity, pending events).
List all available agent presets with live sessions (one per workDir), pending events, and effective command/model details.
List active tmux sessions owned by this MCP instance with workDir and activity timestamps.
Poll for pending events from a specific agent. Returns tool completions, session idle, errors, etc.
Submit a multi-step research plan as a DAG (directed acyclic graph). Squad executes tasks respecting dependencies: independent tasks run in parallel, dependent tasks wait for their inputs. Results from parent tasks are passed as context to children. Final aggregated output is written to a file. Always non-blocking — returns immediately with graphId and outputFile.
Wait for a specific event type from an agent (blocking call with timeout).
Error handling not systematically documented. Tools return success/error responses, but error responses do not include recovery guidance. For example, if a workDir is invalid or a session does not exist, what should the LLM try next? Should it create a session, list available sessions, or fail? No recovery guide patterns are evident.
Stateful session management not clearly exposed. The claude, codex, and continue_agent tools manage persistent tmux sessions per workDir. Callers must understand that multiple calls to the same agent with the same workDir share state, and that async operations (waitForResponse: false) require subsequent poll_events/wait_for_event calls. This multi-step stateful interaction is underspecified in descriptions, agents may not realize they need to maintain session context across calls.
Async operation semantics unclear. When waitForResponse is false, tools return immediately with metadata (graphId, requestId, outputFile) but the exact file format and timing of writes is not documented. How long until the result is available? What happens if the file does not exist yet when the LLM tries to read it? Should retry logic include backoff?
cleanup tool lacks safety guidance. The description warns that cleanup without workDir kills ALL sessions, but does not recommend a confirmation step or document what happens to in-flight requests. A destructive operation this broad should support a dry-run or require explicit confirmation.
list_agents and list_sessions return unspecified structures. Descriptions say they return agent presets with status and pending events, but the output schema (fields, data types, nesting) is not documented. LLMs cannot plan downstream tool calls if they do not know whether to expect an array of objects with an 'id' field vs 'name' vs some other structure.
task_graph DAG execution semantics underspecified. The tool description says results from parent tasks are 'prepended automatically' as context to children, but the exact format (JSON? markdown? raw text?) and how to reference parent results in the child message are not documented. This forces agents to guess or waste a call experimenting.